# 《文档排版》测试报告

> 文档编号：TEST-RPT-007
> 日期：2026-06-12
> 被测：内容与样式分离文档排版子系统（[DESIGN-ARCH-023] / [IMPL-RPT-023]）
> 运行环境：jest（默认框架），python 3 + python-docx 1.2.0
> 结论：**4 suites / 60 cases 全绿**，含 python-docx 端到端渲染断言

---

## 1. 如何运行

```bash
# 在 services/backend 下（jest 在仓库根 node_modules）
../../node_modules/.bin/jest --rootDir . \
  tests/services/typeset tests/tools/renderDocument.test.js
```

端到端用例在**检测不到 python-docx 时自动 skip**（`describe.skip`），单测部分（防呆/解析/
模板/工具契约）无 python 依赖恒可跑。

---

## 2. 测试矩阵

| 测试文件 | 用例数 | 覆盖维度 |
|----------|:---:|----------|
| `tests/services/typeset/contentSchema.test.js` | 26 | 块文法结构校验；防呆拦截 LaTeX 命令/宏、HTML/XML（含 docx `w:` 标签）、内联 CSS、RTF；`a < b` 不等式不误判；code 块正文豁免 |
| `tests/services/typeset/markdownToAst.test.js` | 15 | 标题/段落/列表/引文/代码/表格解析；`[[newpage]]` 与 `<<<pagebreak>>>` 换页；水平线与空行**不**换页；`**bold**`/`*italic*`→语义 run |
| `tests/services/typeset/styleTemplates.test.js` | 9 | 三模板发现；gbt7714 国标签名；未知模板报错列内置；内联/部分模板继承 default 完整基线；overrides 深合并；`_deepMerge` 语义 |
| `tests/tools/renderDocument.test.js` | 10 | 工具契约（name/category/isReadOnly/aliases/schema）；输入闸门（空内容/缺路径/防呆拒 LaTeX·HTML/未知模板列可选/路径封禁拒写 `/etc`）；**端到端**渲染真 .docx 反解断言 |
| **合计** | **60** | |

---

## 3. 关键断言：核心诉求与防呆逐条对应

| 诉求 / 防呆 | 对应用例 | 断言 |
|---|---|---|
| ①模型只管语义 | `防呆: a LaTeX command … rejected`、`… an HTML tag … rejected` | 夹带排版代码 → `success:false`，渲染前即拒 |
| ②模板驱动 | `gbt7714 carries its 国标 signatures`、`overrides deep-merge …` | 格式来自模板键值；覆盖深合并不重述基线 |
| ③原子化排版 | 端到端 `renders a real .docx …` | 模型只给 Markdown+模板名，排版由程序落地 |
| 防呆①拦截排版代码 | contentSchema 11 条 `scanFormatCodes flags …` + 3 条 `validateDocument rejects …` | LaTeX/HTML/CSS/RTF 全拦；code 块正文豁免 |
| 防呆②中文 eastAsia | 端到端反解探针 | **每个有文本的中文 run 的 eastAsia 全覆盖：`missing_eastAsia=0`** |
| 防呆③换页确定性 | `[[newpage]] … pagebreak`、`horizontal rule is NOT a page break`、`blank lines never create a page break` | 换页只来自哨兵/结构块；空行、`---` 绝不换页 |

---

## 4. 端到端证据（python-docx 在位时）

用例 `renders a real .docx and verifies A4 + applied formatting`（256ms）输入一篇含
标题/正文强调/列表/`[[newpage]]`/表格的 Markdown，模板 `gbt7714`，渲染后：

1. 工具返回 `success:true`、`template:"builtin:gbt7714"`、`validation.pageSizeA4:true`、
   `validation.headingSizeOk:true`。
2. 再用独立 python-docx 探针**反向解析**产物 .docx：
   - `abs(page_width - 210mm) < 1mm` 且 `abs(page_height - 297mm) < 1mm` → A4 ✓
   - 段落文本含"引言"(H1) 与"方法"(H2) ✓
   - 遍历所有 run，统计漏设 `w:eastAsia` 的有文本 run 数 → **0** ✓
   - 输出 `OK missing_eastAsia=0 sections=1`

这证明写后校验+打补丁闭环真实生效（首次渲染时页脚页码域的 1 个 run 漏 eastAsia，被
`_verify_and_patch` 捕获并补丁——见 `validation.patched`）。

---

## 5. 回归

- 禁令单一真源：`node --test tests/agentConstraints.test.js` → 6/6，新增红线未破坏体例。
- 边界守恒：未改 `createDocument`/核心调度器/无关业务，相关既有套件不在本次改动面内。

---

## 6. 结论

文档排版子系统的语义层、样式层、渲染层、工具入口与写后校验闭环**全部通过验证**，
核心诉求三项与防呆四条均有对应绿色断言背书。可投入使用。
