第 5 / 9 篇
整理于 · 7 分钟
从本机运行到学校环境交付
本地原型如何克服现场服务器约束并实现单机交付
从三月模块化、四月现场方案写到六月交接，末尾补充九月健康检查修订。
贯穿项目的约定 本篇涉及 2 条
SCORE 起步时依靠本地文件保存数据，随后逐步补上正式账号体系、MySQL 持久化和学校服务器部署。这个过程要解决的具体问题是：本机能够完成导入、查询和导出之后，怎样让学校环境中的服务可启动、数据可迁移、故障可定位。
这一演进过程记录了系统在工程结构、存储适配以及现场部署策略上的真实权衡。
1. 跑通第一阶段的业务闭环
在项目初期，核心目标是尽快跑通端到端的业务主链路：从用户上传 Excel 文件开始，经过结构解析、数据校验、学生身份匹配、落库存储，再到前端发起基础统计查询、展示学情分析并最终导出报表。
为了降低早期各模块间的耦合度，系统设计了一套统一的中间数据格式（Unified Intermediate Representation）。无论是哪种格式的 Excel，解析模块首先将其归一化为标准的中间数据包，后续的校验器、匹配器、预览视图和持久化层都直接消费这份中间结构。这种设计使得在早期数据库表结构尚未完全定型时，前端界面与统计分析逻辑不必随着底层存储的每次试验而频繁返工。
第一阶段留下了完成回写和测试手册，检查范围包括多 Sheet、缺列、分数异常、重名冲突、权限拦截和报表导出。现有资料没有逐条执行日志，因此只能确认当时形成了业务闭环和检查方案，不能将手册中的全部场景都算作已通过。
2. 三月的模块化重构：原生 ES Modules 方案
随着页面功能扩充，早期单体脚本中混合了 HTTP 请求、会话维护、业务计算、DOM 渲染和事件监听代码。3 月下旬的重构开始按这些职责拆分模块。
此时，系统进行了一次关键的架构拆分。需要明确的是，三月的这次重构并非引入现代前端框架（如 React），而是基于原生 ES Modules 规范进行的模块化治理：
- 请求与会话层独立：将所有的 API 交互和身份认证状态提取为专有模块；
- 业务规则与视图解耦：将成绩计算、缺考过滤、排名算法等纯函数与 DOM 渲染逻辑分离，便于独立测试；
- 保留既有技术栈：沿用原有页面与渲染方式，先调整代码组织，不在这一轮引入 React。
这次拆分不仅理清了模块依赖，也为后来九月更彻底的前端工程重构奠定了模块边界基础。
3. 从单机原型走向正式交付
为了让系统能够交付给学校使用，SCORE 启动了单机正式化改造：
两条分支都从围栏里的统一存储接口出发，不是从整个应用服务出发；业务逻辑层与两个存储实现之间没有直接通路，它只调用接口。
- 统一存储适配接口：在业务逻辑与底层持久化之间提供统一接口，向下连接文件适配器和 MySQL 适配器。文件模式方便开发与单机测试；切换 MySQL 则需要准备数据库、连接配置和迁移数据。
- 独立会话持久化与数据迁移：补齐账号鉴权、密码策略与数据库初始化脚本，并准备文件历史数据迁入 MySQL 的工具、核验与回退流程。数量和关联核对是迁移检查的一部分，不能仅凭这些检查就认定所有业务行为一致。
4. 学校现场部署的真实取舍
4 月的部署规划曾考虑将应用与数据库分开放置。4 月 17 日的现场记录确认主机已有 Node.js 和 Nginx，但缺少符合项目要求的 MySQL 环境，后续方案转为同机部署应用与数据库。
执行顺序也随之明确：
- 准备 MySQL、初始化与迁移数据，先让应用在本机端口启动并检查连通；
- 配置 systemd 管理服务进程；
- 再接入既有 Nginx 反向代理，检查外部访问入口。
先应用、后代理的顺序有助于区分应用或数据库问题与代理配置问题。4 月 17 日材料混合了已完成的主机检查和待执行方案，没有完整的当日验收回写；部署是否成功，需要继续看后续记录。
5. 运维认识的演进与交付证据
部署资料逐步区分了检查方法与实际运行证据。
5.1 进程存活不等于数据库健康
部署检查需要分别回答三个问题：进程是否启动、HTTP 入口是否可访问、数据库是否可用。登录页能打开，只能说明相应静态页面或入口可达，不能据此判断成绩查询链路正常。
历史资料因此要求区分进程与数据库健康。到九月的可靠性修复，才进一步将数据库初始化与普通探测分离：初始化显式执行，健康检查采用只读查询并对输出脱敏。不能把这项九月修复提前写成四月已经完成的能力。
5.2 真实的同步与交接记录
6 月 1 日的同步记录提供了具体证据：153 个运行文件哈希一致、服务运行、本机与外部 HTTP 健康检查通过。过程中还修复了 Nginx 仍指向旧端口引起的 502，以及备份路径清单中的换行符引起的脚本失败。
6 月 4 日交接材料继续记录服务可访问，并说明入口、备份与排查方式。这些证据支持六月相应时点的同步和交接状态，不能证明服务此后持续稳定运行，也不能代替九月新版本的上线验收。
这段交付过程留下了可继续使用的排查顺序：先确认存储与应用，再检查代理入口，最后核对部署文件和交接资料。每一层都有自己的证据，架构方案、执行记录与持续运行情况也需要分别判断。