移动端（iOS）
移动端交付受系统版本、审核、权限与后台策略约束。本篇以 Apple 平台与 Swift 为主（个人项目与产品主线），Android 仅在需双端时通过 KMP/共享逻辑处理，UI 仍分平台。
平台约束速览
| 约束 | 影响 |
|---|---|
| 应用生命周期 | 后台时间短；状态恢复、场景（Scene） |
| 权限 | 相机、位置、通知需时机化请求与用途字符串 |
| 分发 | App Store 审核、签名、TestFlight |
| 设备碎片 | 屏幕、动态岛、辅助功能、性能档位 |
SwiftUI 结构（默认）
| 层级 | 职责 |
|---|---|
| View | 声明式 UI、无副作用 body |
| Model | @Observable / 值类型状态 |
| 服务 | 网络、持久化、系统 API（通过协议注入） |
导航：NavigationStack + 类型安全路由；深链用 onOpenURL 统一入口。
并发：UI 更新在 @MainActor；重活 Task offload；跨 actor 传值遵守 Sendable。
提示
预览驱动：为复杂视图写 #Preview，用 mock 服务减少真机往返。
与架构分层对齐
| 整洁架构角色 | Swift 落地 |
|---|---|
| 领域 | 纯 Swift 类型、无 UIKit/SwiftUI import |
| 用例 | async 服务、协调 repository |
| 适配器 | URLSession、SwiftData/Core Data、Keychain |
| 表现 | SwiftUI View + ViewModel（薄） |
数据流：单向——用户事件 → 用例 → 状态快照 → View。避免 View 直接调 SDK。
持久化选择
| 方案 | 适用 |
|---|---|
| UserDefaults / Keychain | 设置、令牌（密钥仅 Keychain） |
| SwiftData / Core Data | 结构化离线、关系查询 |
| 文件 / CloudKit | 大对象、跨设备同步（需设计冲突） |
迁移：schema 版本 + 轻量迁移测试；与 CI 联动的 UI 测试跑在模拟器矩阵。
网络与离线
- API 客户端统一超时、重试策略、可取消
Task - 列表页：占位 + 增量加载；错误态可重试
- 幂等写操作带 client id，配合服务端去重
发布清单
| 步骤 | 动作 |
|---|---|
| 版本号 | Marketing version + build 单调递增 |
| 签名 | 自动签名或 CI 分发证书（密钥不进仓库） |
| 隐私 | Privacy Nutrition Labels、用途字符串与实现一致 |
| 测试 | TestFlight 内测 → phased release |
| 监控 | 崩溃（MetricKit/第三方）、关键漏斗 |
与 Git 工作流 联动：tag 触发 archive / upload。
质量与可访问性
- Dynamic Type、VoiceOver 标签、足够点击区域
- 减少纯手势唯一路径；提供可见控件
- 性能：Instruments 查主线程卡顿、过度 SwiftUI body 重算