# Quarto docx 滤镜验收测试指引

**配对资产**：`lua/*.lua`（网站四个滤镜，或 book 剖面另加编号与横向页）+ `template/reference-doc.docx`（含「表题」「图题」样式）

本指引以 [`scripts/quarto-docx/test/`](.) 为根目录。通用验证工作流见 [`docs/harness-asset-validation-workflow.qmd`](../../../docs/harness-asset-validation-workflow.qmd)。

---

## 1. 测试目标

| 层级 | 验证内容 |
|------|----------|
| **可复用性** | `Install-Harness.ps1 -InstallProfile quarto-docx` / `quarto-docx-book` 复制路径与 YAML 片段与沙盒一致 |
| **效果再现** | 渲出 docx：网站用 `verify_docx.py`，book 用 `verify_book.py`；列宽/字号可目视 |
| **回归** | Quarto 升级或 Lua 改动后重跑 `run-check-all.ps1`（或 `.sh`；含 L0 + L1 + BOOK） |

### 1.1 用例矩阵（mod-acceptance · 网站剖面）

| ID | 验收项 | 自动化 |
|----|--------|--------|
| TC-XREF | 正文「见图2-N」无多余空格；题注无 `图2-`+nbsp | `verify_docx.py`（抽 `w:t` 拼纯文本） |
| TC-FIG | 图题 `pStyle=TuTi` 且**不在** `w:tbl` 内 | `verify_docx.py` |
| TC-TBL | 表题 `pStyle=BiaoTi` 且**不在** `w:tbl` 内；含「年份」「2024」 | `verify_docx.py` |
| TC-BR | 图题/表题段落内有 `w:br` | `verify_docx.py` |
| TC-CALLOUT | 「专栏标题」仍在某张 `w:tbl` 内（未被拆壳） | `verify_docx.py` |
| 目视 | 居中、五号表头、短列不折行 | Word 打开 docx（可选；**不**由脚本保证） |

### 1.2 用例矩阵（test/book · book 剖面）

| ID | 验收项 | 自动化 |
|----|--------|--------|
| TC-BOOK-NUM | 正文出现 `见图N-M`，无点分 `图 N.M` | `verify_book.py` |
| TC-LAND | 恰一处 `w:orient="landscape"`；无空 `<w:sectPr/>` | `verify_book.py` |
| TC-LAND 顺序 | 纵向关 → 注/资料来源 → 横向关（默认 footer `rId14`） | `verify_book.py` |
| TC-CAP | `TuTi` / `BiaoTi` 均在表外 | `verify_book.py` |
| TC-TBL / TC-NOTE | 含「年份」「2024」；无裸 TeX `\U2460` | `verify_book.py` |
| 目视 | 横向页页脚与纸型 | Word 打开 `book/output/*.docx`（可选） |

不要把网站 `verify_docx.py` 套到 book 产物上：网站断言假定前缀 `图2-` 与 callout 仍为表。

---

## 2. 三层测试（L0 / L1 / BOOK / L2）

| 层级 | 工具 | 说明 |
|------|------|------|
| **L0** | `run-check-all.ps1` / `.sh` 内 pandoc + `linebreak.lua` | 纯 AST：`<br>` → `LineBreak` |
| **L1** | `run-module.ps1 -Module mod-acceptance` | 独立进程 render docx/html + `verify_docx.py`（网站前缀） |
| **BOOK** | `run-book.ps1` | `test/book/` 渲染 docx + `verify_book.py`（`图N-M`、一页横向、无空分节符） |
| **L2** | 同 `run-check-all`（当前 = L0+L1+BOOK） | 未来可加负向模块（缺滤镜 / 错顺序 / 两编号滤镜叠挂） |

交叉引用与 caption 拆壳**必须**经 Quarto `post-render` 阶段，故无独立 L0；集成验收在 L1 / BOOK。改过 canonical `lua/` 后先 `sync-mirror.ps1`。

---

## 3. 目录结构

```text
scripts/quarto-docx/test/
├── modules/
│   └── mod-acceptance.qmd      # 网站验收样例
├── book/                       # book 剖面小书（图N-M + landscape）
│   ├── _quarto.yml
│   ├── index.qmd / ch01.qmd
│   └── output/                 # gitignore
├── lua/                        # canonical 镜像
├── template/reference-doc.docx
├── scripts/
│   ├── run-module.ps1 / .sh
│   ├── run-book.ps1 / .sh
│   ├── run-check-all.ps1 / .sh
│   ├── sync-mirror.ps1 / .sh
│   ├── verify_docx.py
│   └── verify_book.py
├── assets/demo.png
├── output/                     # gitignore
└── quarto-docx-test-guide.md
```

---

## 4. 环境

| 项 | 要求 |
|----|------|
| Quarto | **1.8+**。文档记载验证于 **1.8.26**；**1.10.18** 于 2026-09-29 复测网站 L0/L1；**2026-10-15** 同版本 `run-check-all.ps1` 再测（含 BOOK；列宽/五号表头未做 Word 目视）。Cloud 可用 1.9.x 冒烟 |
| Python | 3.x（`verify_docx.py` / `verify_book.py`；Windows 优先 `py -3`） |
| R | **非必须**（样例 `execute: false`，静态表/图） |
| 本机 | Windows 11 用 **PowerShell** 脚本；Linux/Cloud 用 bash |

记录版本：`quarto --version`；写入本地 `TEST-LOG.md`。

---

## 5. 与 templates/ 的关系

- **`test/`**：标准验收沙盒 + 结构断言（维护者晋升前必跑）。**不是** `templates/` 里的微型业务项目。
- **`templates/quarto-docx-demo/`**（规划）：面向外部读者的「如何装进业务仓」微型示例；可链到本沙盒作为效果参照。

验证沙盒**不**通过 `Install-Harness.ps1` 分发。