初始提交

suixinkan/Features/Account/Account.md

@@ -0,0 +1,36 @@
+# Account 模块业务逻辑
+
+## 模块职责
+
+Account 模块负责同步账号进入业务页前必须具备的上下文数据，包括角色权限、景区、门店和当前景区下的景点/打卡点。
+
+该模块只做读取和上下文装配，不负责登录 token 存储，也不负责页面导航。
+
+## 数据边界
+
+- 角色权限：由 `/api/yf-handset-app/role-permission` 返回，写入 `PermissionContext`。
+- 景区列表：由 `/api/yf-handset-app/photog/scenic/list-all` 返回，用于账号业务作用域。
+- 门店列表：由 `/api/app/store/all` 返回，并通过 `scenic_id` 关联景区。
+- 景点/打卡点：由 `/api/yf-handset-app/photog/scenic-spot/list-all` 按当前景区懒加载。
+
+## 加载流程
+
+登录成功或冷启动恢复时，`AccountContextLoader` 会并行请求用户资料和角色权限。权限成功后继续读取景区和门店：
+
+1. 用户资料刷新 `AccountContext.profile`。
+2. 角色权限刷新 `PermissionContext`，并计算当前角色的权限 URI 集合。
+3. 景区列表失败时，从角色权限里的景区数据去重兜底。
+4. 门店列表失败时不阻断登录，只写入空门店列表。
+5. 当前景区确定后，`ScenicSpotContext` 再按景区 ID 拉取景点/打卡点。
+
+## 切换规则
+
+- 切换角色时，当前景区优先保留在新角色可访问景区中，否则选择新角色第一个景区。
+- 切换景区时，当前门店优先保留同景区门店，否则选择该景区第一个门店。
+- 切换景区后，景点/打卡点列表会重新加载。
+
+## 缓存规则
+
+`AccountSnapshotStore` 只保存非敏感上下文快照，包括当前角色 ID、当前景区 ID、当前门店 ID 和基础账号展示信息。
+
+景点/打卡点列表只保存在内存中，不长期落盘。后续业务需要离线缓存时，需要按账号类型、业务账号 ID 和景区 ID 做隔离。