第 8 / 9 篇
整理于 · 7 分钟
维护一段时间后，为什么重写前端
重写界面时怎样核对既有业务与兼容范围
以九月重写为主，回看五月清理；六月、七月的连续记录并不完整。
贯穿项目的约定 本篇涉及 2 条
当一个项目从“快速验证业务可行性”进入“需要长期稳定维护”的阶段，前期的代码债务往往会集中爆发。SCORE 在经历了几轮功能迭代与学校现场落地后，前端积累了大量由原生 DOM 操作、分散的业务规则与冗长的状态脚本交织而成的技术包袱。
到 9 月，项目转向 React 19 与 TypeScript。重写需要同时解决代码组织和功能迁移：旧页面中藏在抽屉、弹层和次级菜单里的能力，都要先核对去向，再判断新版是否覆盖。
1. 重构前的治理：先清理隐患，再启动大拆分
在启动大型重构之前，盲目推倒重来往往会导致旧系统中宝贵的边界修复丢失。系统在 5 月先行开展了代码健康度审查，重点排查出两类高危缺陷：
- 同作用域同名函数的隐式覆盖：导出服务中存在同名函数的重复定义，后定义覆盖前定义，维护者可能修改到已失效的实现。首轮治理退役了 16 个被覆盖的旧函数，保留实际生效行为与对外入口。
- 纯计算规则与存储耦合：原成绩仓储模块同时承担了 SQL/文件持久化、撤销快照以及纯业务计算。治理将教师导入冲突判定、考试类型推导等纯函数抽离为独立规则模块，为后续的架构重组理清了职责边界。
六月至七月的提交记录还涉及班级总体分布导出、成绩权限与对比展示、分数线和均分口径。这一段缺少同等完整的需求与验收资料，只能保留已确认的维护主题，不据此扩写使用成效。
2. 9 月重构的核心诉求与架构选型
进入 9 月，面对日益复杂的教研交互，系统确立了新一代前端技术栈：
- 核心框架：React 19 + TypeScript + Vite，用于组件组织、类型检查与开发构建；
- 状态管理：使用 TanStack Query 管理服务端查询与缓存，使用 Zustand 管理客户端的部分共享状态；
- 可视化与界面：深度定制 ECharts 图表，设计翠绿强调色、细边框与高密度信息排版，支持原生深浅色主题切换；
- 业务模块化目录：将导入、成绩管理、成绩详情、多维分析、学情追踪与系统维护分别划入自治的业务子域，使视图、类型定义、专属 API 与工具函数聚合在一起。
3. 功能盘点：给细节能力安排去向
只按顶层导航核对页面，会遗漏抽屉、弹层和次级菜单里的功能。因此迁移清单除了登录与 12 个一级视图，还继续向下列出页面内部的操作。
盘点覆盖了以下几类能力：
- 成绩详情：粘性表头（Sticky Header）、扩展列开关（Z 分数/校排/联考排）、分线达成矩阵、临界名单非对称浮动、单科更正抽屉、操作日志与多 Sheet 导出；
- 学情追踪：批量考试多选、无记录名单穿透、百分位状态机（待观察/高位稳定/起伏/进阶/后移）、命中断言证据弹窗与个人雷达报告；
- 数据导入：多 Sheet 独立选择/跳过、字段映射、学生匹配冲突审查池、更正差异预览对比；
- 系统基础：登录回跳、会话复用、权限过滤、移动端折叠侧栏与路由深链接。
清单也包含明确的取舍：主题切换是新版新增能力；七条没有前端调用的后端端点继续兼容，不额外补页面；旧版未接线的 SVG 导出不迁移。功能覆盖以这些已确认的边界为准。
4. 真实业务的保护：从代码历史中挖掘遗珠
在功能盘点过程中，曾出现过一个典型的决策插曲：一份早期的迁移报告认为“分线达成”统计模块在 Git 主干中缺少部分提交历史，建议为了赶进度暂不迁移该模块。
核对本地工作区并经用户确认后，这部分实现被认定为需要保留的实际成果，包括分线达成表格与 Excel 导出。
后续决策单记录了表格与导出的补齐。这次调整说明，迁移基线需要同时核对提交历史、当前工作区和用户确认；未提交的实现也可能承担实际业务，不能仅凭提交记录缺失就裁剪。
5. 双轨入口与旧版退役分开处理
现有代码与任务记录支持的是双轨入口和构建流程的形成：
- 主入口服务新构建：根路径
/指向 React SPA 构建产物，并接入构建启动流程和深链接回退。 - 保留历史通道
/v3：旧版继续可作为兼容入口。 - 分步退役：旧资源预检快照中有 71 个测试文件直接依赖旧前端源码，因此入口调整与文件删除分开。先核对新版与构建，再解耦实际依赖；旧文件尚未物理删除。
九月补记确认了入口、构建和面板接线的推进，但总验收仍需汇总核对。这些材料没有证明学校生产环境已经切换到新版，也不能据此声称切换过程无中断。
这次重写把两类工作分开记录：功能迁移说明哪些业务需要保留、哪些经确认不迁移；入口与退役记录说明新版怎样接入、旧资源还有哪些依赖。代码形成、限定验证和生产上线各有证据，不能互相替代。