suixinkan_ios_new/suixinkan/Features/Main/Main.md

Main 模块业务逻辑

模块职责

Main 模块负责登录后的主界面 Tab 容器，以及当前尚未迁移页面的占位入口。

主界面由 MainTabsView 承载：

• 根据 MainTabBarConfiguration.activeStyle 选择自定义 TabBar 或系统 TabView。
• 默认使用自定义 TabBar；如需切回系统实现，将配置改为 .system。
• 自定义和系统两套外壳都展示首页、订单、数据、我的四个 Tab。
• 每个 Tab 内部都包裹独立的 NavigationStack，并通过 TabNavigationStackHost 复用同一套导航构建逻辑。
• 每个 Tab 的导航路径由 AppRouter 单独保存。

Tab 结构

当前 Tab 来自 AppTab：

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

HomeRootView 已接入真实的 HomeView，OrdersRootView 已接入真实的 OrdersView，StatisticsRootView 已接入真实的 StatisticsView，ProfileRootView 已接入真实的 ProfileView。

导航流程

1. MainTabsView 从 Environment 读取 AppRouter。
2. MainTabsView 根据 MainTabBarConfiguration.activeStyle 选择 CustomMainTabsView 或 SystemMainTabsView。
3. 两套外壳都使用 appRouter.selectedTab 作为选中状态。
4. 每个 Tab 通过 TabNavigationStackHost 创建自己的 NavigationStack(path:)。
5. 路径绑定来自 appRouter.binding(for:)。
6. Tab 内页面需要进入尚未迁移的子页面时，通过当前 Tab 注入的 RouterPath push 一个 AppRoute.placeholder。
7. navigationDestination 根据 AppRoute 展示详情页。
8. 子页面展示时读取 AppRoute.hidesTabBarWhenPushed，默认隐藏底部 TabBar。

自定义 TabBar

自定义 TabBar 由 CustomMainTabsView 和 CustomMainTabBar 组成：

• CustomMainTabsView 负责保留已访问 Tab 页面、刷新订单角标、展示扫码页。
• CustomTabNavigationStackHost 会把 CustomMainTabBar 拼在每个 Tab 的根页面内容下方。
• CustomMainTabBar 只负责展示 UI，不直接读取账号、订单 API 或业务上下文。
• MainTabBadgeViewModel 通过 OrdersAPI.writeOffList 获取待核销数量，失败时静默清空角标。
• 中间扫码按钮使用订单模块已有的 OrderScannerPage。
• 扫码成功后调用 AppRouter.routeToOrderVerification(scannedCode:)，订单页再通过 consumePendingOrderScanCode() 一次性消费结果。
• 自定义 TabBar 只属于 Tab 根页面内容；当前 Tab 的导航栈 push 到二级页面后，目标页面不包含 TabBar，也不会保留底部占位高度。
• 承载根页面和 CustomMainTabBar 的容器需要忽略键盘底部安全区，避免订单搜索框等输入控件唤起键盘时把自定义 TabBar 顶起。

系统 TabView 外壳由 SystemMainTabsView 保留。系统模式不显示中间扫码按钮，但订单页内部的扫码核销入口仍然可用。

后续迁移规则

迁移新页面时：

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