141 lines
6.6 KiB
Markdown
141 lines
6.6 KiB
Markdown
# WonderQ 三端联调流程
|
||
|
||
本文档定义 `WonderQ-Admin` 后端、`WonderQ-Admin-UI-Vue` 管理前端和 `WonderQ-MiniAPP` 前台的本地启动、联调顺序与接口变更流程。
|
||
|
||
## 三端职责
|
||
|
||
| 端 | 目录 | 职责 | 主要契约 |
|
||
| --- | --- | --- | --- |
|
||
| 后端 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 状态码。
|
||
|
||
## 本地启动顺序
|
||
|
||
### 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
|
||
.\.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
|
||
```
|
||
|
||
健康检查：`http://localhost:4000/health`。
|
||
|
||
首次空库初始化内容才执行 `python -m app.seed`；该命令会覆盖初始化站点与媒体内容，已有开发数据时不要重复执行。
|
||
|
||
### 2. 启动管理前端
|
||
|
||
```powershell
|
||
Set-Location .\WonderQ-Admin-UI-Vue
|
||
yarn install
|
||
yarn dev
|
||
```
|
||
|
||
访问 `http://localhost:5604/admin/`。Vite `/api` 代理默认指向 `http://localhost:4000`；修改后端地址时，在 `.env.local` 设置 `VITE_API_PROXY_TARGET`。
|
||
|
||
### 3. 启动 MiniAPP H5
|
||
|
||
```powershell
|
||
Set-Location .\WonderQ-MiniAPP
|
||
yarn install
|
||
yarn dev
|
||
```
|
||
|
||
访问 `http://localhost:5173`。微信小程序开发构建使用：
|
||
|
||
```powershell
|
||
yarn dev:mp-weixin
|
||
```
|
||
|
||
## 联调检查清单
|
||
|
||
后端启动后：
|
||
|
||
- `GET /health` 返回健康状态。
|
||
- `GET /api/public/site-config` 返回前台站点配置。
|
||
- `GET /api/admin/auth/captcha` 返回图形验证码和短时 `captchaId`。
|
||
- `POST /api/admin/auth/login` 携带 `captchaId`、`captchaCode` 和可选 `rememberMe` 后返回统一包裹的登录结果；验证码错误或过期后重新获取。
|
||
- 管理端登录后依次读取 `/api/admin/system/profile` 和 `/api/admin/system/routers`；后者按当前管理员权限提供动态导航树。
|
||
- 所有成功响应包含数字 `code`、`msg: "success"` 和 `data`；失败响应的 `data` 必须为 `null`。
|
||
|
||
管理端重点检查：
|
||
|
||
- 登录后请求带 `Authorization: Bearer <access-token>`，Refresh Token 只通过 HttpOnly Cookie 传递。
|
||
- 登录页应展示验证码图片，点击图片可刷新；验证码失败后自动刷新，不能在前端缓存或记录验证码答案。
|
||
- “记住密码”只控制 Refresh Token Cookie 是否持久化；前端最多记住账号和勾选偏好，不得保存明文密码。
|
||
- 动态路由只注册 `/api/admin/system/routers` 返回的页面菜单；目录用于组织层级，按钮只用于按钮权限，不注册为页面。
|
||
- 管理端界面图标统一由 `@element-plus/icons-vue` 提供；菜单返回的图标名经 `LayoutIcon` 白名单映射，未知值显示默认图标。顾问服务详情中的 `icon` 字段仍按业务内容数据处理。
|
||
- 变更角色、菜单或用户关联后，权限缓存失效时要重新登录或重新加载菜单，确认侧栏、路由和按钮权限同步变化。
|
||
- 站点模块、玩法、详情、管家、线索和媒体接口按当前契约返回。
|
||
- 新增、更新、删除和排序成功后，页面使用接口返回的数据更新状态，不自行生成 ID 或排序结果。
|
||
|
||
MiniAPP 重点检查：
|
||
|
||
- Public API 失败时显示错误、重试或空态，并按现有本地 fallback 规则处理。
|
||
- 首页、玩法、路线详情、管家、团队共创和客片案例都由公共 API 层解包 `data`，页面不重复解包。
|
||
- `POST /api/public/leads` 的用车需求携带客户 JWT；后端从 JWT 写入 `customerId`，客户端不提交该字段。
|
||
- 登录后从“我的”进入“用车提交记录”和“历史浏览记录”两个入口；两个列表均使用 `z-paging` 的 `@query` 分页模式，并传递 `pageNum`、`pageSize`。
|
||
- 用车记录列表只显示当前客户数据，点击列表项进入只读详情；确认详情中的联系电话是脱敏值，点击“提交新的用车需求”仍进入 `/pages/vehicle-demand`。
|
||
- 历史记录列表点击 `wanfa-route`、`team-building`、`wild-archive` 分别进入既有路线、团队共创和客片案例详情；详情成功后检查浏览历史服务端去重更新，接口失败时检查本地缓存兜底。
|
||
- 客户记录接口返回 `401` 时清除本地客户会话并跳转登录；列表还需检查空态、网络错误重试、下拉刷新和加载更多。
|
||
- Admin UI 不新增浏览历史菜单；在“需求线索”中以 `leadType=vehicle` 查询刚提交的用车记录，确认详情弹窗、状态更新和车型快照仍可用。
|
||
|
||
## 接口变更流程
|
||
|
||
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. 完成后端实现、前端调用和影响范围内的测试；不得在流程文档中复制接口字段。
|
||
|
||
## 验证命令
|
||
|
||
后端：
|
||
|
||
```powershell
|
||
Set-Location .\WonderQ-Admin
|
||
python -m pytest
|
||
```
|
||
|
||
管理前端：
|
||
|
||
```powershell
|
||
Set-Location .\WonderQ-Admin-UI-Vue
|
||
yarn test
|
||
yarn build
|
||
```
|
||
|
||
MiniAPP：
|
||
|
||
```powershell
|
||
Set-Location .\WonderQ-MiniAPP
|
||
yarn test
|
||
yarn build:h5
|
||
yarn build:mp-weixin
|
||
```
|
||
|
||
涉及客户记录接口时，先确认数据库已执行最新迁移 `0036_customer_browse_history`，再按“登录 → 我的 → 两个入口 → 分页 → 详情 → 返回刷新”的顺序联调。微信开发者工具中需分别验证 H5 和小程序不支持的图片格式不会被记录接口重新引入。
|
||
|
||
## 安全边界
|
||
|
||
- 不读取、展示或提交 `.env`、`.env.local` 和生产环境变量值。
|
||
- 文档示例只写占位值，不写真实 Token、JWT secret、客服链接、企业 ID 或手机号。
|
||
- `python -m app.seed` 和数据库迁移属于高风险动作，生产环境执行前必须明确确认。
|