汉秋
a1c031c9b7
Add CYLTabBarController with a global scan entry, promote MainTabBarController to the window root after login, replace RouterPath-based navigation with AppNavigator, and fix Profile diffable cell reconfiguration crashes. Co-authored-by: Cursor <cursoragent@cursor.com>
53 lines
2.6 KiB
Markdown
53 lines
2.6 KiB
Markdown
# Main 模块业务逻辑
|
||
|
||
## 模块职责
|
||
|
||
Main 模块负责登录后的主界面 Tab 容器。
|
||
|
||
主界面由 `MainTabBarController` 承载，使用 **CYLTabBarController** 展示首页、订单、数据、我的四个 Tab，并在中间提供扫码核销按钮。每个 Tab 内部包裹独立的 `TabNavigationController`，页面路径以 UIKit 导航栈为唯一事实源。
|
||
|
||
## Tab 结构
|
||
|
||
当前 Tab 来自 `AppTab`：
|
||
- `home`：首页
|
||
- `orders`：订单
|
||
- `statistics`：数据
|
||
- `profile`：我的
|
||
|
||
各 Tab 根页面已接入真实业务页面：`HomeViewController`、`OrdersViewController`、`StatisticsViewController`、`ProfileViewController`。
|
||
|
||
## 导航流程
|
||
|
||
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 中间通过 `MainScanPlusButton`（CYLTabBarController PlusButton）展示全局扫码入口，点击后全屏打开 `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` 策略中单独放开。
|
||
- 真实业务页面接入后，应同步补充该模块文档和单元测试。
|