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

模块化重构实施计划

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: 将单体 App.tsx 拆分为模块化架构，支持多 BI 大类（资产管理、里程管理）通过全局导航切换。

Architecture: 新增 Shell 布局组件管理全局导航（Web 侧边栏 / 移动端底部导航），每个 BI 模块作为独立目录（modules/assets、modules/mileage），通过 hash 路由切换。现有资产管理逻辑原样迁入 modules/assets/，去掉其内部底部导航。

Tech Stack: React 19, TypeScript, Tailwind CSS 4, Lucide Icons, Vite

---

文件结构

操作	文件	职责
创建	src/components/SearchSelect.tsx	从 App.tsx 抽取的公共搜索下拉组件
创建	src/components/Shell.tsx	全局布局壳（侧边栏 + 底部导航 + 内容区）
移动	src/types.ts → src/modules/assets/types.ts	资产管理类型定义
移动	src/api.ts → src/modules/assets/api.ts	资产管理 API 客户端
创建	src/modules/assets/AssetsModule.tsx	资产管理主组件（现 App.tsx 逻辑迁入）
创建	src/modules/mileage/MileageModule.tsx	里程管理占位组件
重写	src/App.tsx	顶层壳：模块注册 + Shell 渲染

---

Task 1: 抽取 SearchSelect 公共组件

Files:

• Create: src/components/SearchSelect.tsx

• Step 1: 创建 SearchSelect 组件文件

从现有 src/App.tsx 第 38-106 行抽取 SearchSelect 组件，加上必要的 import：

import { useState, useEffect, useMemo, useRef } from 'react';
import { ChevronDown } from 'lucide-react';

export function SearchSelect({ value, onChange, options, placeholder, className }: {
  value: string;
  onChange: (v: string) => void;
  options: string[];
  placeholder: string;
  className?: string;
}) {
  const [open, setOpen] = useState(false);
  const [query, setQuery] = useState('');
  const ref = useRef<HTMLDivElement>(null);

  useEffect(() => {
    const handler = (e: MouseEvent) => {
      if (ref.current && !ref.current.contains(e.target as Node)) setOpen(false);
    };
    document.addEventListener('mousedown', handler);
    return () => document.removeEventListener('mousedown', handler);
  }, []);

  const filtered = useMemo(() => {
    if (!query) return options;
    const q = query.toLowerCase();
    return options.filter((o) => o.toLowerCase().includes(q));
  }, [options, query]);

  const displayValue = value || '';

  return (
    <div ref={ref} className="relative">
      <div
        className={`flex items-center bg-white border border-gray-200 rounded-lg shadow-sm cursor-pointer transition-all focus-within:ring-2 focus-within:ring-blue-500/20 focus-within:border-blue-500 ${className || 'text-xs py-1.5 px-2'}`}
        onClick={() => setOpen(!open)}
      >
        <input
          type="text"
          className="flex-1 outline-none bg-transparent min-w-0 text-inherit"
          placeholder={displayValue || placeholder}
          value={open ? query : displayValue}
          onChange={(e) => { setQuery(e.target.value); if (!open) setOpen(true); }}
          onFocus={() => { setOpen(true); setQuery(''); }}
        />
        <ChevronDown size={14} className={`text-gray-400 shrink-0 transition-transform ${open ? 'rotate-180' : ''}`} />
      </div>
      {open && (
        <div className="absolute z-50 left-0 right-0 mt-1 bg-white border border-gray-200 rounded-lg shadow-xl max-h-48 overflow-auto">
          <div
            className="px-2 py-1.5 text-xs text-gray-400 cursor-pointer hover:bg-gray-50"
            onClick={() => { onChange(''); setQuery(''); setOpen(false); }}
          >
            {placeholder}
          </div>
          {filtered.map((o) => (
            <div
              key={o}
              className={`px-2 py-1.5 text-xs cursor-pointer hover:bg-blue-50 transition-colors ${o === value ? 'bg-blue-50 text-blue-600 font-bold' : 'text-gray-700'}`}
              onClick={() => { onChange(o); setQuery(''); setOpen(false); }}
            >
              {o}
            </div>
          ))}
          {filtered.length === 0 && (
            <div className="px-2 py-3 text-xs text-gray-400 text-center">无匹配项</div>
          )}
        </div>
      )}
    </div>
  );
}

• Step 2: 验证 TypeScript 编译

Run: npx tsc --noEmit Expected: 无新增错误（SearchSelect 尚未被引用，不影响现有代码）

• Step 3: 提交

git add src/components/SearchSelect.tsx
git commit -m "refactor: 抽取 SearchSelect 为公共组件"

---

Task 2: 移动 types.ts 和 api.ts 到 assets 模块

Files:

• Move: src/types.ts → src/modules/assets/types.ts

• Move: src/api.ts → src/modules/assets/api.ts

• Modify: src/App.tsx (更新 import 路径)

• Modify: src/modules/assets/api.ts (更新 import 路径)

• Step 1: 创建目录并移动文件

mkdir -p src/modules/assets
git mv src/types.ts src/modules/assets/types.ts
git mv src/api.ts src/modules/assets/api.ts

• Step 2: 更新 api.ts 内部的 import 路径

src/modules/assets/api.ts 第 1-9 行，import 路径从 './types' 保持不变（同目录），无需修改。

• Step 3: 更新 App.tsx 的 import 路径

将 src/App.tsx 中的两处 import：

import type { SummaryData, TypeSummary, VehicleListItem, DeptGroup, RegionGroup, CustomerStats, RegionalInventoryStats } from './types';
import { fetchSummary, fetchByType, fetchVehicleList, fetchWeeklyDetail, fetchDeptStats, fetchRegionStats, fetchCustomerStats, fetchInventoryStats, fetchRegionChart } from './api';
import type { WeeklyDetailItem } from './api';

改为：

import type { SummaryData, TypeSummary, VehicleListItem, DeptGroup, RegionGroup, CustomerStats, RegionalInventoryStats } from './modules/assets/types';
import { fetchSummary, fetchByType, fetchVehicleList, fetchWeeklyDetail, fetchDeptStats, fetchRegionStats, fetchCustomerStats, fetchInventoryStats, fetchRegionChart } from './modules/assets/api';
import type { WeeklyDetailItem } from './modules/assets/api';

• Step 4: 验证 TypeScript 编译

Run: npx tsc --noEmit Expected: PASS，无错误

• Step 5: 验证开发服务器启动

Run: npm run dev:client (启动后 Ctrl+C 关闭) Expected: Vite 正常启动，无编译错误

• Step 6: 提交

git add -A
git commit -m "refactor: 移动 types.ts 和 api.ts 到 modules/assets/"

---

Task 3: 创建 AssetsModule 组件

Files:

• Create: src/modules/assets/AssetsModule.tsx
• Modify: src/App.tsx (后续 Task 5 重写时替换)

这一步将 src/App.tsx 中 export default function App() 及其上方的 TABS 常量迁移为 AssetsModule，并做以下调整：

• Step 1: 创建 AssetsModule.tsx

复制 src/App.tsx 的全部内容到 src/modules/assets/AssetsModule.tsx，然后做以下修改：

修改 1 — import 路径调整（文件顶部）：

将：

import type { SummaryData, TypeSummary, VehicleListItem, DeptGroup, RegionGroup, CustomerStats, RegionalInventoryStats } from './modules/assets/types';
import { fetchSummary, fetchByType, fetchVehicleList, fetchWeeklyDetail, fetchDeptStats, fetchRegionStats, fetchCustomerStats, fetchInventoryStats, fetchRegionChart } from './modules/assets/api';
import type { WeeklyDetailItem } from './modules/assets/api';

改为：

import type { SummaryData, TypeSummary, VehicleListItem, DeptGroup, RegionGroup, CustomerStats, RegionalInventoryStats } from './types';
import { fetchSummary, fetchByType, fetchVehicleList, fetchWeeklyDetail, fetchDeptStats, fetchRegionStats, fetchCustomerStats, fetchInventoryStats, fetchRegionChart } from './api';
import type { WeeklyDetailItem } from './api';

修改 2 — SearchSelect 改为外部导入：

删除文件中第 37-106 行的 SearchSelect 组件定义（// --- SearchSelect Component --- 到闭合的 }），替换为 import：

import { SearchSelect } from '../../components/SearchSelect';

修改 3 — 删除 import 中不再需要的图标：

从 lucide-react import 中移除 Users 和 Building2（这两个只被底部导航使用，删除底部导航后不再需要）。MapPin 保留（在内容区域第 2106 行仍被使用）。

修改 4 — 组件名改为 AssetsModule：

将：

export default function App() {

改为：

export default function AssetsModule() {

修改 5 — 删除底部导航栏（原第 2772-2802 行）：

删除从 {/* Footer / Navigation */} 到其对应 </div> 的整个代码块：

      {/* Footer / Navigation */}
      <div className="fixed bottom-0 left-0 right-0 bg-white border-t border-gray-100 p-2 flex justify-around items-center md:hidden z-40">
        ...全部删除...
      </div>

修改 6 — 去掉底部导航的 padding 留白：

将根 div 的 className：

min-h-screen bg-[#F8F9FB] text-gray-800 font-sans p-6 pb-20 md:pb-6 relative

改为：

min-h-screen bg-[#F8F9FB] text-gray-800 font-sans p-6 relative

即去掉 pb-20 md:pb-6，统一使用 p-6 的 padding。

• Step 2: 验证 TypeScript 编译

Run: npx tsc --noEmit Expected: PASS（AssetsModule 已自包含，App.tsx 仍引用旧路径但即将被重写）

• Step 3: 提交

git add src/modules/assets/AssetsModule.tsx
git commit -m "refactor: 创建 AssetsModule，迁移资产管理逻辑"

---

Task 4: 创建 Shell 布局组件

Files:

• Create: src/components/Shell.tsx

• Step 1: 创建 Shell.tsx

import { useState, useEffect, type ComponentType } from 'react';
import { Truck, Route } from 'lucide-react';

export interface ModuleConfig {
  id: string;
  label: string;
  icon: ComponentType<{ size?: number; className?: string }>;
  component: ComponentType;
}

function getHashModule(modules: ModuleConfig[]): string {
  const hash = window.location.hash.slice(1);
  return modules.some((m) => m.id === hash) ? hash : modules[0]?.id ?? '';
}

export function Shell({ modules }: { modules: ModuleConfig[] }) {
  const [activeModule, setActiveModule] = useState(() => getHashModule(modules));

  useEffect(() => {
    const onHashChange = () => setActiveModule(getHashModule(modules));
    window.addEventListener('hashchange', onHashChange);
    return () => window.removeEventListener('hashchange', onHashChange);
  }, [modules]);

  useEffect(() => {
    if (!window.location.hash) {
      window.location.hash = modules[0]?.id ?? '';
    }
  }, [modules]);

  const switchModule = (id: string) => {
    window.location.hash = id;
  };

  const ActiveComponent = modules.find((m) => m.id === activeModule)?.component ?? modules[0]?.component;

  return (
    <div className="flex min-h-screen">
      {/* Web 侧边栏 (md 及以上) */}
      <nav className="hidden md:flex flex-col items-center w-16 bg-white border-r border-gray-100 fixed top-0 left-0 h-full z-50 py-6 gap-2">
        {modules.map((m) => {
          const Icon = m.icon;
          const isActive = m.id === activeModule;
          return (
            <button
              key={m.id}
              onClick={() => switchModule(m.id)}
              className={`flex flex-col items-center justify-center w-14 h-14 rounded-xl transition-colors ${
                isActive
                  ? 'bg-blue-50 text-blue-600'
                  : 'text-gray-400 hover:text-gray-600 hover:bg-gray-50'
              }`}
            >
              <Icon size={22} />
              <span className="text-[10px] mt-1 leading-tight">{m.label}</span>
            </button>
          );
        })}
      </nav>

      {/* 内容区 */}
      <main className="flex-1 md:ml-16 pb-16 md:pb-0">
        {ActiveComponent && <ActiveComponent />}
      </main>

      {/* 移动端底部导航 (md 以下) */}
      <nav className="fixed bottom-0 left-0 right-0 bg-white border-t border-gray-100 p-2 flex justify-around items-center md:hidden z-50">
        {modules.map((m) => {
          const Icon = m.icon;
          const isActive = m.id === activeModule;
          return (
            <button
              key={m.id}
              onClick={() => switchModule(m.id)}
              className={`flex flex-col items-center ${isActive ? 'text-blue-600' : 'text-gray-400'}`}
            >
              <Icon size={20} />
              <span className="text-[10px] mt-1">{m.label}</span>
            </button>
          );
        })}
      </nav>
    </div>
  );
}

• Step 2: 验证 TypeScript 编译

Run: npx tsc --noEmit Expected: PASS（Shell 尚未被引用）

• Step 3: 提交

git add src/components/Shell.tsx
git commit -m "feat: 创建 Shell 布局组件（侧边栏 + 底部导航）"

---

Task 5: 创建里程管理占位组件

Files:

• Create: src/modules/mileage/MileageModule.tsx

• Step 1: 创建 MileageModule.tsx

import { Route } from 'lucide-react';

export default function MileageModule() {
  return (
    <div className="min-h-screen bg-[#F8F9FB] flex items-center justify-center p-6">
      <div className="text-center">
        <Route size={48} className="mx-auto text-gray-300 mb-4" />
        <h2 className="text-lg font-semibold text-gray-500">里程管理</h2>
        <p className="text-sm text-gray-400 mt-2">开发中...</p>
      </div>
    </div>
  );
}

• Step 2: 提交

mkdir -p src/modules/mileage
git add src/modules/mileage/MileageModule.tsx
git commit -m "feat: 创建里程管理占位组件"

---

Task 6: 重写 App.tsx 为顶层壳

Files:

• Rewrite: src/App.tsx

• Step 1: 重写 App.tsx

用以下内容完全替换 src/App.tsx：

import { Truck, Route } from 'lucide-react';
import { Shell, type ModuleConfig } from './components/Shell';
import AssetsModule from './modules/assets/AssetsModule';
import MileageModule from './modules/mileage/MileageModule';

const MODULES: ModuleConfig[] = [
  { id: 'assets', label: '资产管理', icon: Truck, component: AssetsModule },
  { id: 'mileage', label: '里程管理', icon: Route, component: MileageModule },
];

export default function App() {
  return <Shell modules={MODULES} />;
}

• Step 2: 验证 TypeScript 编译

Run: npx tsc --noEmit Expected: PASS，无错误

• Step 3: 验证 Vite 构建

Run: npm run build Expected: 构建成功，无错误

• Step 4: 本地验证功能

Run: npm run dev

手动检查：

1. 打开 http://localhost:3000 — 应看到左侧侧边栏（Web）或底部导航（移动端模拟）
2. 默认进入资产管理，所有 Tab（总览/按部门/按区域/按客户）正常
3. 数据正常加载显示
4. 点击"里程管理"切换到占位页面
5. 点击"资产管理"切回，数据和状态正常
6. URL hash 随切换变化（#assets / #mileage）
7. 原有移动端底部的资产内部导航已消失

• Step 5: 提交

git add src/App.tsx
git commit -m "refactor: 重写 App.tsx 为模块化顶层壳"

---

Task 7: 清理旧文件引用

Files:

• Delete: src/types.ts (如果 git mv 未处理干净)

• Delete: src/api.ts (如果 git mv 未处理干净)

• Verify: 无残留的旧 import 路径

• Step 1: 确认无残留文件

ls src/types.ts src/api.ts 2>/dev/null && echo "STALE FILES EXIST" || echo "CLEAN"

Expected: CLEAN（Task 2 已用 git mv 移动）

如果有残留，删除它们：

rm -f src/types.ts src/api.ts

• Step 2: 确认无旧 import 引用

grep -r "from '\./types'" src/ --include="*.tsx" --include="*.ts" | grep -v modules/assets/ | grep -v node_modules
grep -r "from '\./api'" src/ --include="*.tsx" --include="*.ts" | grep -v modules/assets/ | grep -v node_modules

Expected: 无输出（所有引用都已更新到新路径）

• Step 3: 最终构建验证

Run: npm run build Expected: 构建成功

• Step 4: 提交（如有清理）

git add -A
git status
# 如果有变更则提交：
git commit -m "chore: 清理残留文件和旧引用"