Kris
55188ff7fa
1. 调整导入顺序与格式，修复重复导入 2. 替换通用异常捕获为更精准的ValueError 3. 重构持久层仓库的get_deleted/list_deleted方法，添加ORM转领域模型逻辑 4. 完善配置校验与参数合法性检查，新增缺失字段校验 5. 优化多行字符串与函数调用的换行格式 6. 修复通知服务状态判定逻辑与文档描述 7. 简化无用的TYPE_CHECKING代码块 8. 重构ServiceNow元数据发现逻辑，增加字段合法性校验 9. 修复数据库查询验证器的子查询处理逻辑 10. 完善领域模型的初始化校验与属性语义
165 lines
7.9 KiB
Python
165 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）。
|
||
以下表格中的 URL 均省略 ``https://`` 前缀。
|
||
|
||
| 维度 | Cloud | Data Center |
|
||
| --- | --- | --- |
|
||
| Jira API 版本 | v3 | v2 |
|
||
| Confluence API 版本 | v2 | v1（``/rest/api``） |
|
||
| Jira 根路径（Basic Auth） | ``<site>.atlassian.net/rest/api/3`` | ``<host>:<port>/[context]/rest/api/2`` |
|
||
| Jira 根路径（OAuth 3LO） | ``api.atlassian.com/ex/jira/{cloudId}/rest/api/3`` | 无（DC 不需要 cloudId） |
|
||
| Confluence 根路径（Basic Auth） | ``<site>.atlassian.net/wiki/rest/api/v2`` | ``<host>:<port>/[context]/rest/api`` |
|
||
| Confluence 根路径（OAuth 3LO） | ``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/{{issueIdOrKey}}"
|
||
JIRA_ISSUE_TRANSITIONS_PATH = "/rest/api/{api_version}/issue/{{issueIdOrKey}}/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,
|
||
)
|