suixinkan_ios_new/suixinkan/Features/ScenicPromotion/ScenicPromotion.md

ScenicPromotion 模块业务逻辑

模块职责

ScenicPromotion 模块负责首页 promotion_page 入口，为摄影师和景区运营提供景区宣传与排队导览 Demo 页面。

当前阶段使用 Mock 数据完成业务闭环，不接入真实后端接口、真实视频地址或真实二维码。

页面流程

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