项目介绍很容易只保留正确答案：我们最终采用了什么架构、通过了多少检查、画出了怎样的闭环。可真正体现判断力的，往往是那些后来被推翻的决定。
TeachFlow 的长期开发记录里有六类这样的转折。它们并不都来自严重事故，有些只是一个最小反例、一段浏览器行为或一次数据对账，足以证明原来的“合理方案”缺少关键条件。
1. 先 OCR 再切题
原判断：整页先识别文字，再根据文本切成单题，流程更简单。
反例：跨页长题、图文混排和错误框会让 OCR 顺序与真实题目边界错位；后续再切无法恢复原始版面证据。
修正：先用版面分析形成候选框，教师修框并确认裁片，再对每道题独立 OCR；原裁片、识别结果和人工修改一起保留。
原则：当输入结构本身是证据时，不能先把它压扁成文本。
2. 一次独立答对就显示 secure
原判断：独立正确已经是最强单次证据，可以直接显示掌握。
反例：幸运答对立即得到 mastery=1 / secure，状态强度远大于证据量。
修正：至少两条独立、无提示正确达到最低权重，提示依赖、迁移和时间仍单独保留。
原则：事件正确性与长期状态不是同一个合同。
3. 白板笔画属于 Lesson
原判断：把白板笔画和课程一起保存，最容易恢复。
反例：同一课程给两个班授课时会互相污染；一次课堂涂写还会无意义增加 Lesson revision，并与冻结 Publication 分叉。
修正：正式板书进入 Classroom Session 的 Board；预览页只保留内存态，课堂结束后只读回看，教师明确确认后才沉淀为新的课程版本。
原则：模板、发布快照与运行实例必须分开。
4. 测试写共享库，结束后清理即可
原判断：复用开发库更快，只要脚本最后删除夹具。
反例：异常退出、append-only 子记录与脚本顺序依赖留下残留；恢复演练才暴露孤儿外键。
修正：常规回归拥有一次性 PostgreSQL、Neo4j 和动态端口；Golden seed 与恢复演练保留独立职责。
原则：不要把清理能力当作状态所有权。
5. build 通过就可以发布
原判断：生产构建成功代表工程质量已经足够。
反例：构建可以配置为忽略 TypeScript 错误，也不会证明数据库原子性、浏览器真实交互、备份恢复或窄屏可用。
修正：类型、lint、focused contract、隔离数据库、production 浏览器、恢复和 Golden Demo 分层验收。
原则：每个检查只证明自己的范围。
6. 参考项目能力越多，TeachFlow 越强
原判断：优秀开源项目已有的功能，尽量完整迁入可以加速项目。
反例：第二套页面、会话和运行时会制造两套事实权威，项目难以回答“课程和学情到底归谁”。
修正：只采纳窄能力与方法，输出回到 TeachFlow 的领域对象；缺少用户任务、权威归属和停止条件的扩展被冻结。
原则：集成首先是责任设计，其次才是代码复用。
这些转折有什么共同结构
六个错误判断都不是“技术水平不够”，而是把一个局部成立的事实扩张成了全局结论：
- OCR 能识字，不代表它能恢复题目结构；
- 一次作答正确，不代表能力稳定；
- Lesson 能保存内容，不代表它拥有课堂状态；
- DELETE 能清数据，不代表测试拥有共享库；
- build 能产出文件，不代表用户工作流成立；
- 开源项目功能丰富，不代表它适合作为本地权威。
后来形成的修复方法也高度一致：
- 找到最小可靠反例；
- 写出被破坏的产品不变量；
- 定位最早让不变量失真的权威层；
- 在该层做最小完整修复；
- 用正例与邻近反例保护；
- 把仍未验证的结论留在边界里。
NIST AI RMF 强调风险治理需要随上下文、能力和影响变化而持续迭代。对个人项目而言，这不必变成繁重流程，但需要留下“为什么改”和“什么会让我们再次改”的记录。
哪些内容不应该美化
这些调整来自源码与项目记录，部分历史回归尚未重新执行。它们主要解决状态归属和工程一致性；教师实际使用、教学效果与生产运行仍需单独验证。
下一次遇到相似设计问题，可以先复用这里的反例：尝试跨班读取、重放旧版本、重复提交或改变输入来源，再观察状态是否仍由正确的对象管理。
常见问题与设计边界
你如何判断该修补还是重构？
先找最早失真的权威层。如果局部合同能恢复不变量，就做最小修复；只有多个核心对象都无法表达真实业务时，才考虑结构重构。
哪一次推翻的代价最大？
测试状态所有权和课堂状态归属影响面最大，因为它们会让其他验证结果也失去可信度；但具体工时没有形成可公开统计。
如何避免反复摇摆？
记录当时 context、decision、consequence、证据状态和 revisit trigger。新证据改变前提时可以推翻，但不能只因出现新技术就重开决定。
参考资料
- NIST AI RMF Core
- The GDS Way：Documenting architecture decisions
- TeachFlow
项目亮点与演进.md、DESIGN_DECISIONS.md与相关专项脚本
结论
这些反例改变了 TeachFlow 对课堂状态、事实归属与测试资源的处理方式。后续设计需要保留决定成立的条件；条件变化时，先重跑对应反例，再判断是否需要调整合同。