X-Financial/server/src/app/core/openapi.py

API_DESCRIPTION = """
X-Financial 后端 OpenAPI 文档。

## 基本信息

- 所有业务接口都挂在 `/api/v1` 前缀下。
- 交互式 Swagger 页面默认位于 `/docs`，ReDoc 页面位于 `/redoc`。
- 仓库内导出的静态规范文件位于 `document/development/backend_api/openapi.json`。

## 鉴权约定

- 知识库接口依赖以下请求头模拟当前用户：
  - `X-Auth-Username`
  - `X-Auth-Name`
  - `X-Auth-Role-Codes`
  - `X-Auth-Is-Admin`
- Agent 资产写接口支持以下审计头：
  - `X-Actor`
  - `X-Request-Id`
- Hermes 运行时模型配置接口需要：
  - `Authorization: Bearer <HERMES_AGENT_SHARED_TOKEN>`

## 当前模块范围

- 系统初始化与健康检查
- 登录认证
- 员工目录
- 报销单
- 知识库与 ONLYOFFICE
- OCR 票据识别
- 语义本体解析
- Orchestrator 统一调度
- 系统设置与模型连通性
- Agent 资产、运行日志、审计日志
""".strip()


OPENAPI_TAGS = [
    {
        "name": "health",
        "description": "服务健康检查与数据库 / Redis 连通性状态。",
    },
    {
        "name": "bootstrap",
        "description": "系统初始化配置，包括公司信息、数据库和缓存配置。",
    },
    {
        "name": "auth",
        "description": "后台登录认证接口，支持管理员和员工账号登录。",
    },
    {
        "name": "employees",
        "description": "员工目录管理，包括员工列表、详情、创建、更新和停用。",
    },
    {
        "name": "reimbursements",
        "description": "报销申请基础接口，包含列表、创建和详情查询。",
    },
    {
        "name": "knowledge",
        "description": "知识库文件管理、内容访问与 ONLYOFFICE 集成接口。",
    },
    {
        "name": "ocr",
        "description": "票据图片与 PDF 的 OCR 识别接口，当前默认对接 PaddleOCR mobile 运行时。",
    },
    {
        "name": "ontology",
        "description": "Day 3 语义本体解析接口，把自然语言问题稳定转换为 8 个核心字段。",
    },
    {
        "name": "orchestrator",
        "description": "Day 4 Orchestrator 统一入口，负责语义、权限、路由、工具调用和降级。",
    },
    {
        "name": "settings",
        "description": "系统设置、模型配置、模型连通性探测和 Hermes 运行时模型配置。",
    },
    {
        "name": "agent-assets",
        "description": "Agent 资产中心，覆盖规则、技能、MCP、任务及其版本、审核和上线流程。",
    },
    {
        "name": "agent-runs",
        "description": "Agent 运行日志查询，包括工具调用和语义解析结果。",
    },
    {
        "name": "audit-logs",
        "description": "系统审计日志查询接口，用于追踪资产和任务写操作。",
    },
    {
        "name": "root",
        "description": "服务根入口，用于确认应用已启动。",
    },
]