docs: Phase3 Word 解析优先设计（模板/规则/聚合三模块）

_AI_USAGE_LOG.md

@@ -59,3 +59,4 @@
 | 2026-08-09 | 测试验证 | 里程碑3.1 LLM错误码对齐收尾改动（最终评审 Minor）：① 删除 tests/test_inference_engine.py 中 test_chat_failed_error_code_not_configured 首行未使用变量 client = FakeLLMClient(...)（死代码，未引用，函数自洽性核查通过）；② 补齐 src/genesis/inference/engine.py 文件末尾换行符（最后一字节 ) → \n）。覆盖测试 22 passed；pytest 全量 128 passed，覆盖 100.00%（803 stmts/188 br），fail_under=99 达标；提交见 git log | tests/test_inference_engine.py, src/genesis/inference/engine.py, _AI_USAGE_LOG.md | deepseek-v4-flash-free |
 | 2026-08-09 | 测试验证 | 新增 api §7 ↔ 异常树 error_code 一致性门禁测试（防文档漂移）。新建 tests/test_api_design_consistency.py（4 用例：树→文档 / 文档→树双向断言 + 行数护栏 / 空解析护栏）；首次运行 RED（行数护栏 ==5 与事实 4 冲突，文档与异常各为 4 条/4 个子类，双向一致）→ 修正护栏为 4 → GREEN（聚焦 4 passed）；pytest 全量 132 passed 覆盖 100.00%（803 stmts/188 br），fail_under=99 达标；提交见 git log | tests/test_api_design_consistency.py, _AI_USAGE_LOG.md | deepseek-v4-flash-free |
 | 2026-08-09 | 测试验证 | 一致性门禁最终评审收尾修复（Important x1 + Minor x3）：① plan 文档 Interfaces 段 L311-314「五行 LLM 行」→「四行」（与 ==4 护栏一致）；② 测试文件补尾随换行（末字节 " → \n）；③ 断言消息改「异常类存在文档未登记或来源类名失配的 error_code」（覆盖双失败场景）；④ _LLM_ROW_RE 加正则隐式限域注释。覆盖测试 4 passed；pytest 全量 132 passed 覆盖 100.00%，fail_under=99 达标 | docs/superpowers/plans/2026-08-09-error-code-consistency-test.md, tests/test_api_design_consistency.py, _AI_USAGE_LOG.md | deepseek-v4-flash-free |
+| 2026-08-09 | 架构设计 | Phase3 Word 解析优先设计（brainstorming）：范围澄清（Word 解析优先=3.1/3.2/3.6/3.7，PPT/现有系统探索后续；规则分类按来源映射零LLM；SourceAggregator 全量整合 StructuredSource；样式名级提取；方案A 三模块门面聚合）；输出设计文档 docs/superpowers/specs/2026-08-09-phase3-word-parser-design.md | docs/superpowers/specs/2026-08-09-phase3-word-parser-design.md, _AI_USAGE_LOG.md | deepseek-v4-flash-free |

docs/superpowers/specs/2026-08-09-phase3-word-parser-design.md

@@ -0,0 +1,160 @@
+# Phase 3「Word 解析优先」设计（Parser Agent - Word 解析 + 聚合）
+
+> **状态：** 已批准（brainstorming + 范围澄清吸收）
+> **日期：** 2026-08-09
+> **里程碑：** implementation-plan 阶段 3（Word 解析优先切片）
+
+## 1. 背景与目标
+
+`implementation-plan.md` 阶段 3 定义 Parser Agent 的 Word/PPT 解析与现系统探索。经范围澄清（用户确认），本次迭代只做 **Word 解析优先** 切片：实现为后续 Writer（阶段 7）、RAG 规则检索（阶段 4）、QA（阶段 8）服务的 **Word 模板解析 / Word 规则文档 Markdown 化 / 全量输入聚合** 基础设施。
+
+**现状：**
+- `data_models.py` 已定义 `ParsedTemplate` / `ChapterMarker` / `RuleDocument` / `StructuredSource` / `UnifiedDocument` 等数据类，可直接复用
+- `parsers/` 已有完整 Excel 解析链（ExcelParser → ExcelParseResult），且 `python-docx>=1.0` 已在 `pyproject.toml`
+- `samples/` 已有 3 个 Word 样本：`概要設計書テンプレート.docx`（模板）、`概要設計做成説明書.docx`（做成说明书）、`記入規則.docx`（记入规则），以及 5 个 Excel 样本
+- 全量测试基线 **132 passed / 100.00% 覆盖**（fail_under=99 红线）
+
+**目标：** 新增 WordTemplateParser（章构成/占位符/样式名提取）、RuleDocParser（docx → Markdown + 规则分类）、SourceParser 门面（按扩展名路由全量输入 → StructuredSource），并配套单元测试与真实样本集成测试，保持红线不回归。
+
+## 2. 范围与不做的事
+
+**范围（implementation-plan 3.1 / 3.2 / 3.6 / 3.7）：**
+- 3.1 WordTemplateParser：章构成（Heading 层级）提取、占位符（`{{section:xxx}}`）检测、样式名提取
+- 3.2 RuleDocParser（Word）：规则文档 Markdown 化、规则分类（按来源映射）
+- 3.6 SourceAggregator：全量输入（Excel 要件定义 + Word 模板 + Word 规则）统一组装 `StructuredSource`
+- 3.7 Parser Agent 集成测试：真实样本（3 Word + 5 Excel）全链路
+
+**不做（YAGNI / 后续里程碑）：**
+- ❌ 3.3 PPTXParser（无 .pptx 样本、python-pptx 未安装）→ 后续补样本后实施
+- ❌ 3.4 现有系统代码探索（CodeParser 未实现、无 .java 样本）→ 后续实施
+- ❌ 3.5 现有系统设计书探索（无现系统 Word/Excel 设计书样本）→ 后续实施
+- ❌ FileReader 统一读取层（UnifiedDocument）（方案 B 否决；现有 Excel 链直接 openpyxl，本轮不重构）
+- ❌ 完整样式定义提取（字号/颜色等）（YAGNI：阶段 3 无样式消费方，阶段 7/8 再按需深挖）
+- ❌ LLM 参与的规则分类（按来源映射，零网络依赖、离线可测）
+- ❌ data_models.py 数据模型改动（现有类型完全够用）
+
+## 3. 设计
+
+### 3.1 架构
+
+在 `src/genesis/parsers/` 下新增 3 个模块，与现有 `excel_parser.py` 同构（扁平模块、dataclass 结果、纯函数拆分）：
+
+```
+parsers/
+├── excel_parser.py          # 现有，不动
+├── word_template_parser.py  # 新：WordTemplateParser
+├── rule_doc_parser.py       # 新：RuleDocParser
+└── source_aggregator.py     # 新：SourceParser 门面
+```
+
+### 3.2 WordTemplateParser
+
+**输入：** docx 路径（`str | Path`）
+**输出：** `ParsedTemplate{file_name, sections, placeholders, styles}`（复用 data_models 类型）
+
+提取逻辑（`python-docx`）：
+
+| 产物 | 提取方式 | 说明 |
+|------|---------|------|
+| `sections` | 遍历文档段落，识别 Heading 样式的段落 → `ChapterMarker(type="heading", name=段落文本, level=大纲级别)`；遍历书签（`bookmarkStart`）→ `type="bookmark"`；遍历占位符 → `type="placeholder"` | `ChapterMarker.type` 取值 `"heading" | "bookmark" | "placeholder"` |
+| `placeholders` | 正则识别 `{{section:xxx}}` 与封面型 `{{doc_title}}` / `{{version}}` / `{{created_at}}` → `{占位符名: 出现位置或上下文}` | 占位符名去重 |
+| `styles` | 收集文档命名样式 + 各段落实际使用的样式名 → 去重集合 | **样式名级**（不提取字号/颜色/字体明细） |
+
+### 3.3 RuleDocParser
+
+**输入：** docx 路径 + `category`（调用方按来源映射传入：`"write" | "design" | "ref"`）
+**输出：** `RuleDocument{file_name, category, markdown_content, source_path, file_type="word", hash}`
+
+Markdown 化规则：
+
+| docx 元素 | Markdown 输出 |
+|-----------|--------------|
+| Heading 1/2/3 | `#` / `##` / `###` 标题行 |
+| 普通段落 | 文本行 |
+| 表格 | GFM 表格（表头 + 分隔行 + 数据行） |
+| 列表（List Bullet/Number） | `- ` 项 / 编号项 |
+| 空段 | 空行 |
+
+- `hash` = 文件内容 sha256 hex（供阶段 4 规则版本管理）
+- `file_type` 固定 `"word"`
+
+**来源映射（分类策略，零 LLM）：**
+
+| 输入文件 | category |
+|---------|----------|
+| `記入規則.docx` | `write` |
+| `概要設計做成説明書.docx` | `ref` |
+
+**明确的策略：** `rule_paths` 仅接受 `.docx` 规则文档；类别由门面按文件名映射（`記入規則*` → `write`，`*説明書*` → `ref`，其余文件名 → `write` 兜底）。Excel 图表规则（`図表規則.xlsx`）本轮**不纳入** `rule_docs`（Excel 规则解析留给后续迭代）。
+
+### 3.4 SourceParser 门面（3.6 SourceAggregator）
+
+**输入：**
+- `requirement_paths: list[str | Path]` — 要件定义 Excel 列表
+- `template_path: str | Path | None` — 概要设计模板 docx
+- `rule_paths: list[str | Path]` — 规则文档列表（**仅 docx**）
+
+**类别映射（内置于门面，零 LLM）：** `rule_paths` 中文件名含 `記入規則` → `write`；含 `説明書` → `ref`；其它 → `write` 兜底。
+
+**路由：**
+
+| 扩展名/角色 | 解析器 | 产物 |
+|------------|--------|------|
+| `.xlsx` | 现有 `ExcelParser` | `tables` + `comments` |
+| 模板 docx（template_path） | `WordTemplateParser` | `template: ParsedTemplate` |
+| 规则 docx（rule_paths） | `RuleDocParser` | `rule_docs: list[RuleDocument]` |
+
+**输出：** `StructuredSource{tables, template, rule_docs, image_analyses=[], existing_system=None, comments}`（`image_analyses`/`existing_system` 本轮恒为空/None，类型字段保留）。
+
+### 3.5 数据流
+
+```
+samples/*.xlsx ─────────────► ExcelParser ─────► tables / comments
+samples/テンプレート.docx ──► WordTemplateParser ─► template: ParsedTemplate  ─┐
+samples/記入規則.docx ──────► RuleDocParser ────► rule_docs: [RuleDocument] ──┼─► StructuredSource
+                                                                              ┘
+```
+
+### 3.6 错误处理
+
+| 场景 | 行为 |
+|------|------|
+| 文件不存在 | 抛出 `FileNotFoundError`（消息含路径，便于定位） |
+| 模板无 Heading / 空文档 | 返回空 `sections`/`placeholders`，不崩溃（与 ExcelParser 的 skipped 哲学一致） |
+| 非法占位符格式（非 `{{section:xxx}}` / `{{doc_*}}`） | 不识别为占位符，正文文本原样保留 |
+| 未知扩展名（如 `.txt`/`.md`） | `SourceParser` 路由阶段报错：`ValueError("不支持的文件类型: ...")` |
+| docx 损坏 | 透出 python-docx 异常（PackageNotFoundError），测试不吞 |
+
+### 3.7 与现有代码的关系
+
+- **不改** `excel_parser.py`、`data_models.py`、`pyproject.toml`、任何现有测试
+- 只新增 `src` 3 个生产模块 + 3 个测试文件 + 扩展 `test_real_samples.py`
+- 提交消息前缀：`feat:`（生产实现）/ `test:`（门禁测试）/ `docs:`（本文档与 AI 日志）
+
+## 4. 文件定位与测试先例
+
+- 单元测试沿用 `tests/test_real_samples.py:7` 的定位方式：`Path(__file__).resolve().parents[1] / "samples"`，样本缺失 `pytest.skip`
+- 临时 docx 构造（单元测试）：用 `python-docx` 在 `tmp_path` 生成内存文档（Heading/表格/占位符/书签），不依赖真实样本
+- 全量回归命令：`python -m pytest -q`（保持 ≥ 132 passed / 100.00%）
+
+## 5. 验收标准
+
+1. `python -m pytest tests/test_word_template_parser.py tests/test_rule_doc_parser.py tests/test_source_aggregator.py tests/test_real_samples.py -v` 全绿
+2. 全量回归 `python -m pytest -q` ≥ 132 passed（新增用例后 ≥ 现有基线 + 新增数）/ 100.00% 覆盖
+3. 真实样本：模板 docx 解析出 7 个 H1 章（はじめに…バッチ一覧）+ 占位符；记入规则 docx 产出 category="write" 的 markdown
+4. 门面全量组装：`StructuredSource.tables` 非空、`template` 非 None、`rule_docs` 含 write/ref 两类
+5. 手工破坏验证（可选）：删除模板占位符段落 → 占位符断言变红；恢复正常
+
+## 6. 影响面
+
+- 新增生产文件 3 个：`src/genesis/parsers/word_template_parser.py`、`rule_doc_parser.py`、`source_aggregator.py`
+- 新增测试文件 3 个：`tests/test_word_template_parser.py`、`tests/test_rule_doc_parser.py`、`tests/test_source_aggregator.py`
+- 修改文件：`tests/test_real_samples.py`（追加 3 个 Word 样本用例）、`_AI_USAGE_LOG.md`（追加日志行）
+- 提交纪律：分任务提交（feat/test/docs/chore 各自独立 commit）
+
+## 7. 不做的事（YAGNI 最终确认）
+
+- ❌ PPTXParser（3.3）— 无样本、无依赖，后续里程碑
+- ❌ 现有系统代码/设计书探索（3.4/3.5）— CodeParser 未实现
+- ❌ FileReader 统一读取层 — 现有 Excel 链不重构
+- ❌ 完整样式定义 / LLM 规则分类 / 模型改动