ForcePilot/backend/package/yuxi/external_systems/integrations/jira/metadata.py

"""Jira / Confluence 厂商集成元数据。

定义 ``IntegrationMetadata(key="jira", ...)`` 与 ``IntegrationMetadata(key="confluence", ...)``
两个实例，由 ``__init__.py`` 自注册到 ``IntegrationRegistry``。元数据为内存态，不持久化到数据库。

同时定义 Atlassian Cloud / Data Center 的 API 端点常量、OAuth 端点常量、路径模板等，
供 ``operations.py`` / ``generators.py`` 复用。

Cloud vs Data Center 路径差异（见设计文档 §1 / §4）：

| 维度 | Cloud | Data Center |
| --- | --- | --- |
| Jira API 版本 | v3 | v2 |
| Confluence API 版本 | v2 | v1（``/rest/api``） |
| Jira REST 根路径（Basic Auth） | ``https://<site>.atlassian.net/rest/api/3`` | ``https://<host>:<port>/[context]/rest/api/2`` |
| Jira REST 根路径（OAuth 3LO） | ``https://api.atlassian.com/ex/jira/{cloudId}/rest/api/3`` | 无（DC 不需要 cloudId） |
| Confluence REST 根路径（Basic Auth） | ``https://<site>.atlassian.net/wiki/rest/api/v2`` | ``https://<host>:<port>/[context]/rest/api`` |
| Confluence REST 根路径（OAuth 3LO） | ``https://api.atlassian.com/ex/confluence/{cloudId}/wiki/rest/api/v2`` | 无 |
"""

from __future__ import annotations

from yuxi.external_systems.integrations.schemas import IntegrationMetadata

# ── OAuth 2.0 (3LO) 端点常量 ──────────────────────────────────────────────
CLOUD_AUTHORIZE_URL = "https://auth.atlassian.com/authorize"
CLOUD_TOKEN_URL = "https://auth.atlassian.com/oauth/token"
CLOUD_ACCESSIBLE_RESOURCES_URL = "https://api.atlassian.com/oauth/token/accessible-resources"

# ── Atlassian OAuth 代理地址前缀 ──────────────────────────────────────────
CLOUD_OAUTH_PROXY_BASE = "https://api.atlassian.com/ex"

# ── 健康检查推荐路径 ──────────────────────────────────────────────────────
JIRA_CLOUD_HEALTH_CHECK_PATH = "/rest/api/3/myself"
JIRA_DC_HEALTH_CHECK_PATH = "/rest/api/2/myself"
CONFLUENCE_CLOUD_HEALTH_CHECK_PATH = "/wiki/rest/api/v2/user/current"
CONFLUENCE_DC_HEALTH_CHECK_PATH = "/rest/api/user/current"

# ── Jira 元数据发现路径模板 ───────────────────────────────────────────────
JIRA_PROJECTS_PATH = "/rest/api/{api_version}/project"
JIRA_PROJECT_DETAIL_PATH = "/rest/api/{api_version}/project/{project_id_or_key}"
JIRA_ISSUE_TYPES_PATH = "/rest/api/{api_version}/issue/createmeta/{project_id_or_key}/issuetypes"
JIRA_ISSUE_TYPE_FIELDS_PATH = "/rest/api/{api_version}/issue/createmeta/{project_id_or_key}/issuetypes/{issue_type_id}"
JIRA_FIELDS_PATH = "/rest/api/{api_version}/field"
JIRA_STATUSES_PATH = "/rest/api/{api_version}/status"

# ── Jira Issue CRUD 路径模板 ──────────────────────────────────────────────
JIRA_ISSUE_CREATE_PATH = "/rest/api/{api_version}/issue"
JIRA_ISSUE_GET_UPDATE_PATH = "/rest/api/{api_version}/issue/{issue_id_or_key}"
JIRA_ISSUE_TRANSITIONS_PATH = "/rest/api/{api_version}/issue/{issue_id_or_key}/transitions"
JIRA_SEARCH_CLOUD_PATH = "/rest/api/{api_version}/search/jql"
JIRA_SEARCH_DC_PATH = "/rest/api/{api_version}/search"

# ── Confluence 元数据发现路径模板 ─────────────────────────────────────────
CONFLUENCE_CLOUD_SPACES_PATH = "/wiki/rest/api/v2/spaces"
CONFLUENCE_DC_SPACES_PATH = "/rest/api/space"

# ── Confluence 页面 CRUD 路径模板 ─────────────────────────────────────────
CONFLUENCE_CLOUD_PAGES_PATH = "/wiki/rest/api/v2/pages"
CONFLUENCE_CLOUD_PAGE_DETAIL_PATH = "/wiki/rest/api/v2/pages/{id}"
CONFLUENCE_CLOUD_SEARCH_PATH = "/wiki/rest/api/v2/search"
CONFLUENCE_DC_CONTENT_PATH = "/rest/api/content"
CONFLUENCE_DC_CONTENT_DETAIL_PATH = "/rest/api/content/{id}"
CONFLUENCE_DC_SEARCH_PATH = "/rest/api/content/search"

# ── IntegrationMetadata 定义 ──────────────────────────────────────────────

_CONNECTION_EXTRA_SCHEMA: dict = {
    "type": "object",
    "properties": {
        "deployment_mode": {
            "type": "string",
            "enum": ["cloud", "data_center"],
            "default": "cloud",
            "description": "部署模式：cloud 或 data_center",
        },
        "site_url": {
            "type": "string",
            "description": "Cloud 站点 URL（API token 场景），如 https://myorg.atlassian.net",
        },
        "base_url": {
            "type": "string",
            "description": "DC 实例根 URL，如 https://jira.example.com:8443/context",
        },
        "api_version": {
            "type": "string",
            "enum": ["v2", "v3"],
            "default": "v3",
            "description": "API 版本：Cloud 用 v3，DC 用 v2",
        },
        "product": {
            "type": "string",
            "enum": ["jira", "confluence"],
            "default": "jira",
            "description": "Atlassian 产品：jira 或 confluence",
        },
        "cloud_id": {
            "type": "string",
            "description": "Cloud 3LO 场景的 cloudId（首次授权时解析，可手动指定用于多站点校验）",
        },
    },
    "required": ["deployment_mode"],
}

_DEPENDENCY_NOTE = (
    "Cloud 3LO（jira_cloud_3lo）推荐用于生产环境，自动解析 cloudId。"
    "Cloud API token（basic）2024-12-15 起新 token 默认 1 年过期，旧 token 在 2026-03-14 至 2026-05-12 间过期，需定期更换。"
    "DC 需 Jira 8.4+（分步 createmeta 端点）；PAT 需 Jira 8.14+ / Confluence 7.9+。"
    "DC OAuth2（oauth2_authorization_code）需框架补齐 PKCE 支持，当前建议 DC 场景使用 PAT。"
    "Cloud 旧 search 端点（/rest/api/3/search）已 deprecated，需使用 /rest/api/3/search/jql。"
    "Cloud 限流自 2026-03-02 起强制执行 points-based 计费，影响 3LO 应用；API token 不受影响。"
)

JIRA_METADATA = IntegrationMetadata(
    key="jira",
    display_name="Jira / Confluence",
    description="Atlassian Jira 集成，支持 Issue CRUD / JQL 搜索 / Transition / 项目管理",
    adapter_type="http",
    source_types=["jira"],
    supported_auth_types=[
        "jira_cloud_3lo",  # Cloud 3LO（专属，含 cloudId 解析）
        "basic",  # Cloud API token
        "oauth2_authorization_code",  # DC OAuth2（需框架补齐 PKCE）
        "jira_dc_pat",  # DC PAT
    ],
    tags=["研发管理", "项目管理", "SaaS", "Enterprise"],
    icon="jira",
    docs_url="https://developer.atlassian.com/cloud/jira/platform/rest/v3/",
    connection_extra_schema=_CONNECTION_EXTRA_SCHEMA,
    example_config={
        "deployment_mode": "cloud",
        "api_version": "v3",
        "product": "jira",
        "auth_type": "jira_cloud_3lo",
    },
    dependency_note=_DEPENDENCY_NOTE,
)

CONFLUENCE_METADATA = IntegrationMetadata(
    key="confluence",
    display_name="Confluence",
    description="Atlassian Confluence 集成，支持页面 CRUD / CQL 搜索 / 空间管理",
    adapter_type="http",
    source_types=["confluence"],
    supported_auth_types=[
        "jira_cloud_3lo",
        "basic",
        "oauth2_authorization_code",
        "jira_dc_pat",
    ],
    tags=["知识库", "SaaS", "Enterprise"],
    icon="confluence",
    docs_url="https://developer.atlassian.com/cloud/confluence/rest/v2/",
    connection_extra_schema=_CONNECTION_EXTRA_SCHEMA,
    example_config={
        "deployment_mode": "cloud",
        "api_version": "v2",
        "product": "confluence",
        "auth_type": "jira_cloud_3lo",
    },
    dependency_note=_DEPENDENCY_NOTE,
)