WonderQ-Project/docs/development-status.md

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 刷新验证展示结果。

验证命令

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

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

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、迁移、发布和回滚需要额外确认，避免影响生产数据。

更新规则

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