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

document/development/backend_api/README.md

@@ -0,0 +1,44 @@
+# Backend API Swagger 文档
+
+本目录用于沉淀后端接口的 Swagger / OpenAPI 产物，给开发、联调和后续 Agent 接口调用统一对照。
+
+## 目录说明
+
+- `openapi.json`
+  - 由 FastAPI `app.openapi()` 导出的完整 OpenAPI 规范。
+- `interface_inventory.md`
+  - 基于 OpenAPI 自动整理的接口清单，按 tag 分组查看方法、路径和摘要。
+
+## 在线入口
+
+- Swagger UI：`/docs`
+- ReDoc：`/redoc`
+- OpenAPI JSON：`/openapi.json`
+
+如果本地默认端口不变，完整地址通常是：
+
+- `http://127.0.0.1:8000/docs`
+- `http://127.0.0.1:8000/redoc`
+- `http://127.0.0.1:8000/openapi.json`
+
+## 重新生成
+
+在 `/app/server` 下执行：
+
+```bash
+PYTHONPATH=/app/server/src /app/server/.venv/bin/python /app/server/scripts/export_openapi.py
+```
+
+## 当前约定
+
+- 全部业务接口前缀：`/api/v1`
+- 知识库接口使用请求头模拟登录用户：
+  - `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>`

document/development/backend_api/interface_inventory.md

@@ -0,0 +1,100 @@
+# Backend API Interface Inventory
+
+- Generated at: `2026-05-11 04:14:05 UTC`
+- API title: `X-Financial`
+- API version: `0.1.0`
+- Total paths: `28`
+
+## Tag Overview
+
+### agent-assets
+
+| Method | Path | Summary |
+| --- | --- | --- |
+| `GET` | `/api/v1/agent-assets` | 查询 Agent 资产列表 |
+| `POST` | `/api/v1/agent-assets` | 创建 Agent 资产 |
+| `GET` | `/api/v1/agent-assets/{asset_id}` | 读取 Agent 资产详情 |
+| `PATCH` | `/api/v1/agent-assets/{asset_id}` | 更新 Agent 资产 |
+| `POST` | `/api/v1/agent-assets/{asset_id}/activate` | 激活资产当前版本 |
+| `POST` | `/api/v1/agent-assets/{asset_id}/reviews` | 创建资产审核记录 |
+| `GET` | `/api/v1/agent-assets/{asset_id}/versions` | 查询资产版本列表 |
+| `POST` | `/api/v1/agent-assets/{asset_id}/versions` | 创建资产版本 |
+
+### agent-runs
+
+| Method | Path | Summary |
+| --- | --- | --- |
+| `GET` | `/api/v1/agent-runs` | 查询 Agent 运行日志 |
+| `GET` | `/api/v1/agent-runs/{run_id}` | 读取单次 Agent 运行详情 |
+
+### audit-logs
+
+| Method | Path | Summary |
+| --- | --- | --- |
+| `GET` | `/api/v1/audit-logs` | 查询审计日志 |
+
+### auth
+
+| Method | Path | Summary |
+| --- | --- | --- |
+| `POST` | `/api/v1/auth/login` | 用户登录 |
+
+### bootstrap
+
+| Method | Path | Summary |
+| --- | --- | --- |
+| `GET` | `/api/v1/bootstrap` | 读取初始化状态 |
+| `POST` | `/api/v1/bootstrap` | 写入初始化配置 |
+
+### employees
+
+| Method | Path | Summary |
+| --- | --- | --- |
+| `GET` | `/api/v1/employees` | 查询员工列表 |
+| `POST` | `/api/v1/employees` | 创建员工 |
+| `GET` | `/api/v1/employees/meta` | 读取员工目录元数据 |
+| `GET` | `/api/v1/employees/{employee_id}` | 读取员工详情 |
+| `PATCH` | `/api/v1/employees/{employee_id}` | 更新员工 |
+| `POST` | `/api/v1/employees/{employee_id}/disable` | 停用员工 |
+
+### health
+
+| Method | Path | Summary |
+| --- | --- | --- |
+| `GET` | `/api/v1/health` | 服务健康检查 |
+
+### knowledge
+
+| Method | Path | Summary |
+| --- | --- | --- |
+| `POST` | `/api/v1/knowledge/documents` | 上传知识库文档 |
+| `DELETE` | `/api/v1/knowledge/documents/{document_id}` | 删除知识库文档 |
+| `GET` | `/api/v1/knowledge/documents/{document_id}` | 读取知识库文档详情 |
+| `GET` | `/api/v1/knowledge/documents/{document_id}/content` | 下载或预览知识库原文 |
+| `GET` | `/api/v1/knowledge/documents/{document_id}/onlyoffice-config` | 读取 ONLYOFFICE 预览配置 |
+| `POST` | `/api/v1/knowledge/documents/{document_id}/onlyoffice/callback` | 接收 ONLYOFFICE 回调 |
+| `GET` | `/api/v1/knowledge/documents/{document_id}/onlyoffice/content` | 读取 ONLYOFFICE 文档源文件 |
+| `GET` | `/api/v1/knowledge/library` | 查询知识库目录 |
+
+### reimbursements
+
+| Method | Path | Summary |
+| --- | --- | --- |
+| `GET` | `/api/v1/reimbursements` | 查询报销申请列表 |
+| `POST` | `/api/v1/reimbursements` | 创建报销申请 |
+| `GET` | `/api/v1/reimbursements/{request_id}` | 读取报销申请详情 |
+
+### root
+
+| Method | Path | Summary |
+| --- | --- | --- |
+| `GET` | `/` | 服务根检查 |
+
+### settings
+
+| Method | Path | Summary |
+| --- | --- | --- |
+| `GET` | `/api/v1/settings` | 读取系统设置 |
+| `PUT` | `/api/v1/settings` | 保存系统设置 |
+| `POST` | `/api/v1/settings/model-connectivity` | 测试模型连通性 |
+| `GET` | `/api/v1/settings/runtime-models/{slot}` | 读取 Hermes 运行时模型配置 |