suixinkan_ios_uikit/suixinkan_ios/Features/Main/Main.md

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 策略中单独放开。
• 真实业务页面接入后，应同步补充该模块文档和单元测试。