Initial commit

suixinkan/Core/Core.md

@@ -0,0 +1,65 @@
+# Core 模块业务逻辑
+
+## 模块职责
+
+Core 模块提供跨业务复用的基础能力，包括网络请求、缓存存储和通用设计常量。业务页面不应直接重复实现这些能力。
+
+主要子模块：
+- `Networking`：统一 API 请求、响应解析、错误处理和 token 注入。
+- `Storage`：统一登录 token、账号快照和 App 偏好的本地存储。
+- `Design`：统一颜色、字号、间距、控件尺寸和圆角。
+
+## Networking
+
+`APIClient` 是统一网络客户端，负责：
+- 根据 `APIRequest` 生成 `URLRequest`。
+- 注入公共 Header：`Content-Type`、`Accept`、App 版本和系统类型。
+- 通过 token provider 或 `tokenOverride` 注入登录 token。
+- 发送请求并处理 URLSession 错误。
+- 校验 HTTP 状态码。
+- 解码后端统一 `APIEnvelope`。
+- 将 HTTP 错误、业务错误、解析错误转成 `APIError`。
+
+业务模块只应该封装自己的 API 类，例如 `AuthAPI`、`ProfileAPI`，然后调用 `APIClient.send`。页面和 ViewModel 不应直接拼接 URL 或处理原始响应体。
+
+### 响应约定
+
+后端响应通过 `APIEnvelope<Response>` 解包：
+- `code` 表示业务状态。
+- `msg` 表示业务提示。
+- `data` 是真正业务数据。
+
+`APIEnvelope.isSuccess` 为 false 时，`APIClient` 抛出 `APIError.serverCode`。
+
+### token 失效判断
+
+`APIError.isAuthenticationExpired` 用于判断是否需要清空登录态：
+- HTTP 401 / 403 视为登录失效。
+- 业务码 `200001` 视为登录失效。
+- 错误文案包含 token、过期、登录失效、重新登录、unauthorized、验证失败等关键词时视为登录失效。
+
+## Storage
+
+本地缓存按安全级别拆分：
+- `SessionTokenStore`：使用 Keychain 保存正式 token。
+- `AccountSnapshotStore`：使用 UserDefaults 保存非敏感账号快照。
+- `AppPreferencesStore`：使用 UserDefaults 保存上次手机号、协议同意状态等偏好。
+
+缓存边界：
+- 正式 token 只放 Keychain。
+- 临时 token 只放内存。
+- 密码、验证码、OSS STS token、一次性扫码结果和错误提示不落盘。
+- 头像图片缓存交给 Kingfisher，Core 不保存图片 Data。
+
+`AccountSnapshot` 保存可重建的账号展示和业务上下文：
+- `AccountProfile`
+- 账号类型和业务账号 ID
+- 当前角色 ID
+- 景区作用域和门店作用域
+- 当前景区 ID 和当前门店 ID
+
+## Design
+
+`AppDesign` 管理跨页面颜色。`AppMetrics` 管理常用字号、间距、控件尺寸、行距和圆角。
+
+新增页面时优先使用 `AppMetrics` 和 `AppDesign`。只有明显属于单个页面的特殊尺寸，才保留在页面本地。