学校里最常见的教学数据不一定来自在线答题，而是一张已经批改好的成绩表。把它“导入系统”看起来只是读 Excel、循环插入数据库；一旦这些分数会改变学生学情，导入就不再是文件功能，而是一次高风险事实写入。
TeachFlow 要解决的核心问题是：一场测验要么完整进入可信证据链，要么一条也不进入。
为什么逐行成功不可接受
假设一张表有 40 名学生、10 道题。前 27 名写入成功，第 28 行因为学生 ID 错误失败。如果系统保留前面的结果，教师会看到一个“部分班级”的平均掌握度，却很难知道缺了谁、哪些题已经重算、重试会不会重复。
所以导入合同必须覆盖整场测验，而不是一行：
第一步：文件解析不产生事实
客户端读取 CSV/XLSX，只生成列、样例值与候选映射。教师需要明确：
- 哪一列是稳定
student_id； display_name仅用于人工核对；- 哪些列对应正式 LearningTask；
- 分数如何转成正确/错误；
- 测验发生时间与时区；
- 哪些空值代表缺考，而不是错误。
此时任何预览都不能修改 Current。
第二步：服务端预检使用真实事务
纯前端预检无法发现服务端权限、任务版本、不可变证据冲突或数据库约束。TeachFlow 会在 PostgreSQL 事务中执行与正式提交相同的解析、映射与校验，然后整体 rollback，只返回可复核结果。
PostgreSQL 官方文档对 ROLLBACK 的语义很直接：中止当前事务并丢弃该事务中的全部更新。这里的重点不是数据库术语，而是预检和提交必须共享同一条权威代码路径，否则“预检通过、正式失败”会成为常态。
第三步：确认后整批提交
教师确认后，系统按班级、测验批次、任务和学生生成幂等键，并在一个事务中：
- 校验教师仍然拥有班级权限；
- 校验任务、知识点与图版本仍然有效；
- 写入原始答案、正误、独立性、提示与时间；
- 追加 LearningEvent、Attempt、Response 等事实；
- 重算个人与班级 Current；
- 写入 Neo4j Outbox。
任一学生越权、映射失效或不可变 evidence 冲突，整个批次失败。重试同一批次返回同一结果，不会让一场测验被计算两次。
原子性之外还有语义正确
数据库全成或全败，并不自动保证教学含义正确。最危险的几个问题是：
- 用姓名作为关联键，遇到重名或改名；
- 把缺考当作 0 分；
- 允许客户端自己指定知识点和权重；
- 把总分列重复映射为多道题；
- 导入后覆盖原证据，无法追踪纠错；
- 只更新班级平均值，不保留每条输入。
TeachFlow 因此让 display_name 只参与核对，正式关联始终使用稳定 ID；知识点与权重由服务端从正式任务读取；纠错通过后继事件完成，不覆盖原始导入事实。
与 OneRoster 的关系
1EdTech OneRoster 的 CSV 规范强调批量文件之间的标识引用与依赖，例如 Enrollment 必须引用 class、school 和 user 的 sourcedId。TeachFlow 并没有声明实现完整 OneRoster，但这个标准帮助解释了为什么稳定标识和跨文件依赖不能靠“名字差不多”解决。
当前证据边界
源码与项目记录显示，专项检查覆盖单条和 CSV/XLSX 多题教师评分、预检回滚、整批原子提交、班级授权、Episode 归属、并发幂等和不可变事实。本文固定快照未附带新的隔离 PostgreSQL 执行回执，因此不公布成功率或耗时，也不声称已兼容学校所有 Excel 模板。
照片答卷 OCR 仍是另一条风险更高的链。当前文章只讨论已经结构化、已经批改的表格，不把识别结果直接当作评分事实。
常见问题与设计边界
为什么预检要真的写再回滚，不能只校验 DTO？
因为唯一约束、权限、现有 evidence 冲突和重算路径都在数据库边界。只校验 DTO 证明不了正式事务会成功。
文件有一行错，能否允许跳过继续？
可以设计“明确排除后重新确认”的新批次，但不能默默跳过。教师必须知道最终进入学情的是哪个确定集合。
如何处理老师重复上传？
幂等键绑定班级、测验批次、任务和学生；相同事实安全重放，不同内容冲突并阻止覆盖。
参考资料
- PostgreSQL 16：ROLLBACK
- PostgreSQL：START TRANSACTION
- 1EdTech OneRoster 1.2.1 CSV Binding
- TeachFlow
lib/learning-state/evidence-import.ts、lib/learning-state/teacher-evidence.ts、scripts/teacher-evidence-check.mjs
结论
成绩表导入的完成标准不是“读出了 400 个格子”，而是教师能够确认一组稳定映射，系统用真实事务证明它可提交，并让整场测验以不可变、幂等、可追溯的方式进入学情。只有这样，一张 Excel 才从办公文件变成可信教学证据。