Machi iOS 离线优先工程指南

Machi iOS 是一个城市本地生活与同城社交客户端，它不是一个只调用接口的壳。用户需要在首页、发现、发布、私信、通知和个人页之间高频切换，也可能在弱网环境下继续浏览和起草内容。

架构目标

• 本地数据层足够稳定，离线时仍能提供基础体验。
• 远端同步流程可恢复，避免一次失败导致状态混乱。
• 账号凭据和用户数据有清晰边界。
• iOS 与 Web 共用后端事实，但保留平台交互差异。

分层方式

1. SwiftUI 负责界面、状态绑定和 NavigationStack 路由。
2. SwiftData 负责本地持久化、Schema 版本和迁移恢复。
3. Repository 负责隔离本地实体读写。
4. Service 负责认证、网络、媒体、同步、地区目录和通知偏好。
5. Keychain 负责 Bearer Token，避免敏感凭据明文落地。

离线优先流程

用户先和本地状态交互，系统再根据连接状态决定是否同步。ConnectivityMonitor 负责感知网络变化，RemoteSyncService 负责把本地草稿、Feed 状态和互动数据与统一后端对齐。

迁移与恢复

SwiftData 的价值不只是保存数据，更重要的是让 App 可以在模型演进时继续运行。Machi 使用版本化 Schema 和迁移恢复策略，遇到本地容器异常时优先尝试修复，而不是直接让用户失去使用入口。

工程判断

我选择无第三方依赖，是为了让第一版产品的工程边界更干净。SwiftUI、SwiftData、Foundation、Security、Network 和 URLSession 已经足够支撑一个可运行、可维护、可同步的原生客户端。