汉秋
ae0bc116d8
为 album_list 与 album_trailer 接入首页路由，在 Profile 中新增 DEBUG 首页菜单预览，并扩展 Assets 测试。 Co-authored-by: Cursor <cursoragent@cursor.com>
123 lines
6.2 KiB
Markdown
123 lines
6.2 KiB
Markdown
# Profile 模块业务逻辑
|
||
|
||
## 模块职责
|
||
|
||
Profile 模块负责“我的/个人信息”页面及其二级页面，包括用户资料展示、昵称编辑、账号切换、密码修改、实名认证、系统设置、协议页和退出登录。
|
||
|
||
该模块聚焦个人资料业务：
|
||
- 拉取用户基础资料。
|
||
- 拉取实名认证信息。
|
||
- 展示头像、昵称、UID、手机号、账号状态和实名认证状态。
|
||
- 修改昵称和头像。
|
||
- 修改密码。
|
||
- 切换当前景区/门店业务账号。
|
||
- 提交实名认证基础资料。
|
||
- 展示系统设置、版本号、下载链接和协议 H5 页面。
|
||
- 退出登录入口。
|
||
|
||
登录态清理和缓存清理由 App 模块的 `AuthSessionCoordinator` 统一处理。
|
||
|
||
DEBUG 构建下，“我的”列表会额外展示“首页调试”入口，进入 `DebugHomeMenuPreviewView` 后可查看并跳转所有已知首页菜单，不读取角色权限。该入口只用于迁移预览和调试，不进入 Release 包。
|
||
|
||
## 核心对象
|
||
|
||
- `ProfileView`：个人信息页 UI，负责展示资料、编辑入口、密码弹窗和退出确认。
|
||
- `ProfileViewModel`：维护资料加载状态、编辑状态、保存状态和展示文案。
|
||
- `ProfileRoute`：个人中心二级页面路由。
|
||
- `AccountSwitchView` / `AccountSwitchViewModel`：账号切换页面和状态逻辑。
|
||
- `RealNameAuthView` / `RealNameAuthViewModel`：实名认证页面和表单逻辑。
|
||
- `SettingsCenterView` / `AgreementView`：设置中心和协议 H5 页面。
|
||
- `DebugHomeMenuPreviewView`：DEBUG 专用首页菜单预览页，不参与正式业务流程。
|
||
- `ProfileAPI`：封装用户资料、实名认证和资料更新接口。
|
||
- `OSSUploadService`：上传头像和实名认证证件图片，返回可提交给业务接口的 OSS URL。
|
||
- `UserInfoResponse`：用户基础资料。
|
||
- `RealNameInfoResponse` / `RealNameInfo`：实名认证信息。
|
||
- `UpdateInfoRequest`：昵称、密码或头像更新请求体。
|
||
- `RealNameAuthRequest`：实名认证提交请求体。
|
||
|
||
## 加载流程
|
||
|
||
1. `ProfileView.task` 进入页面时调用 `reloadProfile(showToast: false)`。
|
||
2. 下拉刷新时调用 `reloadProfile(showToast: true)`。
|
||
3. `ProfileViewModel.reload` 并发请求：
|
||
- `ProfileAPI.userInfo`
|
||
- `ProfileAPI.realNameInfo`
|
||
4. 请求成功后更新 `userInfo` 和 `realNameInfo`。
|
||
5. `ProfileView` 将最新 `userInfo` 交给 `AuthSessionCoordinator.refreshCachedProfile`。
|
||
6. 协调器更新 `AccountContext.profile`，并同步刷新账号快照。
|
||
|
||
## 资料编辑流程
|
||
|
||
1. 用户点击编辑按钮。
|
||
2. `ProfileViewModel.beginEditing` 进入编辑状态，并把当前昵称写入编辑框。
|
||
3. 用户点击头像时通过 `PhotosPicker` 选择本地图片。
|
||
4. `AvatarImageProcessor` 将头像压缩为 JPEG，并暂存在内存中。
|
||
5. 用户提交后，`ProfileViewModel.saveProfile` 校验昵称非空。
|
||
6. 头像变化时先调用 `OSSUploadService.uploadUserAvatar` 上传到 OSS。
|
||
7. 头像上传成功后调用 `ProfileAPI.updateUserAvatarURL` 回写头像 URL。
|
||
8. 昵称变化时调用 `ProfileAPI.updateUserInfo(nickname:)`。
|
||
9. 接口成功后本地更新 `userInfo.nickname` 和 `userInfo.avatar`。
|
||
10. `ProfileView` 刷新全局账号资料和账号快照。
|
||
|
||
## 密码修改流程
|
||
|
||
1. 用户打开 `PasswordUpdateSheet`。
|
||
2. 输入新密码并点击完成。
|
||
3. `ProfileViewModel.updatePassword` 校验密码至少 6 位。
|
||
4. 校验通过后调用 `ProfileAPI.updateUserInfo(password:)`。
|
||
5. 成功后关闭弹窗并展示 Toast。
|
||
|
||
密码不会写入本地缓存。
|
||
|
||
## 账号切换流程
|
||
|
||
1. 用户点击“当前账号”进入 `AccountSwitchView`。
|
||
2. `AccountSwitchViewModel.load` 调用 `ProfileAPI.switchableAccounts`，读取 `/api/app/v9/accounts`。
|
||
3. 页面展示景区账号和门店账号，优先选中后端标记的当前账号，否则选中第一项。
|
||
4. 用户确认后调用 `AuthAPI.setUser`，使用 `AccountSwitchAccount.toSetUserRequest()` 生成请求体。
|
||
5. 切换成功后调用 `AuthSessionCoordinator.completeLogin`，重新写入正式 token、账号快照、权限、景区和门店上下文。
|
||
6. `AppRouter.reset()` 清空旧路由栈并回到首页。
|
||
|
||
## 实名认证流程
|
||
|
||
1. 用户点击“认证状态”进入 `RealNameAuthView`。
|
||
2. `RealNameAuthViewModel.load` 调用 `ProfileAPI.realNameInfo` 并回填姓名、身份证号、证件有效期、图片 URL 和审核状态。
|
||
3. 用户可发送短信验证码，接口为 `/api/yf-handset-app/photog/real-name/sms-verify-code`。
|
||
4. 用户通过图片卡片选择身份证人像面和国徽面。
|
||
5. `RealNameImageProcessor` 将证件图片压缩为 JPEG，并暂存在内存中。
|
||
6. 提交前校验姓名、身份证号、短信验证码、证件图片和有效期。
|
||
7. 校验通过后先调用 `OSSUploadService.uploadRealNameImage` 上传证件图片。
|
||
8. 上传成功后把 OSS URL 写入 `RealNameAuthRequest.frontUrl/backUrl`。
|
||
9. 调用 `/api/yf-handset-app/photog/real-name/submit` 提交实名资料。
|
||
10. 提交成功后重新加载实名认证信息。
|
||
|
||
证件图片的原始 Data、压缩 Data 和上传进度只保存在内存中，不写入本地缓存。
|
||
|
||
## 设置和协议流程
|
||
|
||
1. 用户点击“系统设置”进入 `SettingsCenterView`。
|
||
2. 设置中心展示关于我们、系统版本、App 下载链接、用户协议和隐私政策。
|
||
3. App 下载点击后复制 `/h5/app/download` 链接到剪贴板。
|
||
4. 协议页使用 `AgreementView` 加载 `APIEnvironment.current.baseURL` 下的 H5 页面。
|
||
|
||
## 退出登录流程
|
||
|
||
1. 用户点击退出登录。
|
||
2. `ProfileView` 展示确认弹窗。
|
||
3. 用户确认后调用 `AuthSessionCoordinator.logout`。
|
||
4. 协调器清空正式 token、账号快照、账号上下文、路由栈和 Toast。
|
||
5. `AppSession` 切换为 `loggedOut`，根视图回到登录页。
|
||
6. 上次手机号和协议状态等非敏感偏好保留。
|
||
|
||
## 状态展示规则
|
||
|
||
- 昵称为空时展示“未设置昵称”。
|
||
- 真实姓名、手机号和账号状态为空时展示 `--`。
|
||
- 实名认证状态：
|
||
- `auditStatus == 2`：已实名认证。
|
||
- `auditStatus == 3`：审核不通过。
|
||
- 其他状态：审核中。
|
||
- 无实名认证信息时：点击去实名认证。
|
||
- 账号切换失败只展示 Toast，不清空登录态。
|
||
- 实名认证失败只影响实名认证页面，不影响登录态和账号上下文。
|