suixinkan_ios_uikit/suixinkan_ios/Features/Main/Main.md

Main 模块业务逻辑

模块职责

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

主界面由 MainTabBarController 承载，使用系统 UITabBarController 展示首页、订单、数据、我的四个 Tab。每个 Tab 内部包裹独立的 TabNavigationController，导航路径由 AppRouter 单独保存。

Tab 结构

当前 Tab 来自 AppTab：

• home：首页
• orders：订单
• statistics：数据
• profile：我的

各 Tab 根页面已接入真实业务页面：HomeViewController、OrdersViewController、StatisticsViewController、ProfileViewController。

导航流程

1. MainTabBarController 读取 AppServices.appRouter 作为选中 Tab 状态源。
2. 用户点击 TabBar 或通过 AppRouter.select 切换 Tab 时，两边状态保持同步。
3. 每个 Tab 由 TabNavigationController 创建独立 UINavigationController 栈。
4. Tab 内 push 子页面时，通过 AppRoute.hidesTabBarWhenPushed 控制是否隐藏系统 TabBar，默认隐藏。
5. 跨 Tab 跳转通过 AppRouter.select 或 AppRouter.selectOrders(entry:) 处理。

订单角标

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

扫码核销

系统 TabBar 不展示中间扫码按钮；订单页内部的扫码核销入口仍然可用。如需全局扫码入口，可通过首页或订单页进入。

后续迁移规则

迁移新页面时：

• 优先替换对应 Tab 的根 ViewController。
• 保持每个 Tab 自己的 TabNavigationController 导航栈。
• 跨 Tab 跳转通过 AppRouter.select 切换 Tab。
• 需要从首页或全局入口进入订单核销时，优先使用 AppRouter.selectOrders(entry:) 或 AppRouter.routeToOrderVerification(scannedCode:)。
• Tab 内跳转通过当前 Tab 的 RouterPath.navigate 或扩展后的 AppRoute 处理。
• 普通业务子页面默认隐藏 TabBar；只有确有产品需求时，才在 AppRoute 策略中单独放开。
• 真实业务页面接入后，应同步补充该模块文档和单元测试。