docs: 更新项目文档与架构说明

docs/architecture.md

@@ -0,0 +1,51 @@
+# 架构
+
+## 分层与依赖
+
+依赖单向无环：`App → feature/* → core/*`，`App` 额外依赖 `CoreRepository` 装配具体实现。
+
+```
+App ──► FeatureHome / FeatureCheckin / FeaturePlan / FeatureProfile / FeatureAuth
+         │
+         └──► CoreDomain（协议 + UseCase）──► CoreModel
+                ▲
+                └── CoreRepository（Fake* 实现）
+```
+
+- **CoreModel**：领域模型，`Sendable` 值类型，叶子不依赖任何模块。
+- **CoreDomain**：Repository 协议 + UseCase，纯 Swift（不 import SwiftUI / 数据框架）。
+- **CoreRepository**：Fake 实现（当前），未来替换为 OfflineFirst（编排 CoreNetwork / CoreDatabase）。
+
+## 数据流（MVVM 单向）
+
+```
+Screen(.task) ──► ViewModel.load() ──► UseCase ──► Repository（AsyncThrowingStream）
+       ▲                                          │
+       └────────── uiState（@Observable）◄──── yield
+```
+
+- ViewModel：`@MainActor @Observable final class`，`private(set) var uiState`。
+- UiState：`enum` 关联值（对应 Kotlin sealed interface）。
+- 每次 `load()` 先 `loadTask?.cancel()` 再开新 `Task`，实现 `flatMapLatest` 语义。
+
+## 会话 / 登录态
+
+`SessionRepository` 持进程内登录态（Fake 用 Combine `CurrentValueSubject<Bool, Never>`），`AppContainer` 持单例注入所有 ViewModel。
+
+- 外层 `Task` 观察 `observeIsLoggedIn()`；登录态变化 → 取消内层数据 `Task` → 重新订阅。
+- **Home**：已登录 `observeHome()`（isGuest=false）/ 游客 `observeGuestHome()`（isGuest=true），无 `loggedOut` 态（游客落地页即未登录首页）。
+- **checkin / plan / profile**：登录态 false → `.loggedOut`；true → `.loading` → 数据。
+
+## Feature 一览
+
+| Feature | UiState | 数据源（Repository）|
+|---|---|---|
+| FeatureHome | loading / success(HomeData, isGuest) / error | observeHome / observeGuestHome |
+| FeatureCheckin | loading / success(CheckinRecord) / loggedOut / error | observeCheckin + submitCheckin |
+| FeaturePlan | loading / success(PlanRecord) / loggedOut / error | observePlan（+ observePlanSubmit / savePlan）|
+| FeatureProfile | loading / success(UserProfile) / loggedOut / error | observeProfile |
+| FeatureAuth | 表单态（isSendingCode / countdownSeconds / isSubmitting / errorMessage）| requestSmsCode / login |
+
+## 设计 tokens
+
+品牌色 / 状态色 / 渐变定义在 `DesignSystem/DesignTokens.swift`（`DS.Color` / `DS.Gradient`），对齐 wechat-clock-mini / android-client 的 designsystem。