docs: 清理过时文档并更新管理端名称

删除home-api.md、team-building-api.md等废弃文档统一替换所有文档中的`WonderQ-Admin-UI`为`WonderQ-Admin-UI-Vue` 更新README.md与联调文档的内容与路径修正各API文档的过时描述，移除废弃的迁移说明与本地mock依赖整理docs/README.md的文档索引，优化阅读路径
2026-08-26 19:41:15 +08:00
parent 8de6ea01d0
commit e8eb8614f0
17 changed files with 143 additions and 1754 deletions
--- a/docs/integration-workflow.md
+++ b/docs/integration-workflow.md
@@ -1,21 +1,32 @@
 # WonderQ 三端联调流程

-本文档定义 `WonderQ-Admin` 后端、`WonderQ-Admin-UI` 管理前端、`WonderQ-MiniAPP` 前台的本地联调顺序和接口变更流程。
+本文档定义 `WonderQ-Admin` 后端、`WonderQ-Admin-UI-Vue` 管理前端和 `WonderQ-MiniAPP` 前台的本地启动、联调顺序与接口变更流程。

 ## 三端职责

-| 端           | 目录               | 职责                                                  | 主要契约                                                                                  |
-| ------------ | ------------------ | ----------------------------------------------------- | ----------------------------------------------------------------------------------------- |
-| 后端 API     | `WonderQ-Admin`    | 提供 Public API、Admin API、鉴权、数据库、迁移和 seed | `backend-api-service.md`、`backend-plan.md`、`public-api.md`、`admin-api-requirements.md` |
-| 管理前端（Vue 迁移端） | `WonderQ-Admin-UI-Vue` | 新权限壳、动态菜单和业务切片迁移，生产路径 `/admin` | `admin-api-requirements.md`、`module-config-api.md` |
-| 管理前端（React 过渡端） | `WonderQ-Admin-UI` | 旧管理端，过渡路径 `/admin-legacy` | `admin-api-requirements.md`、`module-config-api.md` |
-| 前台 MiniAPP | `WonderQ-MiniAPP`  | H5 与微信小程序前台展示、咨询和线索提交               | `public-api.md`                                                                           |
+| 端 | 目录 | 职责 | 主要契约 |
+| --- | --- | --- | --- |
+| 后端 API | `WonderQ-Admin` | 提供 Public API、Admin API、鉴权、数据库、迁移和 seed | `admin-api-requirements.md`、`public-api.md` |
+| 管理前端 | `WonderQ-Admin-UI-Vue` | 管理登录、权限、站点模块、玩法、详情、管家和线索 | `admin-api-requirements.md`、`module-config-api.md`、各领域契约 |
+| 前台 MiniAPP | `WonderQ-MiniAPP` | H5 与微信小程序展示、咨询和线索提交 | `public-api.md` |

-三端所有 JSON 接口还必须遵守 [api-response-contract.md](./api-response-contract.md)：成功业务数据位于 `data`，失败为 `data: null`，`code` 必须等于 HTTP 状态码。
+三端所有 JSON 接口还必须遵守 [`api-response-contract.md`](./api-response-contract.md)：成功业务数据位于 `data`，失败时 `data: null`，`code` 等于 HTTP 状态码。

 ## 本地启动顺序

-1. 确认 Docker Desktop 已运行，然后启动后端依赖和数据库迁移。
+### 1. 启动后端
+
+首次安装：
+
+```powershell
+Set-Location .\WonderQ-Admin
+Copy-Item .env.example .env
+python -m venv .venv
+.\.venv\Scripts\Activate.ps1
+python -m pip install -r requirements.txt
+```
+
+日常启动：

 ```powershell
 Set-Location .\WonderQ-Admin
@@ -25,28 +36,11 @@ python -m alembic upgrade head
 python -m uvicorn app.main:app --host 0.0.0.0 --port 4000 --reload
 ```

-首次缺少虚拟环境或依赖时，先在 `WonderQ-Admin` 目录执行 `python -m venv .venv` 和 `python -m pip install -r requirements.txt`。
-健康检查：
+健康检查：`http://localhost:4000/health`。

-```text
-http://localhost:4000/health
-```
+首次空库初始化内容才执行 `python -m app.seed`；该命令可能重置站点、玩法和媒体内容，已有开发数据时不要重复执行。

-2. 启动管理前端。
-
-```powershell
-Set-Location .\WonderQ-Admin-UI
-yarn install
-yarn dev
-```
-
-默认访问：
-
-```text
-http://localhost:5602
-```
-
-Vue 迁移端独立启动：
+### 2. 启动管理前端

 ```powershell
 Set-Location .\WonderQ-Admin-UI-Vue
@@ -54,11 +48,9 @@ yarn install
 yarn dev
 ```

-默认访问 `http://localhost:5604/admin/`。生产反向代理使用 `/admin`，旧 React 使用 `/admin-legacy`；两端共用 `/api` 和 HttpOnly Refresh Cookie。
+访问 `http://localhost:5604/admin/`。Vite `/api` 代理默认指向 `http://localhost:4000`；修改后端地址时，在 `.env.local` 设置 `VITE_API_PROXY_TARGET`。

-管理端优先通过 `VITE_API_BASE_URL` 或本地 Vite `/api` 代理访问 `http://localhost:4000`。
-
-3. 启动 MiniAPP H5。
+### 3. 启动 MiniAPP H5

 ```powershell
 Set-Location .\WonderQ-MiniAPP
@@ -66,78 +58,40 @@ yarn install
 yarn dev
 ```

-默认访问：
+访问 `http://localhost:5173`。微信小程序开发构建使用：

-```text
-http://localhost:5173
-```
-
-微信小程序开发构建：
-
-```bash
+```powershell
 yarn dev:mp-weixin
 ```

 ## 联调检查清单

-后端启动后先检查：
+后端启动后：

- `GET /health` 返回服务健康状态。
- `GET /api/public/site-config` 返回前台所需数组字段。
- `POST /api/admin/auth/login` 能返回 token 和 user。
- 使用客户端或 curl 检查响应顶层包含数字 `code`、字符串 `msg` 和 `data`；不能继续接受旧的未包裹响应。
+- `GET /health` 返回健康状态。
+- `GET /api/public/site-config` 返回前台站点配置。
+- `POST /api/admin/auth/login` 返回统一包裹的登录结果。
+- 所有成功响应包含数字 `code`、`msg: "success"` 和 `data`；失败响应的 `data` 必须为 `null`。

-管理端联调重点：
+管理端重点检查：

- 登录后请求头包含 `Authorization: Bearer <token>`。
- 站点配置、线索、发布和重置接口按 `admin-api-requirements.md` 返回。
- 页面模块新增、更新、删除、排序按 `module-config-api.md` 返回 JSON。
+- 登录后请求带 `Authorization: Bearer <access-token>`，Refresh Token 只通过 HttpOnly Cookie 传递。
+- 站点模块、玩法、详情、管家、线索、媒体、发布和重置接口按当前契约返回。
+- 新增、更新、删除和排序成功后，页面使用接口返回的数据更新状态，不自行生成 ID 或排序结果。

-MiniAPP 联调重点：
+MiniAPP 重点检查：

- `site-config` 失败时仍能回退本地内容。
- 首页模块按 Public API 字段渲染，不依赖后台未发布或未启用数据。
- 线索提交调用 `POST /api/public/leads`，失败时显示可理解错误。
- 首页、玩法、路线详情、管家、团队共创和客片案例请求都由公共 API 层解包 `data`，页面不重复解包。
-
-## 用车需求三端联调
-
-1. 在 Admin UI 首页模块的“用车服务”中维护板块简介、服务说明、优势和使用流程；在“万趣用车”中维护可选车型。
-2. 启动 MiniAPP 后点击车型卡片，确认进入 `/pages/vehicle-demand?vehicleOptionId={id}`；未登录时走现有微信登录并回跳原页面。
-3. 登录后提交用车需求，确认 `POST /api/public/leads` 携带 `leadType=vehicle`、`vehicleDemand` 和客户 JWT；后端从 JWT 写入 `customerId`，并归一化目的地、日期和人数摘要。
-4. Admin UI 进入“需求线索”，默认筛选 `leadType=vehicle`，确认联系人、日期、地点、人数、行李、车型快照和备注可查看，并可更新既有线索状态。
-5. 停止 Public API 时确认 MiniAPP 仍显示本地用车服务文案，并保留表单错误和重试提示；不展示实时库存、价格、支付或订单状态。
-
-## 路线详情三端联调
-
-路线详情使用独立 `DetailRecord`，不修改 `WanfaRoute` 表结构，也不建立商品、订单或预订关联。联调顺序如下：
-
-1. 执行数据库迁移，确认 `0021_detail_records` 已创建详情表并为已有路线生成基础记录；确认 `0022_opaque_ids` 已将历史语义 ID 转换为稳定 UUID，并同步玩法外键、详情 `key` 和审计引用。生产环境执行前按迁移规范单独确认。
-2. 在 Admin UI 进入“玩法”，编辑路线摘要、详情字段和联系管家，保存时先保存路线，再以路线 ID 作为 `DetailRecord.key` 创建或更新详情；顾问选项来自 `GET /api/admin/concierge/advisors`。
-3. 检查 `GET /api/public/wanfa/categories` 仍只返回路线摘要；检查 `GET /api/public/home` 的玩法推荐携带关联路线摘要。
-4. 在 MiniAPP 首页玩法推荐或玩法页点击路线，确认跳转 `/pages/detail/index?routeId={routeId}`，并请求 `GET /api/public/details/{routeId}`。
-5. 修改 Admin UI 的详情内容或联系管家后刷新 MiniAPP，确认标题、正文、费用说明、注意事项、画廊和顾问资料更新；停用或删除详情时确认 Public API 返回 `404`。
-6. 在管家页面停用或删除已关联顾问，再刷新路线详情，确认详情仍可读取且 `conciergeAdvisor` 为 `null`，联系入口隐藏；重新启用顾问后确认入口和弹窗资料恢复。
-6. 关闭后端接口，确认 MiniAPP 按路线 ID 展示本地网络图片和模拟文案，并提示当前为模拟数据；未知路线展示未找到和重试状态。
-
-## 稳定 ID 联调检查
-
-1. 执行 `0022_opaque_ids` 后，检查首页、玩法、管家、团队共创和客片案例列表返回的 `id` 均为 UUID 字符串。
-2. 从列表复制一个 ID 请求对应详情、排序或删除接口，确认同一 ID 可连续复用，不能每次响应变化。
-3. 检查首页玩法推荐的 `categoryId`、路线 `id` 与 `GET /api/public/details/{key}` 的 `key` 关联正确。
-4. MiniAPP 本地 fallback 的语义 ID 只在接口失败时使用，不得覆盖接口成功返回的 UUID。
-
-路线详情页不包含在线订阅、收藏、预订或订单动作；联系管家入口由 `conciergeAdvisor` 是否有效决定。字段和错误约定以 `detail-api.md`、`public-api.md` 和 `concierge-api.md` 为准。
+- Public API 失败时显示错误、重试或空态，并按现有本地 fallback 规则处理。
+- 首页、玩法、路线详情、管家、团队共创和客片案例都由公共 API 层解包 `data`，页面不重复解包。
+- `POST /api/public/leads` 的用车需求携带客户 JWT；后端从 JWT 写入 `customerId`，客户端不提交该字段。

 ## 接口变更流程

-1. 先更新契约文档。
-   - 响应包裹、错误结构或状态码变化：更新 `api-response-contract.md`。
-   - Public API 变更：更新 `public-api.md`。
-   - Admin API 变更：更新 `admin-api-requirements.md`。
-2. 后端实现或调整接口，并补充对应验证。
-3. 管理前端或 MiniAPP 按契约调整调用和类型。
-4. 三端分别运行对应验证命令。
+1. 响应包裹、错误结构或 ID 规则变化：先更新 `api-response-contract.md`。
+2. Admin API 路径、字段、权限或状态码变化：更新 `admin-api-requirements.md` 或对应领域契约。
+3. 站点模块字段、排序、单例或删除规则变化：更新 `module-config-api.md`。
+4. Public API 变化：更新 `public-api.md`，再同步后端序列化和 MiniAPP 类型。
+5. 完成后端实现、前端调用和影响范围内的测试；不得在流程文档中复制接口字段。

 ## 验证命令

@@ -146,13 +100,13 @@ MiniAPP 联调重点：
 ```powershell
 Set-Location .\WonderQ-Admin
 python -m pytest
-python -m alembic upgrade head
 ```

 管理前端：

 ```powershell
-Set-Location .\WonderQ-Admin-UI
+Set-Location .\WonderQ-Admin-UI-Vue
+yarn test
 yarn build
 ```

@@ -160,13 +114,13 @@ MiniAPP：

 ```powershell
 Set-Location .\WonderQ-MiniAPP
+yarn test
 yarn build:h5
 yarn build:mp-weixin
-yarn test
 ```

 ## 安全边界

 - 不读取、展示或提交 `.env`、`.env.local` 和生产环境变量值。
- 文档示例只写变量名，不写真实 Token、JWT secret、客服链接、企业 ID 或手机号。
- `python -m app.seed`、内容重置、发布、回滚和数据库迁移都属于高风险动作，生产环境执行前必须明确确认。
+- 文档示例只写占位值，不写真实 Token、JWT secret、客服链接、企业 ID 或手机号。
+- `python -m app.seed`、内容重置、发布和数据库迁移属于高风险动作，生产环境执行前必须明确确认。