后端可靠性与重构验收的边界

九月推进前端重构的同时，SCORE 也在修正后端的权限、事务和恢复流程。

这轮审查从匿名分析、损坏备份、并发快照、恢复中间态和凭据处理等问题开始。它们涉及权限与数据完整性，因此先修复行为，再调整模块结构；每项结论都需要保留对应的验证范围。

1. 先处理权限与数据一致性

九月审查复现的问题及处理方式如下：

问题分类	治理前潜在隐患	采取的整改措施
预览与导出权限	接口未完整校验身份与任教范围	先认证，再通过已有授权查询取数
并发读改写覆盖	两次操作各读旧快照，后写覆盖前写	将读取、计算与持久化放入同一操作边界
备份完整性	损坏输入被规范化为空库后恢复	写入前检查清单、结构、版本与引用
恢复一致性	主库、会话与撤销状态只恢复一部分	按存储模式执行事务、原始字节恢复与补偿；未定提交或补偿失败时保留恢复记录
凭据与公开字段	明文凭据被持久化或进入公开响应	使用 scrypt、移除明文认证回退，并对公开账号响应采用字段白名单
输入预算	鉴权前无限缓存请求，表格解析无预算	提前鉴权，限制读取字节、耗时、工作簿展开规模与 Worker 资源
健康检查副作用	普通探测可能触发数据库建表	初始化显式执行，探测只读且输出脱敏
备份查找与错误边界	无关坏备份阻断查找，内部错误被误报或泄露细节	隔离无关损坏，保留已知业务错误，未知内部错误统一脱敏
异步响应	备份概览未等待异步结果，HTTP 返回空对象	补齐等待，并核对真实 JSON 响应

分析接口仍保留需要登录、明确标注的样本兼容路径。不可见或不存在的目标不能通过回查原始成绩暴露存在性。凭据迁移的实现与隔离验证已经记录，但没有据此对真实学校数据库执行迁移。

并发保护也因存储方式而不同：文件模式按真实数据目录互斥，使用原子文件替换，失败时恢复原始字节；MySQL 模式采用命名锁加事务，操作内复用同一连接。不能把两种机制合写成所有状态都由一个数据库事务自动回滚。

完整恢复另外涉及主库、撤销快照和会话清理。执行前先核验必要能力，缺少能力就报装配错误；过程中按受保护的恢复流程提交或补偿。下图只描述恢复专项，不代表每个普通请求都会执行这些步骤：

已授权的完整恢复请求

核验备份与必要恢复能力

进入存储对应的操作边界

恢复主库、撤销快照与会话状态

执行结果

成功

完成恢复

可确定的失败

按存储模式回滚或补偿

恢复完成

返回明确错误

提交结果不确定 ／ 回滚补偿失败

保留恢复记录，阻止相应目录的普通业务

最后那个框只有一个，但有两条入路：提交结果不确定，以及上一条分支里回滚补偿本身也失败。两种情况下系统都无法自证数据已经一致，所以收尾方式相同。

未定提交或补偿失败时需要明确的离线恢复。阻断以相应本地数据目录为范围，没有承诺自动解决断电或多主机故障。

一次复现还发现：业务写入后抛错，如果控制器提前将异常转成正常响应，外层操作可能误判成功。修复要求先让错误穿过操作边界完成回滚，再转换成用户响应；验证因此既要看 HTTP 结果，也要检查失败前后的数据。

输入预算同样有边界。字节、解析时间、Sheet、单元格与 Worker 堆限制经过合成越限场景检查，但这些限制不是生产容量结论，也不是整个进程内存的绝对上限。

2. 拆分职责，并区分缺失与损坏

可靠性修复后，结构调整继续按职责提取模块：

1. 纯规则计算：提取配置归一化、归档规则、趋势与比较模型，减少对数据库连接和 HTTP 上下文的依赖，使这些规则可以独立测试。
2. 查询、权限与操作记录：继续留在原服务入口，避免结构拆分改变授权与业务操作边界。
3. 导出投影、布局与序列化：报表布局接收已经授权取得的数据，不重新访问仓储；内容、排版与文件生成分别处理。

同时，系统严格规范了错误语义：

• 区分“文件不存在”（正常的空结果，返回业务默认态）与“文件存在但已损坏 / IO 异常”（明确报错并提供修复指引）；
• 持久化输入先校验，再兼容合法旧格式；不能用默认空对象掩盖已经存在的数据损坏。

完整恢复允许在受保护流程中替换坏会话，普通会话修改仍拒绝损坏，两者不能共用宽松回退。新增模块依赖检查也只覆盖本轮划定的边界，没有证明所有旧耦合已经清理。

3. 验收的真实边界：我们在什么范围内证明了什么

在重构接近尾声时，工程上最需要保持的是对测试结论的诚实与克制。

SCORE 在各个阶段留下了详实的验证记录，但各项数据必须在特定的上下文中被理解，绝不能将其随意加总或无限放大：

• 后端结构回归：94 个测试文件、439 项测试通过，八类导出共 19 对工作簿模型一致，支持该轮指定范围的行为兼容；不代表所有行为完全等价，也不证明真实 MySQL 或学校现场并发表现。
• 导出专项：桌面 Microsoft Excel 检查 7 个合成文件、15 个目标工作表，支持这些文件在该环境下的布局结果；不覆盖任意内容长度、其他表格软件或所有历史报表。
• 前端门禁：20 个测试文件、315 项测试通过，并有类型检查与构建记录，说明指定版本通过了相应检查；不代替所有页面和业务操作验收。

这些数字属于不同范围与版本，不能相加成一个新的总通过数。模型对照也不要求 XLSX 压缩包字节完全一致。

截至 2026 年 9 月 15 日整理材料时，最新总验收记录更新于 9 月 8 日，状态仍为 needs-verification。后端结构专项的实现与限定验收完成，不等于整个项目最终验收完成；原任务仍要求汇总页面、全链路、导出与文档修订及其源码、构建版本，确认修复仍由有效证据覆盖。

明确未被证明的事项

为了对系统质量负责，必须清晰界定当前验证的边界：

1. 数据库与容量：现有隔离验证不证明真实 MySQL 的权限与并发验收、生产容量，以及断电和多主机故障恢复。
2. 迁移与上线：没有真实业务数据迁移、新版学校部署和旧版物理删除的完成证据。双轨入口形成不等于生产切换完成，构建通过也没有消除较大 JavaScript 包体积提示。
3. 持续使用与教学成效：资料没有量化升学率变化或长期使用成效，不能从实现了追踪工具推导出教学效果。

这轮后端工作把权限、存储操作和恢复失败处理放到明确边界内，再通过结构拆分让规则更容易检查。文章能够报告的是这些修复与限定验证，剩余总验收和生产证据需要继续单独补齐。