suixinkan_ios_new/suixinkan/Features/Home/Home.md

Home 模块业务逻辑

模块职责

Home 模块负责登录后的首页工作台，包括当前景区展示、工作状态、位置上报入口、快捷操作、常用应用和全部功能入口。

首页菜单来自 PermissionContext 中的角色权限。当前模块只同步首页壳和入口路由，入口背后的业务子模块后续逐个迁移。

菜单生成

HomeViewModel 从当前角色的权限树递归提取菜单：

• 当前 role_code 存在但找不到时清空菜单。
• 当前 role_code 为空时使用第一个角色。
• URI 按旧工程顺序排序。
• 同义 URI 按 HomeMenuRouter.menuAliasKey 去重。

角色 UI 判断使用 PermissionContext.currentAppRole（AppRoleCode 枚举），例如店长 isStoreAdmin、首页隐藏工作状态 homeMinimalTopRoles。

常用应用

HomeCommonMenuStore 使用 UserDefaults 按账号和角色保存常用应用 URI：

• 当前版本使用账号 + 角色作用域保存常用应用 URI，避免不同业务账号的同一角色互相覆盖；旧版角色 key 会在首次读取时迁移。
• 首次无配置时，按 Android 规则从当前角色顶层权限 URI 生成默认值：权限多于 4 个取前 4 个，否则全部使用。
• 首页常用应用按 Android Constants.menuList 白名单过滤；iOS 已接入但 Android 首页未登记的 URI 不进入首页常用应用。
• 读取时按当前角色权限过滤不可用 URI。
• 添加和移除时按同义 URI 去重。
• 不同角色的常用应用互不影响。
• 升级时会从旧版 role.{roleId} key 一次性迁移到 role.{roleCode}。

路由规则

HomeMenuRouter 将权限 URI 分为四类：

• tab：切换到订单或数据 Tab。
• destination：进入已接入的本地页面，如个人信息、景区选择、权限申请、全部功能。
• unsupported：已知 iOS 不支持的入口，进入占位说明。
• placeholder：未知或未迁移入口，记录诊断并进入占位说明。

HomeView 不创建自己的 NavigationStack，而是使用 Main Tab 注入的 RouterPath 进行页面跳转。

HomeMoreFunctionsView 使用系统导航栏展示标题和返回，以支持左边缘滑动返回。

位置上报

首页工作状态区域由 HomeLocationViewModel 驱动，与 LocationReport 详情页共享同一实例（在 RootView 注入）。

• 在线/离线切换、立即上报、2 小时倒计时和提前提醒均走真实 API。
• 「位置上报超时」弹窗仅在本地在线且倒计时进入提前提醒窗口时弹出；离线状态不弹窗。
• 本地状态通过 LocationStateStore 持久化在线标志、过期时间戳、上次上报时间和提醒分钟数。
• 首页大按钮直接触发 GPS 上报；菜单 location_report 仍进入详情页。
• 非 homeMinimalTopRoles 角色才展示工作状态卡片。

后续迁移

目前 payment_collection、payment_qr、payment_code 已由 Features/Payment 的真实收款页面接管，wallet 已由 Features/Wallet 的真实钱包页面接管，cooperation_order 已由 Features/CooperationOrder 接管，scenicselection、permission_apply、permission_apply_status、scenicapplication 已由 Features/ScenicPermission 接管，task_management、task_management_editor、task_create 已由 Features/Tasks 接管，cloud_management、cloud_storage_transit、asset_management、material_upload、album_list、album_trailer、sample_management、sample_upload 已由 Features/Assets 接管，checkin_points 已由 Features/PunchPoint 接管，location_report 和 location_report_history 已由 Features/LocationReport 接管，pm、project_edit 已由 Features/Projects 的摄影师项目管理接管，pm_manager 已由店铺项目管理接管，schedule_management 已由 Features/Schedule 接管，registration_invitation、photographer_invite、invite_record 已由 Features/Invite 接管，deposit_order_detail、deposit_order、deposit_order_shooting_info 已由 Features/Orders 的押金订单页接管，withdrawal_audit 已由 Features/WithdrawalAudit 接管，scenic_settlement 和 scenic_settlement_review 已由 Features/ScenicSettlement 接管，message_center 已由 Features/MessageCenter 接管，/scenic-queue 和 queue_management 已由 Features/QueueManagement 接管，live_stream_management 和 live_album 已由 Features/Live 接管，operating-area 已由 Features/OperatingArea 接管，pilot_cert 已由 Features/PilotCertification 接管。

后续迁移具体首页子模块时，应先在 HomeRoute 增加目标页面，再更新 HomeMenuRouter.resolve 对应 URI 的映射，并同步补充单元测试。