# WonderQ 开发状态矩阵

本文档用来快速判断三端当前对接状态。状态以现有文档和接口契约为准，不替代实际构建、测试和联调结果。

## 状态说明

| 状态 | 含义 |
| --- | --- |
| 已覆盖 | 文档中已有明确契约，后端或前端已有对应调用说明 |
| 已封装 | 前端已有客户端封装，但页面不一定展示 |
| 当前使用 | 当前页面或启动流程依赖该能力 |
| 后续接入 | 契约已保留，当前页面可暂不依赖 |
| 需实测 | 需要本地启动三端后验证 |

## 三端总览

| 能力 | 后端 `WonderQ-Admin` | 管理前端 `WonderQ-Admin-UI` | 前台 `WonderQ-MiniAPP` | 说明 |
| --- | --- | --- | --- | --- |
| 健康检查 | 已覆盖 | 需实测 | 需实测 | `GET /health` |
| Public 站点配置 | 已覆盖 | 不直接使用 | 当前使用 | `GET /api/public/site-config` |
| Public 产品列表 | 已覆盖 | 不直接使用 | 当前使用 | `GET /api/public/products` |
| Public 产品详情 | 已覆盖 | 不直接使用 | 后续接入 | MiniAPP 当前主要使用产品列表缓存 |
| Public 目的地列表 | 已覆盖 | 不直接使用 | 后续接入 | 首页目的地当前来自 `site-config.destinations` |
| Public 线索提交 | 已覆盖 | 不直接使用 | 当前使用 | `POST /api/public/leads` |
| Admin 登录 | 已覆盖 | 当前使用 | 不使用 | `POST /api/admin/auth/login` |
| Admin 商品维护 | 已覆盖 | 当前使用 | 不使用 | 商品列表、新建、更新 |
| Admin 目的地维护 | 已覆盖 | 当前使用 | 不使用 | 返回别名和商品计数 |
| Admin 站点配置 | 已覆盖 | 当前使用 | 不使用 | 完整站点配置读取 |
| 页面模块 CRUD | 已覆盖 | 当前使用 | 不使用 | 细节以 `module-config-api.md` 为准 |
| 目的地页数据联调 | 已覆盖 | 当前使用 | 当前使用 | Admin UI 维护 `destinationHero`、`destinationRegions`、`destinations` 和商品 `destinationId`；MiniAPP 目的地页消费 `site-config.destinationHero`、`site-config.destinationRegions`、`site-config.destinations` 与 `products.items` |
| 需求页数据配置联调 | 已覆盖 | 当前使用 | 当前使用 | Admin UI 维护 `demandHero`、`demandFeatureCards`、`demandForm`、`demandRecommendations`，MiniAPP 需求页消费对应配置并按 `productIds` 匹配 `products.items` |
| Admin 线索跟进 | 已覆盖 | 当前使用 | 不使用 | 线索列表和状态流转 |
| 发布站点配置 | 已覆盖 | 当前使用 | 不使用 | `POST /api/admin/publish` |
| 贵州内容重置 | 已覆盖 | 当前使用 | 不使用 | 高风险操作，需鉴权和审计 |
| 媒体上传 | 契约已定义 | 当前使用 | 不使用 | 见 `module-config-api.md` 图片素材上传 |

## 目的地页优先联调路径

1. Admin UI 登录后进入“目的地页”，后台模块名称与前台三个区块一一对应为“顶部主视觉”“热门区域”“省内目的地”。
2. 在“顶部主视觉”新增或编辑主视觉标题、小标题、图片、启停和排序。
3. 在“热门区域”新增或编辑区域名称、搜索关键词、景点摘要、启停和排序。
4. 在“省内目的地”新增目的地，编辑名称、图片、热门状态、启停和排序。
5. 在“商品维护”新建或编辑商品，绑定 `destinationId` 并设置 `status="published"`。
6. MiniAPP 启动后并行读取 `GET /api/public/site-config` 与 `GET /api/public/products`。
7. MiniAPP 目的地页验证顶部主视觉来自 `site-config.destinationHero`，热门区域来自 `site-config.destinationRegions`，省内目的地卡片来自 `site-config.destinations`；点击区域或目的地后搜索结果能命中绑定商品。
8. 删除无商品引用的测试目的地应成功；删除仍被商品引用的目的地应返回 `409 MODULE_CONFIG_CONFLICT`。

## 需求页联调路径

1. Admin UI 登录后进入“需求线索”，页面模块名称与前台区块一一对应为“顶部定制说明”“服务说明卡”“需求表单配置”“热门推荐线路”“线索查询跟进”。
2. 在前 4 个配置模块中新增、编辑、删除、排序、启停；`demandForm` 为单例配置，不提供排序。
3. 在“热门推荐线路”选择已发布商品并调整顺序；该操作只维护商品 ID 关联，不删除商品本体。
4. MiniAPP 启动后并行读取 `GET /api/public/site-config` 与 `GET /api/public/products`。
5. MiniAPP 需求页验证顶部说明、服务卡、表单文案/快捷选项和热门推荐来自 `site-config`；缺字段或无匹配商品时回退本地内容。
6. 在需求页提交表单后，Admin UI “线索查询跟进”可按状态、来源、关键词、提交时间范围查询，并支持行内状态更新。

## 通用联调路径

1. 后端健康检查、迁移和 seed。
2. Admin UI 登录、读取 `GET /api/admin/site-config`。
3. Admin UI 页面模块新增、更新、删除、排序。
4. MiniAPP 启动并读取 `site-config` 与 `products`。
5. MiniAPP 提交线索，Admin UI 在线索列表查看并变更状态。
6. Admin UI 发布站点配置，MiniAPP 刷新验证展示结果。

## 验证命令

```powershell
Set-Location D:\www\znkj\WonderQ-Project\WonderQ-Admin
.\.venv\Scripts\python.exe -m pytest
```

```powershell
Set-Location D:\www\znkj\WonderQ-Project\WonderQ-Admin-UI
yarn build
```

```powershell
Set-Location D:\www\znkj\WonderQ-Project\WonderQ-MiniAPP
yarn test
```

本轮目的地页联调已执行：

- `WonderQ-Admin`: `.\.venv\Scripts\python.exe -m pytest`，69 passed；`.\.venv\Scripts\python.exe -m alembic upgrade head`，迁移到 `0007_destination_page_modules`。
- `WonderQ-Admin-UI`: `yarn build`，通过。
- `WonderQ-MiniAPP`: `yarn test`，11 passed；`yarn build:h5`、`yarn build:mp-weixin` 均通过。

本轮需求页配置与线索查询联调验证项：

- `WonderQ-Admin`: `.\.venv\Scripts\python.exe -m pytest`，78 passed；`.\.venv\Scripts\python.exe -m alembic upgrade head`，迁移到 `0008_demand_page_modules`。
- `WonderQ-Admin-UI`: “需求线索”结构页已接入 5 个模块；线索列表已接状态、来源、关键词、提交时间范围查询和行内状态更新；`yarn build` 通过。
- `WonderQ-MiniAPP`: 需求页已消费 `demandHero`、`demandFeatureCards`、`demandForm`、`demandRecommendations`；`yarn test`，13 passed；`yarn build:h5`、`yarn build:mp-weixin` 均通过。
- 浏览器检查：MiniAPP H5 需求页关键区块可见；Admin UI 侧边栏“需求线索”进入结构页后展示“顶部定制说明”“服务说明卡”“需求表单配置”“热门推荐线路”“线索查询跟进”五个模块。
- 未执行 `python -m app.seed`：本轮约束为不做内容重置或 seed 覆盖，避免改写开发库已有内容。

## 近期风险点

- `admin-api-requirements.md` 与 `module-config-api.md` 的边界必须保持清楚：前者描述管理端主接口，后者是页面模块 CRUD 的唯一细节来源。
- MiniAPP 依赖本地 fallback，接口为空和接口失败都要验证。
- 线索手机号等隐私字段只在必要页面展示，日志和文档示例不得出现真实值。
- 重置内容、seed、迁移、发布和回滚需要额外确认，避免影响生产数据。

## 更新规则

- 接口契约变化后，同步更新本文件对应状态。
- 状态从“需实测”改为“当前使用”前，必须完成本地三端联调验证。
- 新增模块时先写契约文档，再实现后端和前端调用。