Kris
74709ba2d3
新增六边形架构核心代码包，包含： 1. 协议适配器层：HTTP/SMTP/IMAP/SSH/GRPC等多协议适配器实现 2. 认证插件体系：基础认证、API密钥、HMAC等多类型认证插件 3. 执行编排框架：工具执行器、上下文构建、运行时治理组件 4. 用例端口与DTO：定义领域服务端口与数据传输对象 5. 厂商集成包框架：支持第三方系统集成扩展 6. 基础设施装配层：实现依赖注入与服务装配 所有代码遵循六边形架构设计原则，实现端口与适配器解耦，支持动态扩展与自动发现。
163 lines
7.9 KiB
Python
163 lines
7.9 KiB
Python
"""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,
|
||
)
|