# WonderQ 文档索引

本目录只维护当前三端实际使用的契约和联调规则：`WonderQ-Admin`、`WonderQ-Admin-UI-Vue`、`WonderQ-MiniAPP`。历史需求、旧管理端方案和重复接口说明不作为当前文档。

## 推荐阅读路径

后端或管理前端：

1. [`api-response-contract.md`](./api-response-contract.md)：统一响应包裹、错误和 ID 规则
2. [`admin-api-requirements.md`](./admin-api-requirements.md)：Admin API 主契约
3. [`module-config-api.md`](./module-config-api.md)：首页与用车站点模块 CRUD 契约
4. [`wanfa-api.md`](./wanfa-api.md)：玩法分类和路线管理契约
5. [`detail-api.md`](./detail-api.md)：路线详情管理契约
6. [`concierge-api.md`](./concierge-api.md)：管家顾问管理契约

MiniAPP 或 Public API 联调：

1. [`api-response-contract.md`](./api-response-contract.md)
2. [`public-api.md`](./public-api.md)：唯一 Public API 契约
3. [`integration-workflow.md`](./integration-workflow.md)：启动、联调和验证流程

## 文档清单

| 文档 | 作用 | 主要读者 |
| --- | --- | --- |
| `api-response-contract.md` | 三端统一 JSON 响应、错误、ID 和客户端解包规则 | 全部 |
| `integration-workflow.md` | 三端本地启动、联调顺序、接口变更流程和验证命令 | 全部 |
| `admin-api-requirements.md` | 当前 Admin API 主契约 | 后端、管理前端 |
| `module-config-api.md` | 站点页面模块 CRUD 唯一细节契约 | 后端、管理前端 |
| `wanfa-api.md` | 玩法分类和路线管理 API | 后端、管理前端 |
| `detail-api.md` | 路线详情管理 API | 后端、管理前端 |
| `concierge-api.md` | 管家顾问管理 API | 后端、管理前端 |
| `public-api.md` | MiniAPP 使用的 Public API 唯一契约 | 后端、MiniAPP |
| `decisions/` | 当前重要技术决策记录 | 全部 |

## 文档边界

- `public-api.md` 是 MiniAPP 对接后端的唯一 Public API 契约。
- `admin-api-requirements.md` 是 Admin API 主契约；首页站点模块的字段和 CRUD 以 `module-config-api.md` 为准。
- 玩法、详情和管家领域分别以对应补充契约为准，不在联调文档中重复维护字段。
- `integration-workflow.md` 只记录流程、验证和风险，不定义新的接口字段。
- 首页站点模块的 Admin API 统一以 `module-config-api.md` 为准。
- `docs/superpowers/` 仅保存仍在使用的设计参考，不作为接口契约入口。

## 安全约束

- 文档示例不得写入真实 Token、JWT secret、客服链接、企业 ID、手机号或生产环境变量值。
- `.env`、`.env.local` 和生产配置不进入文档目录。
- 涉及重置数据、发布、回滚、迁移或生产操作的文档，必须明确风险和验证方式。