test: 补齐覆盖率工具（pytest-cov，fail_under=90，基线 96.67%）

_AI_USAGE_LOG.md

@@ -38,3 +38,4 @@
 | 2026-08-09 09:40 | 测试验证 | 里程碑2.5 Task12 实现：混合型样本 + 端到端验证。生成 samples/要件定義_混合型.xlsx（機能一覧 表格：表头+3 数据行，空行后接「・改修ポイント」「■対象期間」两条连续碎片文本，无空行）；tests/test_real_samples.py 追加 test_mixed_sample_segments_detected（断言 mixed 段落数==2、kinds==["table","free_text"]、表格段第一批数据行機能ID=="F101"、table.rows==3、碎片段 text 含 改修ポイント/対象期間）。验证：real_samples 全绿 4 passed（3 baseline+1 新增，无 skip）；pytest 全量 52 passed（51 baseline + 1）；实际样本 split_paragraphs 产出两段（0,3）+（5,6）（表格段+碎片段）。提交见 git log | samples/要件定義_混合型.xlsx, tests/test_real_samples.py, _AI_USAGE_LOG.md | deepseek-v4-flash-free |
 | 2026-08-09 04:40 | 反馈迭代 | 里程碑2.5 Task13 遗留清理：① extraction_method 枚举同源（free_text_extractor→ExtractionMethod.LLM_FROM_FREE_TEXT.value、table_extractor 空/非空两分支→ExtractionMethod.OPENPYXL.value，值不变既有用例兼容）；② table_extractor header_row 越界/负值防御（<0 或 >=len(matrix) 回落 0，keep if not matrix 早返回）；③ merge_fill.forward_fill 完整替换（min_row<1/min_col<1 非法值跳过 + 越界防御）；④ data_models.Provenance.row 语义注释；⑤ 补测试 6 个（sheet_nature MIXED ・/■ 正向 x2、formatting_detector 字体色正向、table_extractor 枚举锁 + forward_fill 防御、free_text_extractor 枚举锁）。TDD：先加测试确认 RED（仅 forward_fill 防御用例失败，其余为已通过回归锁）→ 实现 → GREEN；pytest 全量 58 passed（52 baseline + 6） | src/genesis/parsers/free_text_extractor.py, src/genesis/parsers/table_extractor.py, src/genesis/parsers/merge_fill.py, src/genesis/data_models.py, tests/test_sheet_nature.py, tests/test_formatting_detector.py, tests/test_free_text_extractor.py, tests/test_table_extractor.py, _AI_USAGE_LOG.md | deepseek-v4-flash-free |
 | 2026-08-09 10:05 | 反馈迭代 | 里程碑2.5 最终评审与交付：整体评审通过（base 81c6b6c..d93cc77，58 passed）；清理 progress.md Task11 重复/编码行；修正 _AI_USAGE_LOG.md Task13 范式步骤用词；产出交付报告 docs/milestone2.5-mixed-parser-review.md（MIXED 遗留#1 闭环） | docs/milestone2.5-mixed-parser-review.md, .superpowers/sdd/progress.md, _AI_USAGE_LOG.md | deepseek-v4-flash-free |
+| 2026-08-09 10:12 | 测试验证 | 补齐覆盖率工具：安装 pytest-cov 7.1.0/coverage 7.15.4，pyproject.toml 固化 dev 依赖+addopts（--cov=genesis --cov-report=term-missing）+[tool.coverage.run/report]（source=genesis、branch=true、fail_under=90、skip_empty、sort=miss）；验证 fail_under=99 拦截 exit 1；产出 docs/coverage-report.md 与 htmlcov（已 ignore）；基线覆盖 96.67%（571 stmts，12 miss） | pyproject.toml, docs/coverage-report.md | deepseek-v4-flash-free |

docs/coverage-report.md

@@ -0,0 +1,60 @@
+# 代码覆盖率报告
+
+- 日期：2026-08-09
+- 工具：`pytest-cov` 7.1.0 / `coverage` 7.15.4
+- 范围：`src/genesis`（排除 tests 自身）
+- 阈值：`fail_under = 90`（`pyproject.toml` `[tool.coverage.report]`），未达标时 pytest 退出码非 0
+- 全量用例：**58 passed，无 skip**
+- 输出：终端摘要（`--cov-report=term-missing`）、HTML（`htmlcov/index.html`，已 .gitignore）
+
+## 总览
+
+| 指标 | 值 |
+|------|-----|
+| 语句总数 | 571 |
+| 未覆盖语句 | 12 |
+| 分支总数 | 150 |
+| 未覆盖分支 | 12 |
+| **总覆盖率** | **96.67%** |
+| 最低模块 | `table_extractor.py` 88% |
+| 最高模块 | 9 个文件 100% |
+
+## 分模块
+
+| 模块 | Stmts | Miss | Branch | BrPart | Cover | 未覆盖行 |
+|------|------:|-----:|-------:|-------:|------:|----------|
+| `__init__.py` | 1 | 0 | — | — | 100% | — |
+| `data_models.py` | 180 | 0 | — | — | 100% | — |
+| `excel_reader.py` | 12 | 0 | 2 | 0 | 100% | — |
+| `free_text_extractor.py` | 22 | 0 | 10 | 0 | 100% | — |
+| `merge_fill.py` | 15 | 0 | 10 | 0 | 100% | — |
+| `paragraph_splitter.py` | 17 | 0 | 10 | 0 | 100% | — |
+| `provenance.py` | 2 | 0 | — | — | 100% | — |
+| `sheet_detector.py` | 20 | 0 | 14 | 0 | 100% | — |
+| `config.py` | 128 | 1 | 24 | 1 | 99% | 134 |
+| `sheet_nature.py` | 33 | 2 | 18 | 3 | 90% | 26, 32, 40→44 |
+| `table_extractor.py` | 24 | 2 | 10 | 2 | 88% | 32, 37 |
+| `formatting_detector.py` | 40 | 3 | 20 | 2 | 92% | 15–16, 22, 31→33 |
+| `excel_parser.py` | 77 | 4 | 32 | 4 | 93% | 36–37, 61, 66→65, 100 |
+
+## 未覆盖点说明（12 语句 + 12 分支）
+
+主要未覆盖区域属于防御分支 / 异常路径：
+
+- `config.py:134` — `unset(_env)` 分支（枚举加载外的环境变量消除路径）
+- `sheet_nature.py:26/32` — 空白行修正 / `value` 缺失兜底
+- `table_extractor.py:32/37` — `column_letter` 越界兜底 / 空列头兜底
+- `formatting_detector.py:15-22` — 非法 RGB 字符串剔除分支
+- `excel_parser.py:36-37,61,100` — 空表跳过、`header_row<0` 回落、无表头 free_text 直接文本化
+
+均为「非法输入 / 防御分支」，非主路径；当前 96.67% 已满足红线 90%。
+
+## 门槛策略
+
+- `pyproject.toml` 已固化 `fail_under = 90`（含 12 个 `branch` 分支统计）
+- 每次 `python -m pytest` 默认附带覆盖率检查；未来若引入重业务逻辑（LLM/Writer 里程碑），可将 `fail_under` 抬至 95~98 并补充新用例
+
+## 后续可选增强（非当前阻塞）
+
+- 将 `fail_under` 提升至 95% 时需补上述 12 行（多为防御分支，成本低）
+- 可在 CI 中将 `--cov-report=html` 或 junit/xml 纳入流水线归档

pyproject.toml

@@ -16,10 +16,25 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
-dev = ["pytest>=8.0"]
+dev = ["pytest>=8.0", "pytest-cov>=7.0"]
 
 [tool.setuptools.packages.find]
 where = ["src"]
 
 [tool.pytest.ini_options]
-testpaths = ["tests"]
+testpaths = ["tests"]
+addopts = "--cov=genesis --cov-report=term-missing"
+
+[tool.coverage.run]
+# 仅统计 src/genesis 业务代码（不含 tests 自身）
+source = ["genesis"]
+# 测量分支覆盖
+branch = true
+
+[tool.coverage.report]
+# 覆盖率门槛：低于该值 pytest 失败（红线，防止回归）
+fail_under = 90
+# 跳过 __init__.py 等空文件干扰
+skip_empty = true
+# 按语句总数降序展示
+sort = "miss"