# Main 模块业务逻辑

## 模块职责

Main 模块负责登录后的主界面 Tab 容器。

主界面由 `MainTabBarController` 承载，使用系统 `UITabBarController` 展示首页、订单、扫码、数据、我的五个底部入口。首页、订单、数据、我的四个业务 Tab 内部包裹独立的 `TabNavigationController`，页面路径以 UIKit 导航栈为唯一事实源；中间扫码入口只触发全局扫码，不切换选中页面。

## Tab 结构

当前 Tab 来自 `AppTab`：
- `home`：首页
- `orders`：订单
- `statistics`：数据
- `profile`：我的

各 Tab 根页面已接入真实业务页面：`HomeViewController`、`OrdersViewController`、`StatisticsViewController`、`ProfileViewController`。
系统 TabBar 中间额外插入扫码槽位，显示 `MainScanTabItem` 构建的扫码 item。

## 导航流程

1. `MainTabBarController` 在登录后注册为 `AppNavigator` 的导航宿主。
2. 用户点击 TabBar 只改变 UIKit 选中态，并保留各 Tab 原有导航栈。
3. 每个 Tab 由 `TabNavigationController` 创建独立 `UINavigationController` 栈。
4. Tab 内 push 子页面时，通过 `AppRoute.hidesTabBarWhenPushed` 控制是否隐藏系统 TabBar，默认隐藏。
5. 跨 Tab、推送通知、UI Test 直达和全局扫码统一通过 `AppNavigator` 执行。

## 订单角标

- `MainTabBadgeViewModel` 通过 `OrdersAPI.writeOffList` 获取待核销数量，失败时静默清空角标。
- 角标展示在订单 Tab 的 `tabBarItem.badgeValue` 上。
- 账号景区或门店变化、切换到订单 Tab 时会刷新角标。

## 扫码核销

TabBar 中间通过 `MainScanTabItem` 展示全局扫码入口，`MainTabBarController` 在 `shouldSelect` 中拦截点击并全屏打开 `OrderCodeScannerViewController`，因此关闭扫码页后仍显示点击前的页面：

1. 扫码成功 → `AppNavigator.openOrdersEntry(.verificationOrders, scannedCode:)` 切换至订单核销入口并传入扫码结果。
2. `OrdersViewController` 本地保存并消费扫码结果后进入确认核销流程。
3. 扫码失败 → 通过 `ToastCenter` 提示错误。

订单页内部的扫码核销入口仍然可用，与 TabBar 中间按钮为双入口。

## 后续迁移规则

迁移新页面时：
- 优先替换对应 Tab 的根 ViewController。
- 保持每个 Tab 自己的 `TabNavigationController` 导航栈。
- 跨 Tab 跳转通过 `AppNavigator.selectTab` 或对应业务入口方法执行。
- 需要从首页或全局入口进入订单核销时，优先使用 `AppNavigator.openOrdersEntry(_:scannedCode:)`。
- Tab 内跳转通过 `AppNavigator.push(_:from:)` 或扩展后的 `AppRoute` 处理。
- 普通业务子页面默认隐藏 TabBar；只有确有产品需求时，才在 `AppRoute` 策略中单独放开。
- 真实业务页面接入后，应同步补充该模块文档和单元测试。