# 功能同步 Checklist（UIKit 工程）

更新时间：2026-06-26  
工程：[`suixinkan_ios_new_uikit`](.)（Swift + UIKit + SnapKit）  
参考：[`../suixinkan_ios_new`](../suixinkan_ios_new)（SwiftUI）

## 同步进度摘要

| 维度 | 状态 |
| --- | --- |
| 代码同步（阶段 0–5） | **完成** — Core / 登录 / 四 Tab / 子业务模块均有 UIKit 实现 |
| 单元测试 | **完成** — `xcodebuild test` 全绿 |
| 高德地图 | **完成（真机）** — Pod 已接入；模拟器自动降级 |
| 推送 | **完成** — `PushNotificationManager` + `AppDelegate` APNs 回调 |
| UI 视觉还原 | **部分完成** — 功能对齐，细节待逐页走查 |
| XCUITest | **未开始** — 可选后续补充 |

## 状态说明

- **完成**：UIKit 页面、ViewModel、必要单测已同步，编译与测试通过。
- **部分完成**：主流程可用，但与参考工程在 UI 细节或平台能力上仍有差距。
- **未开始**：UIKit 工程尚无对应实现。
- **不迁移**：参考工程已明确不纳入 iOS 范围。

---

## 基础架构

| 状态 | 模块 | UIKit 实现 | 剩余事项 |
| --- | --- | --- | --- |
| 完成 | App 根结构 | `RootViewController` 监听登录阶段；登录后 `MainTabBarController` 作为 window 根控制器 | 持续随路由扩展 |
| 完成 | Tab 导航 | 系统 UITabBarController 五入口（首页、订单、扫码、数据、我的）+ 独立 `TabNavigationController`；扫码入口拦截后 present 扫码页，push 子页隐藏 TabBar。 | 后续新增真实子页面时继续复用 `AppRoute`。 |
| 完成 | 全局状态 | `AppServices.shared` 注入 Session / Context / Router / Toast / Loading | 避免新增 monolith 状态 |
| 完成 | 登录态缓存 | Keychain token + UserDefaults 快照 / 偏好 + 冷启动恢复 | — |
| 完成 | 网络框架 | `APIClient` / `APIEnvelope` / 统一错误与 token | — |
| 完成 | OSS 上传 | `UploadAPI` + `OSSUploadService` | — |
| 完成 | 网络图片 | `UIImageView` + Kingfisher 扩展 | — |
| 完成 | 设计常量 | `AppDesign`（UIColor）+ `AppMetrics` | 新页继续复用 |
| 完成 | 文档规范 | `AGENTS.md` + 各 Feature 模块 `.md` | 新模块同步补文档 |

---

## 平台能力

| 状态 | 模块 | UIKit 实现 | 剩余事项 |
| --- | --- | --- | --- |
| 完成 | Core/Map | CocoaPods 高德 SDK；`OperatingAreaMapView` 围栏 polygon；`PunchPointMapPickerView` 点选 + 逆地理；模拟器坐标摘要兜底 | 在 `Info.plist` 填写 `AMapAPIKey` 后真机验证 |
| 完成 | Core/Push | `PushNotificationManager`；`AppDelegate` 注册 token 与远程通知 | 真机验证 APNs 与后端联调 |
| 完成 | Core/Queue | `ScenicQueueRuntime` WebSocket + 叫号 | 真机验证语音播报策略 |
| 部分完成 | Core/Validation | `AppFormValidator` + 各表单页内联校验 | 未单独抽离全部校验规则 |
| 完成 | Lottie Loading | SPM `Lottie` + `GlobalLoadingOverlayView` | — |
| 不迁移 | 旧 UIKit 兼容页 | — | 参考工程 legacy UIKit 目录不迁移 |

---

## 登录与账号

| 状态 | 模块 | UIKit 实现 | 剩余事项 |
| --- | --- | --- | --- |
| 完成 | 登录页 | `LoginViewController` | — |
| 完成 | 多账号选择 | `AccountSelectionViewController` | — |
| 完成 | 账号上下文 | `AccountContext` / `PermissionContext` / `ScenicSpotContext` | — |
| 完成 | 权限菜单 | `HomeMenuRouter` URI 映射 | 未知 URI 进占位页并记录诊断 |

---

## 四 Tab 主功能

| Tab | 状态 | UIKit 入口 | 备注 |
| --- | --- | --- | --- |
| 首页 | 完成 | `HomeViewController` | 权限菜单、常用应用、景区选择 |
| 订单 | 完成 | `OrdersViewController` | 含扫码、详情、押金、退款、尾片等 |
| 数据 | 完成 | `StatisticsViewController` | 时间段 + 汇总 + 日明细 |
| 我的 | 完成 | `ProfileViewController` | 头像 OSS、改密、实名、设置、协议 |

---

## 首页子业务模块

| 状态 | 模块 | UIKit ViewController |
| --- | --- | --- |
| 完成 | 钱包 | `WalletViewControllers` |
| 完成 | 提现审核 | `WithdrawalAuditViewController` |
| 完成 | 消息中心 | `MessageCenterViewController` |
| 完成 | 排队管理 | `QueueManagementViewControllers` |
| 完成 | 立即收款 | `PaymentCollectionViewController` |
| 完成 | 任务 / 发布任务 | `TaskViewControllers` |
| 完成 | 日程管理 | `ScheduleViewControllers` |
| 完成 | 打卡点管理 | `PunchPointViewControllers`（含地图选点） |
| 完成 | 项目管理 / 店铺项目 | `ProjectViewControllers` |
| 完成 | 相册 / 云盘 / 素材 / 样片 | `AssetsViewControllers` |
| 完成 | 直播 / 直播相册 | `LiveViewControllers` |
| 完成 | 景区 / 权限 / 结算 | `ScenicPermissionViewControllers` / `ScenicSettlementViewControllers` |
| 完成 | 运营区域 | `OperatingAreaViewController`（含围栏地图） |
| 完成 | 位置上报 | `LocationReportViewControllers` |
| 完成 | 注册邀请 | `InviteViewControllers` |
| 完成 | 飞手认证 | `PilotCertificationViewController` |
| 不迁移 | 飞控 / DJI | `HomeMenuRouter` 标记 unsupported |

---

## 已知差异（相对 SwiftUI 参考工程）

| 项目 | 说明 |
| --- | --- |
| UI 视觉 | UITableView 功能型布局，非 SwiftUI 像素级还原 |
| 直播推流 | 无真 RTMP SDK，外部 `push_url` + 诊断层（与参考工程一致） |
| 订单尾片 | 无独立尾片审核进度接口 |
| 高德 Key | 需在 `Info.plist` → `AMapAPIKey` 填入控制台 Key（Bundle ID: `com.hanqiu.suixinkan-ios`） |

---

## 验证命令

```bash
# 编译（模拟器）
xcodebuild -workspace suixinkan_ios.xcworkspace -scheme suixinkan_ios \
  -destination 'generic/platform=iOS Simulator' build

# 单元测试
xcodebuild test -workspace suixinkan_ios.xcworkspace -scheme suixinkan_ios \
  -destination 'platform=iOS Simulator,name=iPhone 17'
```

最近验证：**BUILD SUCCEEDED** / **TEST SUCCEEDED**（2026-06-26）

---

## 后续可选

1. 真机填入 `AMapAPIKey` 并验证运营区域围栏、打卡点地图选点。
2. 逐页 UI 走查，对齐 SwiftUI 参考工程视觉与交互细节。
3. 新增 `suixinkan_iosUITests` 做关键流程自动化。