v1.2.0 - OMR0002 横排题适配 + 3 类误识修复

答题卡智能识别系统 v1.2.0

v1.2.0 重点支持 OMR0002 蒙文答题卡的横排题版面，并修复 v1.1.0 遗留的 3 类识别误识（空卷、多涂、全卷异常降级）。

✨ 新增功能

📐 OMR0002 蒙文横排题版面适配 (option_axis)

OMR0002 等蒙文答题卡采用「题号横排、选项纵排」的特殊版面，v1.1.0 的标准模板（题号纵排、选项横排）无法处理：

• GoldenTemplate._generate_grid 新增 option_axis 字段：
  • "x"（默认）：标准模板，选项在 x 轴、题号在 y 轴
  • "y"：横排题模板，选项在 y 轴、题号在 x 轴
• _calibrate_positions 自动按 option_axis 切换 strict_axis（防被相邻题号/印刷线吸走）
• Tab1 列框配置新增「选项轴」下拉，预览图按 option_axis 画水平/垂直分隔线
• reverse_q 与 option_axis 联动：Q1 永远在题号轴起点

🐛 修复

1️⃣ 空卷被误识为 single（OMR0002 11A/12A）

• 症状：11A/12A 实际无填涂，但 _classify_answer 把 ECC 偏后采样到的题号印刷笔画（暗度 206）误判为 single 答案
• 根因：防线 1 仅当 best_val > 210 才判 empty；11A Q1 best_val=206 落到防线 3 误识
• 修复：防线 1 加 best_val > 200 + best_delta < 15 二级条件，真填涂 best_val 都 < 200（暗），不会受影响

2️⃣ 真实多涂被误判为 uncertain（OMR0002 14A Q9）

• 症状：14A Q9 学生填涂 A+C（暗度 156/159），被识别为 uncertain 而非 multi
• 根因：dark_count 阈值 v < 150 过严，A=156、C=159 都被排掉 → dark_count=0 → 落到防线 3 → 因 gap=3 不满足 single → uncertain
• 修复：dark_count 阈值 150 → 170，abs_dark 阈值 140 → 160

3️⃣ 真填涂卷被降级为白卷（OMR0002 19A）

• 症状：19A 学生填涂的 10 道题全部识别到，但与 gold 完全不同（可能故意错填）；正确率 0% 触发全卷异常检测，10 题全降级为 uncertain，Tab3 显示 10 个「未识别」
• 根因：app.py 全卷异常检测条件「识别出 ≥3 题但正确率 < 10%」误伤「全题都识别但全错」的卡
• 修复：加识别率门槛 identified_count < total_q * 0.3，只对「几乎没识别出来」的扫描异常卡降级，放过「全题都识别但全错」的卡

🔧 杂项

• .gitignore 增量忽略 5 个工具/会话产物目录：.claude/、.codegraph/、.cursor/、.tmp/、runs/
• 物理清理已合入/已废弃的 13 个分支（3 本地 + 10 远程）

✅ 验证

• 单元测试 9/9 边界用例通过（空卷/真填涂/真多涂/浅填涂/OMR0013 Q12/Q16/完全空题）
• OMR0002 四卡综合：19A 10 题 single 全识别、11A empty=8、12A empty=6、14A Q9=AC/multi

v1.1.0 - 架构重构 + Q11/Q16 修复

答题卡智能识别系统 v1.1.0

在 v1.0.0 黄金模板法基础上完成架构重构与识别精度优化，为后续接入 YOLO/AI 识别器铺平道路。

✨ 新增功能

🔌 阶段 1: Recognizer 协议抽象 (#7)

将黄金模板法与差分法统一到 Recognizer 协议下：

• 新增 core/recognizer.py：Protocol + RecognizeContext + RecognizeResult + make_recognizer 工厂
• 新增 core/recognizers/golden.py：黄金模板法适配器
• 新增 core/recognizers/differential.py：差分法适配器（自动重整"(多涂)"后缀）
• 后续接入 YOLO / AI 评分只需新增一个适配器，零侵入 app.py

🎯 阶段 2: ScoreCalculator 集中化 (#3)

把散落在 app.py:810-825 的内联算分循环抽离到独立模块：

• 新增 core/score_calculator.py：calc_total_score / match_answer / round_score 纯函数
• Excel 导出新增 _answers_json 列：未来 ground truth 可直接从历史 Excel 提取
• 算分逻辑 100% 可测试（22 用例），微服务化时可零改动平移到 FastAPI/gRPC

🔀 阶段 7: 双识别器交叉验证 (#8)

黄金模板法 vs 差分法交叉验证，分歧题自动进 Tab3 人工核对：

• 新增 core/recognizer_manager.py：RecognizerManager + 4 种 agreement_type
  • all_empty / all_match / one_uncertain / disputed
• Tab2 新增 enable_cross_validate 开关，默认关闭, 0 回归
• Tab3 高亮 disputed 题 + 新增"分歧""一致率"汇总列
• N=1 降级：单识别器时不误判为 one_uncertain

🐛 Bug 修复

Q11/Q16 低对比度场景误判 empty (#9)

修复真实场景中浅填涂被错判为空题的 bug：

• 根因：core/golden_template.py:301 防线1 阈值 best_delta < 8 过于宽松，Q11/Q16 类浅填涂（best_val=210, best_delta=5-7）穿过所有防线被误判为 empty
• 修复：阈值收紧到 best_delta < 4，提取 _classify_answer 静态方法便于单测
• 新增 13 个边界测试覆盖 Q11/Q16 真实场景 + 阈值上下界

📊 测试覆盖

测试套件	用例数
test_score_calculator.py	60
test_recognizer.py	55
test_recognizer_manager.py	57
test_golden_template.py	48 (含 13 个新增边界用例)
合计	220 passed, 0 failed

🚀 兼容性

• 完全向后兼容：Tab2 默认走原黄金模板识别路径，识别结果与 v1.0.0 一致
• 可选新功能：
  • Tab2 勾选"启用交叉验证"开启双识别器对比
  • Tab3 自动展示 disputed 题高亮

📦 本次发布包含

• 4 个新模块（core/recognizer.py / core/recognizers/* / core/recognizer_manager.py / core/score_calculator.py）
• 4 份单元测试（合计 220 测试用例）
• 3 份设计文档（docs/plans/2026-06-01-stage{1,2,7}-*-design.md）
• app.py 改造：Tab2 走 Recognizer 协议入口 / Tab3 改用 ScoreCalculator / Tab2 交叉验证开关

🔗 快速开始

cd omr_demo
pip install -r requirements.txt
python -m streamlit run app.py

关联 PR：#3, #7, #8, #9

v1.0.0 - 黄金模板对比法首发

答题卡智能识别系统 v1.0.0

基于 Python + OpenCV + Streamlit 的答题卡光学标记识别（OMR）系统。

✨ 核心功能

• 黄金模板对比法（Golden Template）：用一张正确填涂的答题卡作为模板，ECC 全局对齐 + 四道防线判断，识别率 53%+，多涂误判率 2.2%
• 模板识别模式：JSON 模板预定义选项框，支持差分法和固定阈值法
• 手动区域标定模式：在空白答题卡上拖拽画框，支持选择题/个人信息/非选择题三种区域类型
• 自定义选项框标定：直接在标准答案图片上手动画框，解决模板与实际答题卡不匹配问题
• 标准答案识别：上传正确答案答题卡自动识别，支持调试模式查看置信度
• 结果核对与导出：逐题展示识别结果，支持人工修正，批量导出 Excel 成绩单

📊 性能对比

指标	原有方法	Golden Template
识别率	20%	53%+
多涂误判率	27%	2.2%
单张耗时	3ms	123ms

🚀 快速开始

cd omr_demo
pip install -r requirements.txt
python -m streamlit run app.py

📦 包含内容

• 完整 Streamlit Web 应用
• 黄金模板法核心引擎（core/golden_template.py）
• 35 项单元测试全部通过
• 诊断工具套件（坐标诊断、可视化、未识别诊断）
• 9 批次共 358 张答题卡测试样本