e082bd2d98
- 新增`api_response.py`统一响应封装工具类，提供标准成功/错误响应构造方法 - 重构WonderQ-Admin全局异常处理器，将所有异常转换为标准响应格式 - 修改所有公共和管理端接口的返回逻辑，统一使用`code`（与HTTP状态码一致）、`msg`和`data`的三层结构 - 新增`api-response-contract.md`文档，定义完整的三端统一JSON响应规范 - 更新所有领域API文档，明确业务数据需位于`data`字段内，补充响应格式说明 - 为WonderQ-MiniAPP和WonderQ-Admin-UI新增响应解析逻辑和类型定义，自动完成协议校验和错误处理 - 更新所有测试用例，适配新的响应结构确保接口符合契约要求 - 新增`module-config-api.md`模块配置API文档，补充站点模块配置的接口约定 - 更新项目README文档，调整文档分类顺序将响应契约置于首位
78 lines
4.0 KiB
Markdown
78 lines
4.0 KiB
Markdown
# WonderQ 文档索引
|
|
|
|
本目录只保留当前有效文档，用于支撑 `WonderQ-Admin`、`WonderQ-Admin-UI`、`WonderQ-MiniAPP` 三端并行开发和联调。非当前技术路径不放在当前文档集中。
|
|
|
|
## 推荐阅读路径
|
|
|
|
后端开发：
|
|
|
|
1. `api-response-contract.md`
|
|
2. `admin-api-requirements.md`
|
|
3. `home-api.md`
|
|
4. `wanfa-api.md`
|
|
5. `concierge-api.md`
|
|
6. `detail-api.md`
|
|
7. `team-building-api.md`
|
|
8. `public-api.md`
|
|
|
|
管理前端开发：
|
|
|
|
1. `api-response-contract.md`
|
|
2. `integration-workflow.md`
|
|
3. `admin-api-requirements.md`
|
|
4. `home-api.md`
|
|
5. `wanfa-api.md`
|
|
6. `concierge-api.md`
|
|
7. `detail-api.md`
|
|
8. `team-building-api.md`
|
|
9. `module-config-api.md`
|
|
|
|
MiniAPP 前台开发：
|
|
|
|
1. `api-response-contract.md`
|
|
2. `integration-workflow.md`
|
|
3. `wanfa-api.md`
|
|
4. `detail-api.md`
|
|
5. `team-building-api.md`
|
|
6. `public-api.md`
|
|
7. `development-status.md`
|
|
|
|
## 文档清单
|
|
|
|
| 文档 | 作用 | 主要读者 |
|
|
| --------------------------- | --------------------------------------------------------- | -------------- |
|
|
| `api-response-contract.md` | 三端统一 JSON 响应包裹、错误和客户端解包规则 | 全部 |
|
|
| `integration-workflow.md` | 三端本地启动、联调顺序、接口变更流程和验证命令 | 全部 |
|
|
| `development-status.md` | 三端能力对接状态矩阵和优先联调路径 | 全部 |
|
|
| `decisions.md` | 当前有效技术和文档决策 | 全部 |
|
|
| `backend-api-service.md` | 后端 API 服务运行与前端联调说明 | 后端 |
|
|
| `backend-plan.md` | 当前 FastAPI 后端定位、业务模块、近期优先级和安全部署原则 | 后端 |
|
|
| `admin-api-requirements.md` | Admin UI 必需的 Admin API 主契约 | 后端、管理前端 |
|
|
| `module-config-api.md` | 页面模块配置 CRUD 的唯一细节契约 | 后端、管理前端 |
|
|
| `home-api.md` | 首页内容和玩法推荐关联的 Admin API 补充契约 | 后端、管理前端 |
|
|
| `wild-archives-api.md` | 客片案例列表、详情和图片字段契约 | 三端 |
|
|
| `wanfa-api.md` | 玩法分类和路线管理 API 的补充契约 | 后端、管理前端 |
|
|
| `concierge-api.md` | 管家顾问资料管理 API 的补充契约 | 后端、管理前端 |
|
|
| `detail-api.md` | 详情展示内容管理 API 的补充契约 | 后端、管理前端 |
|
|
| `team-building-api.md` | 团队共创详情字段、CRUD 与 Public 详情接口契约 | 三端 |
|
|
| `public-api.md` | MiniAPP 对接后端的 Public API 契约 | 后端、MiniAPP |
|
|
|
|
## 文档边界
|
|
|
|
- `public-api.md` 是 MiniAPP 对接后端的唯一 Public API 契约。
|
|
- `admin-api-requirements.md` 是 Admin UI 对接后端的主契约。
|
|
- `home-api.md` 是首页内容管理的 Admin API 补充契约。
|
|
- `wanfa-api.md` 是玩法分类和路线管理的 Admin API 补充契约。
|
|
- `concierge-api.md` 是管家顾问资料管理的 Admin API 补充契约。
|
|
- `detail-api.md` 是详情展示内容管理的 Admin API 补充契约。
|
|
- `module-config-api.md` 是页面模块 CRUD 细节的唯一权威文档。
|
|
- `integration-workflow.md` 只写联调流程，不重复接口字段。
|
|
- `development-status.md` 只记录当前状态，不替代测试结果。
|
|
- `decisions.md` 只记录当前有效决策。
|
|
|
|
## 安全约束
|
|
|
|
- 文档示例不得写入真实 Token、JWT secret、客服链接、企业 ID、手机号或生产环境变量值。
|
|
- `.env`、`.env.local` 和生产配置不进入文档目录。
|
|
- 涉及重置数据、发布、回滚、迁移或生产操作的文档，需要明确风险和验证方式。
|