suixinkan_ios_new/suixinkan/Features/Auth/Auth.md

Auth 模块业务逻辑

模块职责

Auth 模块负责登录页、手机号密码登录、多账号选择和账号选择后的正式登录确认。

该模块只处理登录流程本身：

• 表单输入、校验和协议确认。
• 调用 v9 登录接口获取临时 token 和账号列表。
• 单账号时自动调用 set-user。
• 多账号时展示账号选择页。
• 选择账号后调用 set-user 换取正式 token。

正式 token 存储、账号快照和全局登录态写入由 App 模块的 AuthSessionCoordinator 统一处理。

核心对象

• LoginView：登录页 UI，展示手机号、密码、协议确认和登录按钮。
• AccountSelectionView：多账号选择弹窗，展示景区账号和门店账号。
• LoginViewModel：维护表单状态、校验状态、登录请求状态和多账号选择状态。
• AuthAPI：封装 /api/app/v9/login 和 /api/app/v9/set-user。
• LoginRequest：登录请求体。
• SetUserRequest：账号选择请求体。
• V9AuthResponse：v9 登录和 set-user 响应。
• V9ScenicUser / V9StoreUser：后端返回的景区账号和门店账号。
• AccountSwitchAccount：统一后的可选择账号模型。

登录流程

1. 用户输入手机号和密码。
2. LoginViewModel.validateForLogin 校验手机号、密码和协议勾选状态。
3. 未勾选协议时，LoginView 弹出协议确认 Sheet。
4. 校验通过后，LoginViewModel.login 调用 AuthAPI.login。
5. 登录接口返回临时 token 和可用账号列表。
6. LoginViewModel 过滤掉业务账号 ID 无效的账号。
7. 没有可用账号时抛出 LoginFlowError.noAvailableAccount。
8. 只有一个账号时，自动调用 AuthAPI.setUser，并返回 .completed。
9. 多个账号时，保存 AccountSelectionPayload，并返回 .needsAccountSelection。
10. LoginView 展示 AccountSelectionView。
11. 用户确认账号后，LoginViewModel.selectAccount 使用临时 token 调用 set-user。
12. set-user 返回正式 token 后，LoginView 调用 AuthSessionCoordinator.completeLogin 写入 token，并同步用户资料、角色权限、景区和门店。

账号模型转换

后端景区账号和门店账号字段不完全一致，统一转换为 AccountSwitchAccount：

• 景区账号通过 ssUserId、scenicUserId、userId、id 兜底生成业务账号 ID。
• 门店账号通过 storeUserId、userId、id 兜底生成业务账号 ID。
• AccountSwitchAccount.toSetUserRequest 根据账号类型生成 store_user_id 或 ss_user_id。

V9AuthResponse 还会派生：

• accounts：合并后的账号选择列表。
• primaryProfile：登录后用于全局展示的账号资料。
• scenicScopes：当前账号可用景区作用域。
• storeScopes：当前账号可用门店作用域。

缓存规则

Auth 模块不直接写缓存。登录成功后的缓存由 AuthSessionCoordinator 负责：

• 正式 token 写 UserDefaults。
• 上次手机号和协议状态写 UserDefaults。
• 账号资料、当前角色和业务作用域写入账号快照。

临时 token 只存在于 AccountSelectionPayload，不落盘。