# 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 行 | 日期、领域计算、图表、表格和页面编排 |

目标结构遵循同一方向：

```text
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 的兼容处理
- 看似可合并但必须保持差异的流程

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

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

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

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