"""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://.atlassian.net/rest/api/3`` | ``https://:/[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://.atlassian.net/wiki/rest/api/v2`` | ``https://:/[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, )