ln-bi/docs/superpowers/specs/2026-04-01-modular-refactor-design.md

模块化重构设计：支持多 BI 大类

背景

当前项目是一个单体 BI 看板（资产管理），所有前端逻辑集中在 App.tsx（~2800 行）。后续需要扩展"里程管理"等新 BI 大类。本次重构目标是建立模块化架构，让新模块可以低成本接入，同时不影响现有功能。

目标

• 建立模块级拆分架构，每个 BI 大类作为独立模块
• 新增全局导航：Web 端侧边栏、移动端底部导航栏
• 去掉现有资产管理内部的移动端底部导航（与顶部 Tab 重复）
• 里程管理模块仅做占位，具体功能后续实现
• 后端不动

重构后目录结构

src/
├── App.tsx                        # 顶层：Shell + hash 路由分发
├── main.tsx                       # 入口（不变）
├── index.css                      # 全局样式（不变）
│
├── components/                    # 公共组件
│   ├── Shell.tsx                  # 布局壳（侧边栏 + 底部导航 + 内容区）
│   └── SearchSelect.tsx           # 搜索下拉组件（从 App.tsx 抽出）
│
├── modules/
│   ├── assets/                    # 资产管理模块
│   │   ├── AssetsModule.tsx       # 现有 App.tsx 全部逻辑迁入
│   │   ├── api.ts                 # 现有 src/api.ts 迁入
│   │   └── types.ts              # 现有 src/types.ts 迁入
│   │
│   └── mileage/                   # 里程管理模块（占位）
│       └── MileageModule.tsx      # 占位组件
│
└── server/                        # 后端完全不动

Shell 布局设计

模块注册

const MODULES = [
  { id: 'assets',  label: '资产管理', icon: Truck,  component: AssetsModule },
  { id: 'mileage', label: '里程管理', icon: Route,  component: MileageModule },
];
// 未来新模块只需往数组加一项

Web 端（md 及以上）— 左侧侧边栏

• 侧边栏窄版（约 64px），图标 + 文字纵向排列
• 固定定位，内容区有左 margin
• 选中项高亮

移动端（md 以下）— 底部导航栏

• 底部固定导航栏，切换 BI 大类（资产管理 / 里程管理）
• 替换掉现有资产管理内部的底部导航

路由机制

• window.location.hash：#assets、#mileage
• 默认无 hash 时进入 #assets
• Shell 监听 hashchange 事件切换模块
• 不引入任何路由库

AssetsModule 迁移策略

改动

1. 去掉底部导航栏（原 App.tsx 2773-2802 行）
2. 去掉底部导航的 padding 留白
3. SearchSelect 改为从 components/SearchSelect.tsx 导入
4. 组件名从 App 改为 AssetsModule

不改

• 所有内部状态管理、Tab 切换、数据加载、图表、弹窗逻辑
• 顶部 Tab 栏（总览/按部门/按区域/按客户）
• API 调用逻辑（仅调整 import 路径）

文件迁移映射

原文件	目标	操作
src/App.tsx	src/modules/assets/AssetsModule.tsx	迁移内容，去掉底部导航和 SearchSelect
src/api.ts	src/modules/assets/api.ts	直接移动
src/types.ts	src/modules/assets/types.ts	直接移动
App.tsx 中 SearchSelect	src/components/SearchSelect.tsx	抽取为独立文件

新增文件

文件	内容
src/App.tsx（重写）	模块注册 + Shell 渲染
src/components/Shell.tsx	全局布局（侧边栏 / 底部导航 + 内容区）
src/modules/mileage/MileageModule.tsx	占位页面

不在范围内

• AssetsModule 内部进一步拆分（保持现有结构）
• 里程管理具体功能实现
• 后端改动
• 新增依赖