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>`