599 lines
23 KiB
Markdown
599 lines
23 KiB
Markdown
# MIXED 完整段落解析 实施计划
|
||
|
||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||
|
||
**Goal:** 将 MIXED（混合型）Sheet 落地 design §3.5.2「段落分割→各段落最优解析」，显式表达段落边界与类型。
|
||
|
||
**Architecture:** 新增纯函数段落分割器 `paragraph_splitter.py`（以空行为界的通用分割）；扩展 `data_models.py` 追加 `MixedParagraph`/`MixedSheet` 容器与 `ExcelParseResult.mixed` 字段；`excel_parser.py` 中为 MIXED 性质新增装配分支（分割→每段 classify→表格段 extract_table/自由文本段 build_free_text_table）；新增混合型样本 `samples/要件定義_混合型.xlsx` 驱动端到端。
|
||
|
||
**Tech Stack:** Python 3.11+，openpyxl 3.1.5，pytest，dataclasses，typing。
|
||
|
||
## Global Constraints
|
||
|
||
- 项目为中文交流（注释中文、标识符英文），Windows/PowerShell 环境
|
||
- `data_models.py` 的既有类与字段**不得修改或删除**（仅追加新类与带默认值的新字段）
|
||
- 既有 TABLE / FREE_TEXT 解析路径**不得改行为**（回归保持 41 passed）
|
||
- 测试命令：`python -m pytest tests/<file> -v`；全量回归：`python -m pytest -v`
|
||
- 提交消息风格：`feat:` / `test:` / `docs:`（简中文描述）
|
||
- 每次修改后按项目规则追加 `_AI_USAGE_LOG.md` 记录（范式步骤列：Agent 实现 或 测试验证）
|
||
|
||
---
|
||
|
||
### Task 9: 段落分割器 `split_paragraphs`
|
||
|
||
**Files:**
|
||
- Create: `src/genesis/parsers/paragraph_splitter.py`
|
||
- Create: `tests/test_paragraph_splitter.py`
|
||
|
||
**Interfaces:**
|
||
- Consumes: 无（纯函数，仅类型 `Any`）
|
||
- Produces: `split_paragraphs(matrix: list[list[Any]]) -> list[tuple[int, int]]` — 以全空行为界的段落序号区间（含行区间端点**，矩阵 0-based；空矩阵 → `[]`）
|
||
|
||
- [ ] **Step 1: 写失败测试**
|
||
|
||
`tests/test_paragraph_splitter.py`:
|
||
```python
|
||
from genesis.parsers.paragraph_splitter import split_paragraphs
|
||
|
||
|
||
def test_empty_matrix():
|
||
assert split_paragraphs([]) == []
|
||
|
||
|
||
def test_single_paragraph_no_empty_rows():
|
||
m = [["a", "b"], ["c", "d"]]
|
||
assert split_paragraphs(m) == [(0, 1)]
|
||
|
||
|
||
def test_split_on_middle_empty_row():
|
||
m = [["a"], [], ["b"], ["c"], []]
|
||
assert split_paragraphs(m) == [(0, 0), (2, 3)]
|
||
|
||
|
||
def test_trailing_empty_rows_no_extra_paragraph():
|
||
m = [["a"], [], [], []]
|
||
assert split_paragraphs(m) == [(0, 0)]
|
||
|
||
|
||
def test_leading_empty_rows_start_at_first_nonempty():
|
||
m = [[], ["a"], [], ["b"]]
|
||
assert split_paragraphs(m) == [(1, 1), (3, 3)]
|
||
```
|
||
|
||
- [ ] **Step 2: 运行确认失败**
|
||
|
||
Run: `python -m pytest tests/test_paragraph_splitter.py -v`
|
||
Expected: FAIL（import 错误 `ModuleNotFoundError: No module named 'genesis.parsers.paragraph_splitter'`）
|
||
|
||
- [ ] **Step 3: 实现**
|
||
|
||
`src/genesis/parsers/paragraph_splitter.py`:
|
||
```python
|
||
from __future__ import annotations
|
||
|
||
from typing import Any
|
||
|
||
|
||
def _is_blank_row(row: list[Any]) -> bool:
|
||
return all(c is None or str(c).strip() == "" for c in row)
|
||
|
||
|
||
def split_paragraphs(matrix: list[list[Any]]) -> list[tuple[int, int]]:
|
||
"""以全空行为界的通用段落分割；返回 (start_row, end_row)（含端，0-based）。"""
|
||
paragraphs: list[tuple[int, int]] = []
|
||
start: int | None = None
|
||
for i, row in enumerate(matrix):
|
||
if not _is_blank_row(row):
|
||
if start is None:
|
||
start = i
|
||
else:
|
||
if start is not None:
|
||
paragraphs.append((start, i - 1))
|
||
start = None
|
||
if start is not None:
|
||
paragraphs.append((start, len(matrix) - 1))
|
||
return paragraphs
|
||
```
|
||
|
||
- [ ] **Step 4: 运行确认通过**
|
||
|
||
Run: `python -m pytest tests/test_paragraph_splitter.py -v`
|
||
Expected: PASS（5 passed）
|
||
|
||
- [ ] **Step 5: 提交**
|
||
|
||
```bash
|
||
git add src/genesis/parsers/paragraph_splitter.py tests/test_paragraph_splitter.py
|
||
git commit -m "feat: 段落分割 split_paragraphs（通用空行分词）"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 10: data_models 扩展（MixedParagraph / MixedSheet）
|
||
|
||
**Files:**
|
||
- Modify: `src/genesis/data_models.py`（在文件末尾追加，不修改既有类）
|
||
|
||
**Interfaces:**
|
||
- Consumes: `typing.Literal`、`ExcelTable`、`SheetType`（已有）
|
||
- Produces:
|
||
- `MixedParagraph(kind: Literal["table","free_text"], matrix: list[list[Any]] | None = None, table: ExcelTable | None = None, text: str | None = None, source_range: tuple[int, int] | None = None)`
|
||
- `MixedSheet(name: str, paragraphs: list[MixedParagraph] = field(default_factory=list))`
|
||
- `ExcelParseResult.mixed: list[MixedSheet]` 新增字段（带默认值）
|
||
|
||
- [ ] **Step 1: 写失败测试**
|
||
|
||
在 `tests/test_excel_parser.py` 末尾追加（先测字段存在性与默认行为）：
|
||
```python
|
||
from genesis.data_models import MixedParagraph, MixedSheet
|
||
from genesis.parsers.excel_parser import ExcelParseResult
|
||
|
||
|
||
def test_excel_parse_result_has_mixed_default():
|
||
r = ExcelParseResult(file_name="f.xlsx")
|
||
assert r.mixed == []
|
||
|
||
|
||
def test_mixed_paragraph_defaults():
|
||
p = MixedParagraph(kind="table")
|
||
assert p.table is None
|
||
assert p.text is None
|
||
assert p.source_range is None
|
||
|
||
|
||
def test_mixed_sheet_holds_paragraphs():
|
||
p1 = MixedParagraph(kind="table")
|
||
p2 = MixedParagraph(kind="free_text", text="备注")
|
||
ms = MixedSheet(name="混合", paragraphs=[p1, p2])
|
||
assert ms.name == "混合"
|
||
assert [p.kind for p in ms.paragraphs] == ["table", "free_text"]
|
||
```
|
||
|
||
- [ ] **Step 2: 运行确认失败**
|
||
|
||
Run: `python -m pytest tests/test_excel_parser.py -v`
|
||
Expected: FAIL（`ImportError: cannot import name 'MixedParagraph'`）
|
||
|
||
- [ ] **Step 3: 实现（data_models.py 末尾追加）**
|
||
|
||
```python
|
||
@dataclass
|
||
class MixedParagraph:
|
||
"""混合 sheet 的一个段落（表格或自由文本）"""
|
||
kind: Literal["table", "free_text"]
|
||
matrix: list[list[Any]] | None = None # 该段原始矩阵（调试/重现）
|
||
table: ExcelTable | None = None # kind="table" 时填充
|
||
text: str | None = None # kind="free_text" 时填充（段全文）
|
||
source_range: tuple[int, int] | None = None # (first_row, last_row) 矩阵 0-based
|
||
|
||
|
||
@dataclass
|
||
class MixedSheet:
|
||
"""混合 sheet 的段落集合"""
|
||
name: str
|
||
paragraphs: list[MixedParagraph] = field(default_factory=list)
|
||
```
|
||
（`field` 已在文件顶部导入；`Literal` 需在 `from typing import Any` 处加 `Literal`）
|
||
|
||
- [ ] **Step 4: 运行确认通过**
|
||
|
||
Run: `python -m pytest tests/test_excel_parser.py -v`
|
||
Expected: PASS（新增 3 passed 全绿）
|
||
|
||
- [ ] **Step 5: 修改 ExcelParseResult（excel_parser.py）**
|
||
|
||
在 `src/genesis/parsers/excel_parser.py` 的 `ExcelParseResult` 中加字段 `mixed`：
|
||
```python
|
||
@dataclass
|
||
class ExcelParseResult:
|
||
file_name: str
|
||
tables: list[ExcelTable] = field(default_factory=list)
|
||
comments: list[CellComment] = field(default_factory=list)
|
||
skipped: list[str] = field(default_factory=list)
|
||
mixed: list[MixedSheet] = field(default_factory=list)
|
||
```
|
||
并更新导入 `from genesis.data_models import CellComment, ExcelTable, MixedSheet`。
|
||
|
||
- [ ] **Step 6: 全量回归**
|
||
|
||
Run: `python -m pytest -v`
|
||
Expected: PASS（41 + 3 = 44 passed）
|
||
|
||
- [ ] **Step 7: 提交**
|
||
|
||
```bash
|
||
git add src/genesis/data_models.py src/genesis/parsers/excel_parser.py tests/test_excel_parser.py
|
||
git commit -m "feat: data_models 扩展 MixedParagraph/MixedSheet（段落容器）"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 11: MIXED 装配（excel_parser 分段解析）
|
||
|
||
**Files:**
|
||
- Modify: `src/genesis/parsers/excel_parser.py`
|
||
- Create: 无新文件
|
||
- Test: `tests/test_excel_parser.py`（追加）
|
||
|
||
**Interfaces:**
|
||
- Consumes: `split_paragraphs`（Task9）、`MixedParagraph/MixedSheet`（Task10）、既有 `classify_sheet` / `forward_fill` / `extract_table` / `extract_text_blocks` / `build_free_text_table`、`cell_formatting` / `collect_comments`
|
||
- Produces: `ExcelParser.parse` 对 MIXED 性质产生 `result.mixed` 段落集合 + 追加表到 `result.tables`
|
||
|
||
**关键实现约定（来自 spec 3.4 修正）**：合并单元格**对整 sheet 先 forward_fill 再按段切片**，避免坐标换算错误；段内 `extract_table` 用 `header_row=0`（段首行为表头）。
|
||
|
||
- [ ] **Step 1: 写失败测试**
|
||
|
||
`tests/test_excel_parser.py` 追加（构造混合矩阵：表格段 + 空行 + 碎片段，落盘解析）：
|
||
```python
|
||
def test_parse_mixed_sheet_segmented(tmp_path):
|
||
wb = new_workbook({
|
||
"混合": [
|
||
["機能ID", "機能名"],
|
||
["F101", "社員登録"],
|
||
["F102", "退職処理"],
|
||
[],
|
||
["・改修ポイント：F102 追加バリデーション"],
|
||
["■対象画面：SC001"],
|
||
],
|
||
})
|
||
path = save_workbook(tmp_path, wb)
|
||
result = ExcelParser().parse(path)
|
||
assert result.mixed, "混合 sheet 应产产出 mixed 段落"
|
||
ms = result.mixed[0]
|
||
assert ms.name == "混合"
|
||
kinds = [p.kind for p in ms.paragraphs]
|
||
assert "table" in kinds and "free_text" in kinds
|
||
# 表格段无碎片污染：table 段应含 2 数据行，机能ID 首行为 F101
|
||
tbl = [p.table for p in ms.paragraphs if p.kind == "table"][0]
|
||
assert tbl is not None and len(tbl.rows) == 2
|
||
assert tbl.rows[0]["機能ID"].value == "F101"
|
||
# 自由文本段捕获碎片
|
||
ft = [p for p in ms.paragraphs if p.kind == "free_text"][0]
|
||
assert "改修ポイント" in (ft.text or "")
|
||
|
||
|
||
def test_parse_mixed_sheet_formatting_in_mid_segment(tmp_path):
|
||
# 表格段不在物理行 0（自由文本段在前），数据行 F101 设取消线 —— 锁住 formatting_map 坐标错位
|
||
from copy import copy
|
||
from openpyxl import Workbook
|
||
wb = Workbook()
|
||
ws = wb.active
|
||
ws.title = "混合"
|
||
data = [
|
||
["■はじめに"], ["前提説明"], [],
|
||
["機能ID", "機能名"], ["F101", "社員登録"], ["F102", "退職処理"],
|
||
[], ["・改修ポイント"],
|
||
]
|
||
for r, row in enumerate(data, start=1):
|
||
for c, v in enumerate(row, start=1):
|
||
if v:
|
||
ws.cell(row=r, column=c, value=v)
|
||
font = copy(ws.cell(row=5, column=1).font) # F101 所在物理行（第 5 行）
|
||
font.strike = True
|
||
ws.cell(row=5, column=1).font = font
|
||
path = save_workbook(tmp_path, wb)
|
||
result = ExcelParser().parse(path)
|
||
ms = result.mixed[0]
|
||
tbl = [p.table for p in ms.paragraphs if p.kind == "table"][0]
|
||
cv = tbl.rows[0]["機能ID"] # F101
|
||
assert cv.formatting is not None
|
||
assert cv.formatting.strikethrough is True
|
||
```
|
||
|
||
- [ ] **Step 2: 运行确认失败**
|
||
|
||
Run: `python -m pytest tests/test_excel_parser.py::test_parse_mixed_sheet_segmented -v`
|
||
Expected: FAIL（当前 MIXED 折叠进表格路径，`result.mixed` 为空）
|
||
|
||
- [ ] **Step 3: 实现装配分支（excel_parser.py）**
|
||
|
||
在 `parse` 的 `if nature == SheetNature.FREE_TEXT` 之后插入 MIXED 分支，或将 `nature == SheetNature.MIXED` 单独处理：
|
||
```python
|
||
if nature == SheetNature.MIXED:
|
||
# 合并单元格：整 sheet 先填充再按段切片
|
||
merged = [
|
||
(r.min_row, r.min_col, r.max_row, r.max_col)
|
||
for r in ws.merged_cells.ranges
|
||
]
|
||
filled_all = forward_fill(matrix, merged) if merged else matrix
|
||
# 整 sheet 构建格式映射一次（按物理坐标）
|
||
fmt_map = {}
|
||
for row in ws.iter_rows():
|
||
for cell in row:
|
||
fmt = cell_formatting(cell)
|
||
if fmt is not None:
|
||
fmt_map[(cell.row - 1, cell.column - 1)] = fmt
|
||
mixed_sheet = MixedSheet(name=ws.title)
|
||
for (s, e) in split_paragraphs(matrix):
|
||
seg = filled_all[s:e + 1]
|
||
seg_nature = classify_sheet(seg)
|
||
if seg_nature == SheetNature.TABLE:
|
||
header_row = find_header_row(seg)
|
||
if header_row < 0:
|
||
header_row = 0
|
||
# extract_table 的 formatting_map 用段内矩阵坐标 (r,c)；
|
||
# 从整 sheet 物理 map 抽出段内子 map（物理行 pr → 段内 pr-s）
|
||
seg_fmt_map = {}
|
||
for (pr, pc), fmt in fmt_map.items():
|
||
if s <= pr <= e:
|
||
seg_fmt_map[(pr - s, pc)] = fmt
|
||
table = extract_table(
|
||
ws.title, seg, file_name, detected_type,
|
||
header_row=header_row, formatting_map=seg_fmt_map,
|
||
)
|
||
result.tables.append(table)
|
||
mixed_sheet.paragraphs.append(MixedParagraph(
|
||
kind="table", matrix=seg, table=table,
|
||
source_range=(s, e),
|
||
))
|
||
else:
|
||
blocks = extract_text_blocks(seg)
|
||
table = build_free_text_table(ws.title, blocks, file_name, detected_type)
|
||
result.tables.append(table)
|
||
mixed_sheet.paragraphs.append(MixedParagraph(
|
||
kind="free_text", matrix=seg,
|
||
text="\n".join(blocks), source_range=(s, e),
|
||
))
|
||
result.mixed.append(mixed_sheet)
|
||
elif nature == SheetNature.FREE_TEXT:
|
||
blocks = extract_text_blocks(matrix)
|
||
result.tables.append(
|
||
build_free_text_table(ws.title, blocks, file_name, detected_type)
|
||
)
|
||
else:
|
||
# 现有 TABLE 路径（含 MIXED 旧折叠）
|
||
```
|
||
> 注：原 `else` 分支现在是 TABLE 专用；MIXED 已独立。`fmt_map` 对整 sheet 按物理坐标构建一次；表格段经 `seg_fmt_map` 抽为段内坐标后传给 `extract_table`（避免段内相对索引与物理坐标错位）。自由文本段无表格 CellValue，不使用格式化。
|
||
|
||
- [ ] **Step 4: 运行确认通过**
|
||
|
||
Run: `python -m pytest tests/test_excel_parser.py -v`
|
||
Expected: PASS（含新 MIXED 用例）
|
||
|
||
- [ ] **Step 5: 全量回归**
|
||
|
||
Run: `python -m pytest -v`
|
||
Expected: PASS（44 + 2 = 46 passed）
|
||
|
||
- [ ] **Step 6: 提交**
|
||
|
||
```bash
|
||
git add src/genesis/parsers/excel_parser.py tests/test_excel_parser.py
|
||
git commit -m "feat: MIXED 完整段落解析（分割→每段最优解析）"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 12: 混合型样本 + 端到端验证
|
||
|
||
**Files:**
|
||
- Create: `samples/要件定義_混合型.xlsx`
|
||
- Modify: `tests/test_real_samples.py`（追加用例）
|
||
|
||
**Interfaces:**
|
||
- Consumes: `ExcelParser.parse`（含 MIXED 装配）
|
||
- Produces: 混合样本（表格段 + 碎片段）端到端用例
|
||
|
||
- [ ] **Step 1: 生成样本**
|
||
|
||
用 Python 脚本生成 `samples/要件定義_混合型.xlsx`（落盘）：
|
||
```python
|
||
from openpyxl import Workbook
|
||
wb = Workbook()
|
||
ws = wb.active
|
||
ws.title = "機能一覧"
|
||
rows = [
|
||
["機能ID", "機能名", "画面ID"],
|
||
["F101", "社員登録", "SC001"],
|
||
["F102", "退職処理", "SC002"],
|
||
["F103", "給与計算", "SC003"],
|
||
[],
|
||
["・改修ポイント：F103 に年末調整バッチ連携を追加する。"],
|
||
["■対象期間：2026年度下半期"],
|
||
]
|
||
for r, row in enumerate(rows, start=1):
|
||
for c, v in enumerate(row, start=1):
|
||
if v is not None:
|
||
ws.cell(row=r, column=c, value=v)
|
||
wb.save(r"samples\要件定義_混合型.xlsx")
|
||
print("saved")
|
||
```
|
||
（实际执行时用 PowerShell 运行；「・」与「■」行**连续无空行**，`split_paragraphs` 将其合并为**一段**碎片段，返回 `[(0,3),(5,6)]` 两段：表格段 + 碎片段。）
|
||
|
||
- [ ] **Step 2: 写端到端测试**
|
||
|
||
`tests/test_real_samples.py` 追加：
|
||
```python
|
||
def test_mixed_sample_segments_detected():
|
||
p = _x("要件定義_混合型.xlsx")
|
||
if not p.exists():
|
||
pytest.skip("样本缺失")
|
||
result = ExcelParser().parse(p)
|
||
by_name = {t.name: t for t in result.tables}
|
||
assert "機能一覧" in by_name
|
||
assert result.mixed, "混合样本应产产出段落"
|
||
mixed = result.mixed[0]
|
||
assert len(mixed.paragraphs) == 2 # 表格段 + 碎片段（・/■ 连续）
|
||
assert [p.kind for p in mixed.paragraphs] == ["table", "free_text"]
|
||
# 表格段无碎片污染
|
||
table = [p.table for p in mixed.paragraphs if p.kind == "table"][0]
|
||
assert table.rows[0]["機能ID"].value == "F101"
|
||
assert len(table.rows) == 3
|
||
# 碎片段含 ・ 与 ■ 两行文本
|
||
ft = [p for p in mixed.paragraphs if p.kind == "free_text"][0]
|
||
assert "改修ポイント" in (ft.text or "")
|
||
assert "対象期間" in (ft.text or "")
|
||
```
|
||
|
||
- [ ] **Step 3: 运行端到端**
|
||
|
||
Run: `python -m pytest tests/test_real_samples.py -v`
|
||
Expected: PASS（4 passed，无 skip）
|
||
|
||
- [ ] **Step 4: 全量回归**
|
||
|
||
Run: `python -m pytest -v`
|
||
Expected: PASS（46 + 1 = 47 passed）
|
||
|
||
- [ ] **Step 5: 提交**
|
||
|
||
```bash
|
||
git add samples/要件定義_混合型.xlsx tests/test_real_samples.py
|
||
git commit -m "test: MIXED 混合样本 + 端到端段落验证"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 13: 遗留清理收尾（枚举/注释/边界/测试补齐）
|
||
|
||
**Files:**
|
||
- Modify: `src/genesis/parsers/free_text_extractor.py`（`extraction_method` 用枚举值同源）
|
||
- Modify: `src/genesis/parsers/table_extractor.py`（`extraction_method` 用枚举值同源；`header_row` 越界防御）
|
||
- Modify: `src/genesis/parsers/merge_fill.py`（`min_row` 非法值防御）
|
||
- Modify: `src/genesis/data_models.py`（`Provenance.row` 语义注释）
|
||
- Modify: `src/genesis/parsers/sheet_nature.py`（「・/■」MIXED 用例已有，不追加代码）
|
||
- Modify: `tests/test_sheet_nature.py`（补 MIXED 正向/边界用例）
|
||
- Modify: `tests/test_formatting_detector.py`（补字体色/背景色正向断言）
|
||
|
||
**Interfaces:**
|
||
- Consumes: `ExtractionMethod` 枚举（data_models）
|
||
- Produces: 一致的枚举同源与防御性实现
|
||
|
||
- [ ] **Step 1: 写失败测试（MIXED 断言 + formatting 正向）**
|
||
|
||
`tests/test_sheet_nature.py` 追加（补 MIXED 正向用例，`test_table_detection` 已覆盖 TABLE 无需重复）：
|
||
```python
|
||
def test_classify_sheet_mixed_with_bullet_line():
|
||
m = [["ID", "名前"], ["1", "田中"], ["・備考行"]]
|
||
assert classify_sheet(m) == SheetNature.MIXED
|
||
|
||
|
||
def test_classify_sheet_mixed_with_square_line():
|
||
m = [["ID", "名前"], ["1", "田中"], ["■備考行"]]
|
||
assert classify_sheet(m) == SheetNature.MIXED
|
||
```
|
||
|
||
`tests/test_table_extractor.py` 追加（锁枚举同源）：
|
||
```python
|
||
from genesis.data_models import ExtractionMethod
|
||
|
||
|
||
def test_extract_table_uses_enum_value():
|
||
matrix = [["ID"], ["1"]]
|
||
table = extract_table("社員", matrix, "f.xlsx", SheetType.FUNCTION)
|
||
assert table.extraction_method == ExtractionMethod.OPENPYXL.value
|
||
```
|
||
|
||
`tests/test_free_text_extractor.py` 追加：
|
||
```python
|
||
from genesis.data_models import ExtractionMethod
|
||
|
||
|
||
def test_free_text_uses_enum_value():
|
||
table = build_free_text_table("メモ", ["A"], "f.xlsx")
|
||
assert table.extraction_method == ExtractionMethod.LLM_FROM_FREE_TEXT.value
|
||
```
|
||
|
||
`tests/test_formatting_detector.py` 追加（复用现有 make_wb 复制字体技巧）：
|
||
```python
|
||
def test_cell_formatting_detects_font_color():
|
||
from openpyxl.styles import Font
|
||
wb = Workbook()
|
||
ws = wb.active
|
||
ws["A1"] = "x"
|
||
f = copy(ws["A1"].font)
|
||
f.color = Font(color="FF0000FF").color
|
||
ws["A1"].font = f
|
||
fmt = cell_formatting(ws["A1"])
|
||
assert fmt is not None
|
||
assert fmt.font_color is not None
|
||
```
|
||
> 注意 openpyxl 颜色格式：不硬编码具体 hex 断言，只断言 `font_color is not None`，避免格式漂移；同时确认纯默认单元格仍返回 None（已有用例覆盖）。
|
||
|
||
- [ ] **Step 2: 实现（枚举同源 + 防御）**
|
||
|
||
`free_text_extractor.py`：导入并改用：
|
||
```python
|
||
from genesis.data_models import ExtractionMethod
|
||
# build_free_text_table 中：
|
||
extraction_method=ExtractionMethod.LLM_FROM_FREE_TEXT.value,
|
||
```
|
||
`table_extractor.py`：
|
||
```python
|
||
from genesis.data_models import ExtractionMethod
|
||
# extract_table 中：
|
||
extraction_method=ExtractionMethod.OPENPYXL.value,
|
||
# 空矩阵分支同样同源
|
||
```
|
||
`table_extractor.py` 的 `header_row` 防御：
|
||
```python
|
||
if not matrix:
|
||
return ExcelTable(...)
|
||
if header_row < 0 or header_row >= len(matrix):
|
||
header_row = 0
|
||
```
|
||
`merge_fill.py` 防御非法入参（完整替换 `forward_fill`）：
|
||
```python
|
||
def forward_fill(
|
||
matrix: list[list[Any]],
|
||
merged_ranges: list[tuple[int, int, int, int]],
|
||
) -> list[list[Any]]:
|
||
"""合并单元格：用左上角主格值填充范围内全部单元格。"""
|
||
out = [list(row) for row in matrix]
|
||
for (min_row, min_col, max_row, max_col) in merged_ranges:
|
||
# 防御：合并范围 1-based，非法（<1）或越界时跳过该范围
|
||
if not out or min_row < 1 or min_col < 1:
|
||
continue
|
||
if min_row > len(out) or min_col > len(out[min_row - 1]):
|
||
continue
|
||
main_value = out[min_row - 1][min_col - 1]
|
||
for r in range(min_row, min(max_row, len(out)) + 1):
|
||
row = out[r - 1]
|
||
for c in range(min_col, min(max_col, len(row)) + 1):
|
||
row[c - 1] = main_value
|
||
return out
|
||
```
|
||
`tests/test_table_extractor.py` 追加（验证防御）：
|
||
```python
|
||
def test_forward_fill_ignores_invalid_range():
|
||
matrix = [["A"], ["B"]]
|
||
assert forward_fill(matrix, [(0, 1, 2, 1)]) == matrix # min_row=0 非法 → 不崩溃不改数据
|
||
assert forward_fill(matrix, [(9, 9, 9, 9)]) == matrix # 越界 → 不崩溃
|
||
```
|
||
|
||
`data_models.py` 注释（`Provenance.row`）：
|
||
```python
|
||
@dataclass
|
||
class Provenance:
|
||
file_name: str
|
||
sheet_name: str
|
||
row: int # 数据行号（从 1 起：表格为物理行-表头行；自由文本为块序）
|
||
column: str
|
||
column_header: str
|
||
```
|
||
|
||
- [ ] **Step 3: 运行全部新增/修改测试**
|
||
|
||
Run: `python -m pytest tests/test_sheet_nature.py tests/test_formatting_detector.py tests/test_free_text_extractor.py tests/test_table_extractor.py -v`
|
||
Expected: PASS（新增 2 MIXED + 1 formatting + 1 自由文本枚举 + 2 表提取枚举/防御 = 6 个新用例）
|
||
|
||
- [ ] **Step 4: 全量回归**
|
||
|
||
Run: `python -m pytest -v`
|
||
Expected: PASS（47 + 6 = 53 passed）
|
||
|
||
- [ ] **Step 5: 提交**
|
||
|
||
```bash
|
||
git add 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
|
||
git commit -m "fix: 遗留清理（枚举同源/边界防御/断言补强）"
|
||
```
|
||
|
||
---
|
||
|
||
## Self-Review
|
||
|
||
**1. Spec 覆盖**：§3.1→Task9、§3.3→Task10、§3.4→Task11、§3.5→Task12、§3.6/§4→Task13 + 各任务内测试。✓
|
||
**2. 占位符检查**：无 TODO/TBD；修正了拼写错误（「占位」→实际代码）。✓
|
||
**3. 类型一致性**：`split_paragraphs` 签名在 Task9 定义、Task11/12 使用一致；`MixedParagraph.kind` 用 `Literal["table","free_text"]` 一致。✓
|
||
**4. 兼容性**：Task10 只追加字段（默认值）；`ExcelParseResult` 既有消费（tests、下游）不受破坏。✓ |