WonderQ-Project/docs/integration-workflow.md

WonderQ 三端联调流程

本文档定义 WonderQ-Admin 后端、WonderQ-Admin-UI 管理前端、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

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

本地启动顺序

1. 确认 Docker Desktop 已运行，然后启动后端依赖和数据库迁移。

Set-Location .\WonderQ-Admin
.\.venv\Scripts\Activate.ps1
docker-compose up -d postgres redis
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

2. 启动管理前端。

Set-Location .\WonderQ-Admin-UI
yarn install
yarn dev

默认访问：

http://localhost:5602

Vue 迁移端独立启动：

Set-Location .\WonderQ-Admin-UI-Vue
yarn install
yarn dev

默认访问 http://localhost:5604/admin/。生产反向代理使用 /admin，旧 React 使用 /admin-legacy；两端共用 /api 和 HttpOnly Refresh Cookie。

管理端优先通过 VITE_API_BASE_URL 或本地 Vite /api 代理访问 http://localhost:4000。

3. 启动 MiniAPP H5。

Set-Location .\WonderQ-MiniAPP
yarn install
yarn dev

默认访问：

http://localhost:5173

微信小程序开发构建：

yarn dev:mp-weixin

联调检查清单

后端启动后先检查：

• GET /health 返回服务健康状态。
• GET /api/public/site-config 返回前台所需数组字段。
• POST /api/admin/auth/login 能返回 token 和 user。
• 使用客户端或 curl 检查响应顶层包含数字 code、字符串 msg 和 data；不能继续接受旧的未包裹响应。

管理端联调重点：

• 登录后请求头包含 Authorization: Bearer <token>。
• 站点配置、线索、发布和重置接口按 admin-api-requirements.md 返回。
• 页面模块新增、更新、删除、排序按 module-config-api.md 返回 JSON。

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，联系入口隐藏；重新启用顾问后确认入口和弹窗资料恢复。
7. 关闭后端接口，确认 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 为准。

接口变更流程

1. 先更新契约文档。
   • 响应包裹、错误结构或状态码变化：更新 api-response-contract.md。
   • Public API 变更：更新 public-api.md。
   • Admin API 变更：更新 admin-api-requirements.md。
2. 后端实现或调整接口，并补充对应验证。
3. 管理前端或 MiniAPP 按契约调整调用和类型。
4. 三端分别运行对应验证命令。

验证命令

后端：

Set-Location .\WonderQ-Admin
python -m pytest
python -m alembic upgrade head

管理前端：

Set-Location .\WonderQ-Admin-UI
yarn build

MiniAPP：

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

安全边界

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