汉秋
1b1e93b9ca
从 xh_test 同步 ScenicPromotion 演示页，补齐 MVVM 结构、本地资源、单元测试与模块文档，注册 promotion_page 首页入口。 Co-authored-by: Cursor <cursoragent@cursor.com>
80 lines
3.3 KiB
Markdown
80 lines
3.3 KiB
Markdown
# ScenicPromotion 模块业务逻辑
|
||
|
||
## 模块职责
|
||
|
||
ScenicPromotion 模块负责首页 `promotion_page` 入口，为摄影师和景区运营提供景区宣传与排队导览 Demo 页面。
|
||
|
||
当前阶段使用 Mock 数据完成业务闭环，不接入真实后端接口、真实视频地址或真实二维码。
|
||
|
||
## 页面流程
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
Home[宣传页主页面] -->|QR 三连击 + 密码 1| Settings[宣传页设置]
|
||
Home -->|缩略图点击| Hero[底部主视觉联动]
|
||
Settings --> Preview[素材预览]
|
||
Settings -->|Mock 上传/删除| Settings
|
||
Settings -->|提交| Submit[Mock 提交结果]
|
||
```
|
||
|
||
## 核心实体
|
||
|
||
| 类型 | 说明 |
|
||
| --- | --- |
|
||
| `ScenicPromotionBoard` | 宣传页看板：景区名、副标题、打卡点列表 |
|
||
| `ScenicPromotionSpot` | 单个打卡点：排队信息 + 视频/照片素材 |
|
||
| `ScenicPromotionQueueInfo` | 排队人数、等待时间、叫号信息 |
|
||
| `ScenicPromotionMedia` | 横向素材与主视觉共用数据 |
|
||
| `ScenicPromotionQueuePoint` | 设置页排队打卡点（多选绑定） |
|
||
| `ScenicPromotionMaterialPoint` | 设置页素材所属打卡点（单选，与排队点独立） |
|
||
| `ScenicPromotionManagedMaterial` | 设置页已上传 Mock 素材 |
|
||
|
||
## 数据来源
|
||
|
||
- 全部 Mock 数据由 `ScenicPromotionMockStore` 提供种子数据。
|
||
- `ScenicPromotionViewModel` 驱动主页面状态与素材选中。
|
||
- `ScenicPromotionSettingsViewModel` 独立管理设置页排队绑定与素材上传。
|
||
|
||
## 主页面规则
|
||
|
||
1. 打卡点由接口返回列表动态展示；Mock 含网红桥、汉地拔冲、空中草原、河谷花海、雪山栈道。
|
||
2. 5 个以内等分展示，超过 5 个时一屏露出 5 个并横向滚动。
|
||
3. 缩略图点击只联动底部主视觉，不跳转二级页。
|
||
4. 视频主视觉点击仅展示模拟播放提示。
|
||
5. 二维码快速点击 3 次（1.1 秒内）→ 密码弹窗 → 输入 `1` 进入设置页。
|
||
6. 长按二维码可切换演示状态（正常 / 无媒体 / 无排队 / 加载 / 异常 / 空数据）。
|
||
|
||
## 设置页规则
|
||
|
||
1. 排队打卡点支持多选绑定；提交前至少选一个。
|
||
2. 素材所属打卡点与排队打卡点是两套独立数据。
|
||
3. 视频/图片上传前必须先选择素材所属打卡点。
|
||
4. 上传、删除、提交均为 Mock 本地状态变更。
|
||
|
||
## 路由
|
||
|
||
- 权限 URI：`promotion_page`
|
||
- 首页路由：`HomeRoute.scenicPromotion`
|
||
- 入口依赖权限下发或用户手动添加到常用应用（`HomeCommonMenuStore.androidHomeMenuURIs` 白名单已包含该 URI）。
|
||
|
||
## 与相邻模块的边界
|
||
|
||
| 模块 | URI | 用途 | 后端 |
|
||
| --- | --- | --- | --- |
|
||
| ScenicPromotion | `promotion_page` | 景区宣传与排队导览 Demo | Mock |
|
||
| QueueManagement | `queue_management` | 真实排队叫号管理 | 真实 API |
|
||
| Assets | `asset_management` | 素材库管理 | 真实 API |
|
||
|
||
## 测试要求
|
||
|
||
- `ScenicPromotionTests`：主页面与设置页 ViewModel 成功路径、场景切换、上传校验。
|
||
- `HomeMenuRouterTests`：`promotion_page` 路由映射。
|
||
|
||
## 主要文件
|
||
|
||
- `Models/ScenicPromotionModels.swift` — 状态枚举与数据实体
|
||
- `Services/ScenicPromotionMockStore.swift` — Mock 种子数据
|
||
- `ViewModels/ScenicPromotionViewModels.swift` — 主页面与设置页 ViewModel
|
||
- `Views/ScenicPromotionViews.swift` — 主页面
|
||
- `Views/ScenicPromotionSettingsViews.swift` — 设置页与素材预览
|