ln-bi/docs/refactoring/2026-08-13-codebase-refactor.md

LN-BI 渐进式重构方案

目标

本轮只调整代码结构，不改变业务功能。以下内容视为冻结契约：

• 页面文案、布局、交互和 URL 行为
• API 路径、请求参数、状态码和响应字段
• SQL、数据源优先级、权限与脱敏顺序
• 里程、资产、能源和调度的统计口径
• 缓存刷新频率与日报归档时间

当前结构

项目已经按业务模块组织，但部分文件仍承担了过多职责：

热点	规模	主要职责混合
modules/assets/AssetsModule.tsx	3240 行	请求、53 组状态、筛选、图表、弹窗、导出和四个视图
modules/mileage/MonitoringView.tsx	1611 行	查询参数、44 组状态、列表、全屏、导出和统计
server/routes/vehicles.ts	1426 行	SQL、缓存、权限、领域映射、聚合和 15 个接口
modules/mileage/DailyReportView.tsx	1192 行	日期、领域计算、图表、表格和页面编排

目标结构遵循同一方向：

route / page
  -> controller / hook       # 流程与状态
    -> service / model       # 业务规则与纯计算
      -> repository / api    # 数据访问

React 组件负责展示和交互编排；纯函数负责排序、筛选、分组和口径；服务端路由只解析请求并组织响应；数据库查询集中在 repository 层。

实施顺序

1. 建立回归门禁：类型检查、领域测试和生产构建必须同时通过。
2. 提取纯模型：先移动无副作用的日期、映射、筛选、排序和聚合逻辑，并补特征测试。
3. 拆分前端组件：日期选择器、表格、展开详情等独立，页面保留状态和组合。
4. 拆分后端边界：服务器应用创建与进程启动分离；大型路由按 model、service、repository、routes 拆分。
5. 清理重复与废弃代码：只有在引用和行为测试都证明无影响后执行。

每一批只处理一个边界，不把现存 Bug 修复、新功能或视觉调整混入重构提交。

模块迭代路线

批次	模块	主要边界	风险控制
第一轮	应用入口、服务启动、日报、资产模型、监控查询、车辆模型	路由装配、启动副作用、纯计算	特征测试锁定路由、日期、口径和请求参数
第二轮	资产页、里程监控、车辆接口、统计报表	展示组件、数据访问、弹层和图表	保持 DOM、SQL、缓存覆盖和请求时机不变
第三轮	氢能展示、能源查询路由	图表展示、日期模型、数据库查询	固定金额/重量单位、客户范围和日期边界
第四轮	智能调度	筛选模型、建议详情、通知历史	写操作与只读派生分开，通知接口单独回归
第五轮	OneOS 接入、里程缓存	外部 API、协议降级、缓存与合并	使用响应夹具验证降级顺序、TTL 和数据源优先级

高风险模块不会与普通页面组件放在同一批：能源路由依赖两套数据库，调度包含通知写入，OneOS 层还包含协议兼容、超时和缓存淘汰。拆分这些模块前必须先建立可重复的输入夹具。

当前进度

截至 2026-08-13，前五轮可独立验证的边界已经完成：

• 应用路由配置与服务器启动副作用已经从入口文件分离。
• 资产、里程监控、每日汇报、统计报表和智能调度已改为“页面协调层 + 展示组件 + 纯模型”。
• 车辆接口已改为“路由 + repository + model”，原 SQL、缓存范围和接口顺序由特征测试锁定。
• 能源接口已按氢能总览、氢能每日、电能总览和电能每日拆分，入口只保留权限守卫与装配。
• 氢能与电能每日页共用自然日范围模型和筛选控件；金额、重量、环比及 30% 波动边界已有测试。
• 反馈入口和电能导入页已收敛为“副作用协调层 + 无状态展示组件”；上传、筛选和请求时机仍由主组件负责。
• OneOS 响应归一化、连续日期分组和请求键已提取为纯模型；协议别名、去重和区间边界由固定样例锁定。
• 里程缓存中的车辆合并、筛选项、考核映射和自然日工具已与刷新流程分离；数据源分类和累计里程空值规则保持不变。
• 调度通知的数据库行映射、请求校验和更新字段生成已有契约测试；数据库写入顺序和单车有效干预约束仍留在路由层。
• 车辆与加氢热力图已把参数解析、距离计算、网格/排名和序列化提取为纯模型；原 SQL 及参数顺序由契约测试锁定。
• CI 已把类型检查、全量测试和生产构建设为同一发布门禁。

下一批继续只处理能够独立回归的边界：

1. 继续缩小 AssetsModule.tsx 的状态协调职责，但不改请求、筛选、导出和弹窗时序。
2. 拆分车辆详情、调度建议详情和通知历史中的纯展示区块，主组件继续持有写操作。
3. 为电能导入服务端路由补 SQL 与去重契约后，再拆解析、repository 和路由装配。
4. OneOS 网络重试、协议降级和缓存 TTL 暂不移动；只有在可注入请求层覆盖 400 降级和重试后再处理。

注释约定

注释解释“为什么”，不复述语句本身。优先说明：

• 统计边界和历史口径
• 时区、日期范围和特殊状态映射
• 外部 API 的兼容处理
• 看似可合并但必须保持差异的流程

命名和类型能够表达清楚的代码不额外添加注释。

已识别但不在本轮修复的问题

• 统计页实时车辆与历史日期车辆共用同一个缓存槽，存在状态覆盖风险。
• 监控页不同入口的请求参数目前不完全一致。
• 数据库连接配置与部署凭据需要独立安全治理。

这些问题需要单独建缺陷、明确期望行为后再修复，避免借重构改变线上结果。