里程碑 3.5（Word 解析优先）评审与交付报告

日期：2026-08-10
状态：通过（5 任务逐项 task review 全部 Approved + 最终 whole-branch review With fixes 已闭环）
关联文档：docs/superpowers/plans/2026-08-09-phase3-word-parser.md、docs/superpowers/specs/2026-08-09-phase3-word-parser-design.md、docs/api-design.md（§2.2）、docs/rag-layer-design.md（§1.1）

一、交付内容

新实现 3 个解析模块 + 1 个共享 helper + 测试基建 + 真实样本集成测试，共 28 个新增测试用例（当前全量 160 passed / 100.00% 分支覆盖），7 个提交：

任务	提交	说明
计划修订（Pre-Flight 裁决）	`7bc9175`	Task 1 前缀 `chore:`→`test:`；`_heading_level` 重复定义→提取共享 `_word_common.py`；兜底分支测试补齐
Task 1 docx 测试基建	`e8771aa`	`tests/docx_helpers.py`：`new_document`/`save_document`/`make_rule_doc`（与 `tests/excel_helpers.py` 对称）
Task 2 WordTemplateParser	`00fcbf1`	`_word_common.py`（`heading_level` 共享 helper）+ `word_template_parser.py`（章构成/占位符/书签/样式名提取）
Task 3 RuleDocParser	`9ab11da`	`rule_doc_parser.py`：Markdown 化 + 列表双通道检测 + GFM 表格 + sha256 hash
Task 4 SourceParser 门面	`7f29cc9`	`source_aggregator.py`：显式角色参数路由全量输入 → `StructuredSource`
Task 5 真实样本集成测试	`16921ec`	`test_real_samples.py` 追加 4 个 Word 样本端到端用例
最终评审收尾	`31167c9`	3 文件补尾随换行 + import 排序 + SourceParser 契约优先级注释

验收项	结论
WordTemplateParser 章构成（H1 大纲级别）	✅ 模板样本 7 个 H1（1.はじめに…7.バッチ一覧）全命中
占位符提取（封面型 `{{doc_title}}` / section 型 `{{section:xxx}}`）	✅ 统一正则，样本 `section:introduction`/`doc_title` 命中
书签提取（bookmarkStart）	✅ 样本 `template_start` 命中（含无 name 兜底分支覆盖）
样式名级提取 `{defined, used}`	✅ 空文档不崩溃，样式名去重排序
RuleDocParser Markdown 化	✅ Heading→#、列表→`-` 、表格→GFM（含 `\|` 转义）、空段→空行
列表双通道检测（List 样式 OR ・/-/• 前缀）	✅ 真实样本「・前缀 Normal 样式」命中（spec §3.3）
hash = 文件内容 sha256 hex	✅ 64 位 hex，稳定
SourceParser 显式角色参数（对齐 api-design file_type）	✅ requirements/template/write_instruction/rules 四角色
规则分类按来源映射 category=write（零 LLM）	✅ 做成说明书与记入规则均 write（api-design §2.2 Type A）
错误处理 FileNotFoundError / ValueError 未知扩展名	✅ 两契约各有测试
全量组装 StructuredSource（tables/template/rule_docs/image_analyses/existing_system/comments）	✅ 真实样本 4 输入端到端通过
覆盖率红线	✅ 160 passed / 100.00%（929 stmts / 236 br，branch=true），fail_under=99 达标
既有代码零改动	✅ `excel_parser.py`/`data_models.py`/`pyproject.toml`/既有测试全程未触碰

Task 1 提交前缀：Global Constraints 规定 feat:/test:/docs:，Task 1 原计划 chore: → 用户裁决改用 test:。
_heading_level 重复定义：Task 2/3 各写一份相同函数（review rubric 视 verbatim duplication 为缺陷）→ 用户裁决提取共享 helper _word_common.py，Task 2 新建、Task 3 复用。
覆盖率补齐（branch=true 刚性要求）：
- Task 2：bookmark 用例内追加无 name 元素，命中 if name: 假分支（8 用例不变）；
- Task 3：test_parse_empty_document 补 doc.add_paragraph("")，命中空段→空行分支（6 用例不变）；
- Task 4：brief 6 用例外补 4 个用例（模板未知扩展名、规则路径缺失、两处无扩展名兜底），各对应一个不可达分支（全量 156 替代计划 152；Task 5 基线随之调整，最终 160）。
上述补齐均经 task reviewer 裁定为「合法最小覆盖」非 scope creep。

最终 whole-branch review（7bc9175..16921ec）结论 With fixes，无 Critical/Important；Minor 收尾已一次 commit 闭环：

缺尾随换行 ×3（合并前置硬性项）：source_aggregator.py/test_source_aggregator.py/test_real_samples.py 末字节补 \n。
import 排序：test_real_samples.py 新增导入改为字母序（rule_doc → source_aggregator → word_template_parser）。
契约优先级注释：SourceParser.parse docstring 注明「扩展名校验先于存在性校验」。

ParsedTemplate.sections 跨类型顺序无保证：bookmark marker 一律追加在 heading/placeholder 之后，与 DOM 实际位置无关。当前 src/ 无任何消费者读取 sections（grep 验证），无实际影响；建议 Writer 里程碑落地时改为单遍 DOM 顺序合并或在 ChapterMarker 补位置字段（spec 显式规定）。
无法打开异常无显式测试：WordTemplateParser 依赖「不捕获即透出」的隐式保证；建议补一例 tmp_path/"missing.docx" 断言抛异常，防未来误加 try/except。
RuleDocParser 双读文件：Document(str(path)) 与 read_bytes() hash 各读一次；可合并为 data = read_bytes() → Document(io.BytesIO(data))，微优化非必须。
函数体内 import：rule_doc_parser.py 循环内 from docx.text.paragraph import Paragraph / from docx.table import Table，纯风格可提至模块顶部。
扩展名/存在性校验优先级重叠：不存在的文件若扩展名未知 → ValueError 而非 FileNotFoundError（计划既定顺序，docstring 已注明）。
后续迭代（非本里程碑范围）：PPTXParser（补样本 + python-pptx）、ExistingSystemExplorer（补 Java 样本 + CodeParser）、Excel 图表规则解析（図表規則.xlsx → design/write）。

全量：python -m pytest → 160 passed in ~5.9s，覆盖率 100.00%（929 stmts / 236 br），fail_under=99 达标
真实样本端到端：模板 7 H1 + 占位符 + 1 书签 / 記入規則 write + markdown / 做成説明書 write / 4 输入全量组装（tables 非空 + template 非空 + rule_docs==2 全 write），0 skip
每任务独立 commit，逐项 task review 均 Approved（含 spec 合规 + 代码质量双裁决）