# Home 模块业务逻辑

Android 工程对应文档：[`zhiflyfollow/docs/home/Home.md`](../../../zhiflyfollow/docs/home/Home.md)

## 模块职责

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

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

## 菜单生成

`HomeViewModel` 从当前角色的权限树递归提取菜单：
- 当前 `role_code` 存在但找不到时清空菜单。
- 当前 `role_code` 为空时使用第一个角色。
- URI 按旧工程顺序排序。
- 同义 URI 按 `HomeMenuRouter.menuAliasKey` 去重。

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

## 常用应用

`HomeCommonMenuStore` 使用 UserDefaults 按账号和角色保存常用应用 URI，算法与 Android `AllFunctionsViewModel` 对齐：
- 当前版本使用账号 + 角色作用域保存常用应用 URI，避免不同业务账号的同一角色互相覆盖；旧版角色 key 会在首次读取时迁移。
- 可用菜单范围：仅**顶层权限** ∩ Android `Constants.menuList` 白名单（`androidHomeMenuURIs`），不使用扁平化子权限。
- 首次无配置时：先取顶层权限前 4 个 URI（原始 API 顺序），再与 menuList 白名单求交后落库。
- 已有 saved 配置时：精确 URI 匹配过滤；全部失效时返回空，**不回退**默认生成。
- 添加/移除常用应用使用精确 URI 匹配（与 Android 一致）。
- 不同角色的常用应用互不影响。
- 升级时会从旧版 `role.{roleId}` key 一次性迁移到 `role.{roleCode}`。
- Debug 构建下可通过 `HomeCommonMenu` 日志 tag 与 Android 端逐步对比（`context` / `rawTopLevel` / `availableFunctions` / `savedCommon` / `defaultCommon` / `finalCommon` / `displayItems`）。

## 路由规则

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

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

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

## 全部功能

「全部功能」页的数据、筛选、展示逻辑见独立文档 [`AllFunctions.md`](AllFunctions.md)。

## 位置上报

首页工作状态区域由 `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 的映射，并同步补充单元测试。

`report_photographer` 已由 `Features/WildPhotographerReport` 接管。

`promotion_page`（宣传页）已从 iOS 移除；该 URI 列入 `HomeCommonMenuStore.hiddenHomeMenuURIs`，首页与全部功能页均不展示。