feat: 完善后端 API OpenAPI 文档与统一错误响应 schema

server/src/app/core/openapi.py

@@ -0,0 +1,80 @@
+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
+- 系统设置与模型连通性
+- 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": "settings",
+        "description": "系统设置、模型配置、模型连通性探测和 Hermes 运行时模型配置。",
+    },
+    {
+        "name": "agent-assets",
+        "description": "Agent 资产中心，覆盖规则、技能、MCP、任务及其版本、审核和上线流程。",
+    },
+    {
+        "name": "agent-runs",
+        "description": "Agent 运行日志查询，包括工具调用和语义解析结果。",
+    },
+    {
+        "name": "audit-logs",
+        "description": "系统审计日志查询接口，用于追踪资产和任务写操作。",
+    },
+    {
+        "name": "root",
+        "description": "服务根入口，用于确认应用已启动。",
+    },
+]