suixinkan_ios_new/功能同步Checklist.md

# 功能同步 Checklist

更新时间：2026-06-29

## 状态说明

- 完成：UI、核心功能、文档和必要单元测试已同步，并通过编译验证。
- 部分完成：已有入口、壳、路由或部分主流程，但旧工程完整业务尚未迁移。
- 未开始：new 工程尚无对应真实业务页面或服务。
- 不迁移：已明确不纳入 iOS 迁移范围。

## 基础架构

| 状态 | 模块 | 同步内容 | 剩余事项 |
| --- | --- | --- | --- |
| 完成 | App 根结构 | `RootView` 按登录态切换登录页/主 Tab；主界面使用 `TabView`，每个 Tab 独立 `NavigationStack`。 | 持续随业务路由扩展。 |
| 完成 | Tab 导航 | 首页、订单、数据、我的四个 Tab；push 子页面时隐藏 TabBar。 | 后续新增真实子页面时继续复用 `AppRoute`。 |
| 完成 | 全局状态拆分 | `AppSession`、`AccountContext`、`PermissionContext`、`ScenicSpotContext`、`AppRouter`、`ToastCenter` 拆分。 | 继续避免新增大而全全局状态。 |
| 完成 | 登录态缓存 | token、账号快照、上次手机号、偏好使用 UserDefaults；冷启动恢复登录态。 | 后续业务缓存按账号和景区/门店作用域隔离。 |
| 完成 | 网络框架 | `APIClient`、`APIRequest`、`APIEnvelope`、统一错误处理和 token 注入。 | 业务 API 继续按模块拆分。 |
| 完成 | OSS 上传 | `UploadAPI`、`OSSUploadService`、上传策略、头像、实名图片、任务附件、云盘文件、相册文件、素材/样片文件、项目图片上传处理。 | 后续新上传场景继续复用。 |
| 完成 | 网络图片 | 新增 `RemoteImage` / `RemoteAvatarImage`，当前网络图片展示均使用 Kingfisher。 | 后续新页面禁止直接使用 `AsyncImage` 加载网络图片。 |
| 完成 | 设计常量 | `AppDesign`、`AppMetrics` 统一颜色、字号、间距等通用尺寸。 | 继续替换新页面中的零散常量。 |
| 完成 | 文档规范 | 已有 `AGENTS.md` 约束；现有模块均有模块说明文档。 | 后续每个新功能模块同步新增模块 md。 |

## 登录与账号上下文

| 状态 | 模块 | 同步内容 | 剩余事项 |
| --- | --- | --- | --- |
| 完成 | 登录页 | 登录 UI、手机号/密码登录、协议勾选、上次手机号恢复。 | 后续如有验证码登录再迁移。 |
| 完成 | 多账号选择 | 登录后多账号选择、临时 token 内存保存、选择后写正式 token。 | 继续跟随后端账号结构变化维护。 |
| 完成 | 账号上下文 | 用户信息、角色权限、景区列表、门店列表、当前景区/门店选择和恢复。 | 后续业务模块按当前上下文取数。 |
| 完成 | 景点/打卡点上下文 | 当前景区下景点/打卡点懒加载，失败不影响登录态。 | 打卡点管理页面已接入，后续可继续增强地图交互。 |
| 完成 | 权限菜单数据 | 递归解析角色权限、URI 去重、按旧工程顺序排序。 | 新 URI 出现时补路由映射或标记不支持。 |

## 首页

| 状态 | 模块 | 同步内容 | 剩余事项 |
| --- | --- | --- | --- |
| 完成 | 首页主 UI | 顶部景区、工作状态、位置上报卡、快捷操作、门店卡、常用应用网格。 | 视觉可随旧工程细节继续微调。 |
| 完成 | 首页权限菜单 | 从 `PermissionContext` 构建菜单，支持 URI 别名去重和旧工程排序。 | 未知 URI 继续通过诊断报告跟踪。 |
| 完成 | 常用应用 | 默认常用应用、添加/移除、UserDefaults 持久化、按权限过滤。 | 后续可加入拖拽排序。 |
| 完成 | 更多功能 | 全部功能页、常用应用增删、首页入口跳转。 | 未迁移功能仍进入占位页。 |
| 完成 | 首页路由壳 | 已迁移入口跳真实页面；订单/数据入口切换 Tab；未知入口安全占位。 | 按模块逐步替换占位页。 |
| 完成 | 景区选择入口 | 旧工程同款景区选择页、搜索、定位距离、景区卡片、封面、地址、营业状态、切换景区并持久化。 | 后续如有景区选择视觉细节变化再微调。 |
| 完成 | 权限申请入口 | `permission_apply`、`permission_apply_status`、`scenicapplication` 已接真实页面。 | 景区结算仍按独立模块后续迁移。 |

## 订单 Tab

| 状态 | 模块 | 同步内容 | 剩余事项 |
| --- | --- | --- | --- |
| 完成 | 订单 Tab 根页面 | 订单管理/核销订单分段入口。 | 后续继续补长尾订单流程。 |
| 完成 | 订单管理列表 | 景区上下文校验、状态筛选、手机号搜索、日期筛选、分页、刷新。 | 无。 |
| 完成 | 核销订单列表 | 核销列表、分页、刷新、手动输入订单号核销。 | 无。 |
| 完成 | 扫码核销 | AVFoundation 扫码、订单号解析、命中高亮、二次确认后核销。 | 后续可继续补扫码 UI 细节。 |
| 完成 | 订单详情 | 订单管理详情、核销订单详情、详情接口和列表摘要兜底。 | 无。 |
| 完成 | 押金订单 | 押金订单列表、手输订单号查详情、押金详情、押金核销、押金退款、押金拍摄信息。 | 后续可继续补押金订单 UI 细节和异常空态。 |
| 完成 | 退款流程 | 普通订单退款入口规则、全额/部分退款金额校验、退款提交和详情刷新。 | 复杂退款审核进度如后端需要可单独补。 |
| 完成 | 历史拍摄 | 多点位历史拍摄项目、拍摄点和媒体展示。 | 仅展示已有媒体，不做上传、删除、下载或编辑。 |
| 完成 | 任务上传 | 多点旅拍订单选择已核销打卡点、云盘素材、本地图片/视频 OSS 上传并提交素材。 | 仅 `orderType == 19` 展示。 |
| 完成 | 视频预告/尾片上传 | 进入订单尾片引导页，并复用相册预览上传。 | 没有独立订单尾片接口，暂不做尾片审核进度。 |
| 完成 | 订单来源/带客单绑定 | orderType 11/14 订单卡片展示「订单来源」Sheet；支持选择获客员与带客单绑定；全页 `ReferralOrderSelectView`；退款后同步带客单状态。 | 依赖 `CooperationOrderAPI` 与首页合作订单模块。 |

## 数据 Tab

| 状态 | 模块 | 同步内容 | 剩余事项 |
| --- | --- | --- | --- |
| 完成 | 数据看板 | 今日、昨日、7 日、本月时间段切换；统计汇总卡；每日明细。 | 后续按旧工程继续补图表细节。 |
| 完成 | 数据分页 | 日数据分页加载、切换时间段重置分页、加载失败保留当前数据。 | 持续跟随后端字段变化。 |
| 完成 | 角色接口分流 | 摄影师/景区管理员两套统计接口。 | 其他角色如有特殊逻辑再补。 |

## 个人中心

| 状态 | 模块 | 同步内容 | 剩余事项 |
| --- | --- | --- | --- |
| 完成 | 个人信息首页 | 头像、昵称、UID、姓名、手机号、账号状态、当前景区、退出登录。 | 后续可继续细化旧工程视觉。 |
| 完成 | 头像上传 | `PhotosPicker` 选图、压缩、OSS 上传、回写头像 URL、刷新账号快照。 | 后续可补裁剪体验。 |
| 完成 | 昵称编辑 | 昵称校验、保存、同步 `AccountContext`。 | 无。 |
| 完成 | 修改密码 | 密码弹窗、最小长度校验、接口提交。 | 无。 |
| 完成 | 账号切换 | 可切换账号列表、默认选中、set-user、刷新登录上下文。 | 无。 |
| 完成 | 实名认证 | 信息加载、短信验证码、身份证校验、证件图片选择、OSS 上传、提交审核。 | 后续可补示例图或拍照入口。 |
| 完成 | 系统设置 | 关于我们、版本号、下载链接、协议入口。 | 若旧工程有更多设置项需继续核对。 |
| 完成 | 协议页 | 关于我们、用户协议、隐私政策、钱包协议页面。 | 无。 |

## 首页子业务模块

| 状态 | 模块 | 当前情况 | 后续事项 |
| --- | --- | --- | --- |
| 完成 | 钱包 | 钱包首页、收益明细、提现记录、提现资格校验、提现申请、银行卡设置、积分兑换。 | `withdrawal_audit` 提现审核仍按独立管理模块后续迁移。 |
| 完成 | 提现审核 | 首页入口已接真实页面，复用提现记录接口展示审核列表、状态筛选、分页和详情时间线。 | 不做管理员审批操作，旧 Android 未体现对应操作接口。 |
| 完成 | 消息中心 | 消息列表、未读筛选、游标分页、已读/全部已读、详情和删除已接入。 | 本轮不新增后端未体现的批量接口。 |
| 完成 | 排队管理 | `/scenic-queue` / `queue_management` 已接真实页面；支持队列列表、叫号、过号、完成、重新排队、用户标记、设置、二维码、日志、实时监听和页面离开后的短轮询。 | 后续可继续按真实设备验证语音播报和后台活跃策略。 |
| 完成 | 立即收款/收款码 | 收款码、设置金额、动态二维码、保存二维码、收款记录、到账轮询、语音提醒。 | 后续可按业务继续优化收款反馈细节。 |
| 部分完成 | 押金订单 | 入口已识别，进入占位页。 | 迁移押金订单详情和拍摄信息。 |
| 完成 | 任务管理 | 任务列表、筛选、分页、任务详情、发布任务入口。 | 旧工程里订单/核销订单拼成待办任务的逻辑本轮未迁移，订单仍归订单 Tab 管理。 |
| 完成 | 发布任务 | 发布表单、选择订单、选择云盘文件、本地图片/视频 OSS 上传、提交任务。 | 完整云盘资产管理已由相册云盘模块接管，任务页只保留发布所需选择能力。 |
| 完成 | 日程管理 | 月份切换、日期标记、日程列表、下拉刷新、删除日程、新增排班、关联订单或手填订单号兜底。 | 后续如旧工程有排班详情页或高级重复规则再继续迁移。 |
| 完成 | 打卡点管理 | 列表、筛选、分页、详情、二维码、新建、编辑、删除、前台定位选点和图片 OSS 上传已接入。 | 后续可把高德地图完整选点 UI 替换进编辑页。 |
| 完成 | 摄影师项目管理 | `pm` / `project_edit` 已接真实页面；支持列表、搜索、分页、详情、新建、编辑、删除和项目图片 OSS 上传。 | 后续可继续补项目数据分析、项目订单深层流程。 |
| 完成 | 店铺项目管理 | `pm_manager` 已接真实页面；支持店铺项目列表、详情、新建、编辑、删除、多点位项目和押金项目。 | 后续如有店铺后台审核扩展再单独迁移。 |
| 完成 | 相册云盘 | 云盘文件/文件夹浏览、搜索筛选、排序、分页、上传、预览、下载、重命名、移动、删除、传输记录。 | 云盘下载只保存到 App 沙盒 `Documents/CloudDownloads`，不写入系统相册。 |
| 完成 | 相册管理 | 相册列表、搜索筛选、日期筛选、创建相册、相册详情、图片/视频列表、预览、设置封面、删除文件、编辑名称/备注。 | 后续如旧工程补充更多相册运营动作再继续迁移。 |
| 完成 | 相册预览上传 | `album_trailer` 入口已接真实页面；支持选择相册、本地图片/视频 OSS 上传、上传后入库到相册。 | 不恢复旧工程手填 URL 主流程。 |
| 完成 | 素材管理 | 素材列表、关键词/审核状态筛选、分页、详情、上传素材、编辑素材、上下架、删除、标签输入、素材文件 OSS 上传。 | 无。 |
| 完成 | 样片管理 | 样片列表、关键词/审核状态筛选、分页、详情、上下架、删除、上传样片、关联项目选择、样片文件 OSS 上传。 | 完整项目管理、样片编辑、视频播放器增强后续单独迁移。 |
| 完成 | 直播管理/直播相册 | `live_stream_management` 和 `live_album` 已接真实页面；支持直播列表、创建、详情、复制外部推流地址、开始/暂停/结束、推流模式切换、直播详情可播放 URL 预览、直播相册视频播放，以及直播相册筛选、上传素材、预览、删除相册和删除单个素材。 | 已按旧 iOS 对齐：不新增真推流 SDK，`push_url` 仅作为 OBS/第三方工具外部推流地址；页面保留推流诊断适配层，真 RTMP/RTC 推流 SDK 仍需后续单独选型和真机联调。 |
| 完成 | 景区申请 | 景区申请表单、地区选择、合作类型、图片选择、OSS 上传、待审核/驳回状态回填。 | 景区结算不属于本模块，后续单独迁移。 |
| 完成 | 权限申请 | 角色权限申请、景区多选、已有权限禁用、申请状态页、驳回编辑入口。 | 后续如有附件上传入口再补。 |
| 完成 | 景区结算 | 景区结算申请、金额/备注、多景区提交和结算审核记录已接入。 | 审核记录复用景区申请/权限申请记录，不新增后端未体现的详情审批操作。 |
| 完成 | 运营区域 | `operating-area` 已接真实页面；按店铺/景区管理员模式加载围栏，解析 `business_map_area` 并只读展示地图或模拟器坐标摘要。 | 本轮不做区域新增、编辑、删除或绘制保存。 |
| 完成 | 位置上报 | 当前位置、标记点、在线状态、立即上报、提醒设置、历史记录、筛选和分页已接入。 | 本轮不做后台定位、离线队列或推送提醒。 |
| 完成 | 注册邀请 | 邀请码、邀请链接、二维码、复制链接、规则展示、邀请记录和奖励记录已接入。 | 邀请二维码不落盘，后续如需分享图片再临时生成。 |
| 完成 | 飞手认证 | `pilot_cert` 已接真实页面；支持实名状态、认证详情、验证码、证件图 OSS 上传、首次提交和驳回编辑。 | 不包含 DJI/飞控 SDK 或真实飞行控制。 |
| 完成 | 合作订单 | `cooperation_order` 已接真实页面；双 Tab 列表（获客线索/获客订单）、合作获客员、扫码绑定、主 Tab 扫码识别 sale_user_bind。 | 与订单模块 orderType 11/14 订单来源联动。 |
| 不迁移 | 飞控/DJI | `fly` / `pilot_controller` 已明确为 iOS 不支持。 | 不再迁移。 |

## 旧工程能力尚未系统迁移

| 状态 | 模块 | 说明 |
| --- | --- | --- |
| 完成 | Assets 模块 | 已迁移相册管理、相册预览上传、相册云盘、素材管理、样片管理和上传样片。 |
| 未开始 | Core/Map | 旧工程地图相关能力尚未迁移。 |
| 未开始 | Core/Push | 旧工程推送能力尚未迁移。 |
| 完成 | Core/Queue | 已迁移排队 WebSocket、远端叫号去重、语音播报和短轮询运行时。 |
| 未开始 | Core/Validation | 旧工程独立校验能力尚未系统迁移；当前只迁移了实名身份证校验等必要逻辑。 |
| 未开始 | UIKit 旧代码 | 旧工程 UIKit 目录下的兼容/旧版页面尚未迁移，除非后续明确仍需保留。 |

## 最近验证记录

已通过：

```bash
xcodebuild test -workspace suixinkan.xcworkspace -scheme suixinkan -destination 'platform=iOS Simulator,name=iPhone 17'
xcodebuild build -workspace suixinkan.xcworkspace -scheme suixinkan -destination 'generic/platform=iOS Simulator'
```

## 下一批建议迁移顺序

1. 直播真推流 SDK：旧 iOS 未接入真推流 SDK，当前已按旧 iOS 对齐为外部 `push_url` + 推流诊断；如后续需要真 SDK，可在腾讯/TRTC、RTMP SDK 等方案明确后替换 `LivePushAdapter` 实现并补真机联调。
2. 订单尾片深层能力：等后端明确独立尾片接口后，再补自动关联订单、审核进度和视频播放器增强。