# 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` — 设置页与素材预览