348 lines
16 KiB
Markdown
348 lines
16 KiB
Markdown
# v0.6.0 DOCX 全主题视觉与结构审计
|
||
|
||
审计日期：2026-07-30
|
||
|
||
> 本文第 3～8 节记录阶段 10 的首轮审计基线。阶段 12C 已于
|
||
> 2026-07-31 完成对应结构修复和自动化门禁，最新状态见第 9 节；真实
|
||
> Word/WPS 视觉、编辑和互存结论仍需阶段 12D 复验。
|
||
|
||
## 1. 审计目标
|
||
|
||
本轮按 v0.6.0 已冻结的两条 DOCX 发布门禁检查全部内置主题：
|
||
|
||
1. 导出的 DOCX 必须保留完整纸张设置与文本样式，包括字体、段落、标题、
|
||
列表、代码块、表格、图片、Mermaid、ECharts、封面和结构化公文元素。
|
||
2. 导出的 DOCX 必须能被 Microsoft Word 与 WPS 正常打开、编辑和互存。
|
||
|
||
项目实际包含 14 套内置主题，而不是此前口头统计的 13 套。本轮没有只做
|
||
OOXML 自动检查，还使用本机 Microsoft Word 原生排版引擎逐份导出 PDF，
|
||
并检查全部 22 个渲染页面。
|
||
|
||
## 2. 审计方法与证据
|
||
|
||
- 使用 Pandoc `3.9.0.2` 和当前动态 `reference.docx` 生成 14 份 DOCX。
|
||
- 使用每套主题自己的 `samples/themes/<theme-id>.md` 和导出配置。
|
||
- 检查 DOCX 包结构、纸张尺寸、四边页边距、样式、表格、图片关系、
|
||
页眉页脚、页码字段、分页符和 `altChunk`。
|
||
- 使用 Microsoft Word 原生 COM 导出 14 份 PDF，共 22 页。
|
||
- 将 Word PDF 以 150 DPI 栅格化，逐页按原始分辨率检查。
|
||
- 从 Word PDF 提取实际使用字体，排查字体替换。
|
||
- 检查 Front Matter 结构字段是否真正进入可编辑 Word 正文。
|
||
|
||
可复现命令：
|
||
|
||
```powershell
|
||
npm run verify:docx-themes
|
||
```
|
||
|
||
本地审计产物位于：
|
||
|
||
```text
|
||
output/docx-theme-matrix/
|
||
├── *.docx
|
||
├── theme-matrix-report.json
|
||
├── word-pdf-isolated/
|
||
└── word-png/
|
||
```
|
||
|
||
`output/` 已被 Git 忽略，审计产物不会进入仓库。
|
||
|
||
## 3. 总体结论
|
||
|
||
当前实现通过了“原生可编辑 DOCX”基础能力，但没有通过“完整主题样式映射”
|
||
发布门禁。
|
||
|
||
| 检查项 | 结果 | 结论 |
|
||
| --- | ---: | --- |
|
||
| Word 可打开并原生排版 | 14/14 | 通过 |
|
||
| 正文、标题、列表、表格和代码为原生 OOXML | 14/14 | 通过 |
|
||
| 禁止 `altChunk` | 14/14 | 通过 |
|
||
| A4、方向和四边页边距符合主题配置 | 14/14 | 通过 |
|
||
| 页眉页脚和页码为 Word 原生区域/字段 | 14/14 | 通过 |
|
||
| 本机字体无异常替换 | 14/14 | 通过 |
|
||
| 独立封面完整生成 | 0/4 | 阻塞 |
|
||
| 结构化公文/简报 Front Matter 完整映射 | 0/4 | 阻塞 |
|
||
| 主题视觉完整映射 | 0/14 | 阻塞 |
|
||
| 全宽表格 | 0/14 个含表格主题 | 阻塞 |
|
||
| 无重复标题 | 8/14 | 需修复 |
|
||
|
||
因此，本轮结论不是 Node.js 或 Pandoc 路线不可行，而是当前
|
||
`reference.docx + 原始 Markdown 直送 Pandoc` 的实现层级不足。Pandoc
|
||
仍适合作为可编辑 OOXML 的底座，但必须增加项目自有的结构化 AST 转换、
|
||
分节和主题专属 Word 样式映射，不能期待 Pandoc 自动理解浏览器主题 CSS
|
||
与项目 Front Matter。
|
||
|
||
## 4. 关键阻塞问题
|
||
|
||
### 4.1 结构化 Front Matter 没有进入 Word 正文
|
||
|
||
浏览器预览通过 `render-document-structure.ts` 将 `document.profile` 转成
|
||
红头、文号、签发人、版记、封面等结构；DOCX 转换当前将原始 Markdown
|
||
直接交给 Pandoc，两条链路没有复用同一份结构化文档模型。
|
||
|
||
| 主题 | Profile | 结构字段覆盖率 | 主要缺失 |
|
||
| --- | --- | ---: | --- |
|
||
| enterprise-red-simple | official | 14% | 文号、签发人、日期、抄送、印发机关 |
|
||
| gov-red-letter | official | 17% | 文号、日期、抄送、印发机关 |
|
||
| gov-red-standard | official | 22% | 文号、紧急程度、签发人、日期、抄送、版记 |
|
||
| red-briefing | briefing | 17% | 期号、编发单位、日期、联系方式等 |
|
||
| formal-feasibility | project-report | 33% | 项目名、建设单位、版本、日期和独立封面 |
|
||
| tender-blind | tender | 20% | 正副本、项目名、编号、分册、投标人等封面字段 |
|
||
| tender-business-blue | tender | 14% | 正副本、项目名、编号、分册、代表、日期 |
|
||
| tender-classic | tender | 14% | 正副本、项目名、编号、分册、代表、日期 |
|
||
|
||
四套声明独立封面的主题均没有生成封面，也没有显式分页符或分节：
|
||
|
||
- `formal-feasibility`
|
||
- `tender-blind`
|
||
- `tender-business-blue`
|
||
- `tender-classic`
|
||
|
||
### 4.2 14 套主题实际收敛成少量通用 Word 预设
|
||
|
||
当前 DOCX 样式主要来自 `official`、`formal`、`tender`、`technical` 和
|
||
`general` 几个预设。多个网页视觉差异明显的主题，在 DOCX 中使用完全相同
|
||
或近似的正文、标题和表格样式。
|
||
|
||
- `formal-regulation` 与 `formal-report` 基本相同。
|
||
- `typora-github` 与 `typora-like` 基本相同。
|
||
- `typora-pixyll` 与 `typora-whitey` 基本相同。
|
||
- 三套红头公文正文样式基本相同，但没有各自红头版式结构。
|
||
- 三套标书共用蓝色系表格预设，破坏暗标和经典黑白主题语义。
|
||
|
||
这说明当前是“按主题选择一个通用 Word 模板”，尚不是“完整映射每套主题”。
|
||
|
||
### 4.3 标题重复
|
||
|
||
以下 6 套样例的 YAML `title` 与正文第一个 H1 相同。Pandoc 同时输出文档
|
||
标题块和 H1，Word 中出现重复标题：
|
||
|
||
- `formal-regulation`
|
||
- `formal-report`
|
||
- `typora-github`
|
||
- `typora-like`
|
||
- `typora-pixyll`
|
||
- `typora-whitey`
|
||
|
||
此外，文档标题当前基于 H1 再增加 4pt，实际约 26pt；在红头信函中产生
|
||
过大的标题和不自然换行，例如“函”被孤立到第二行。
|
||
|
||
### 4.4 表格没有继承网页主题的全宽布局
|
||
|
||
Pandoc 生成的表格宽度是：
|
||
|
||
```xml
|
||
<w:tblW w:type="auto" w:w="0"/>
|
||
```
|
||
|
||
Word 会按内容自动收缩，导致所有表格明显窄于正文内容区。网页主题中的
|
||
`width: 100%`、列宽和部分表头视觉没有被映射到 Word 表格网格。
|
||
|
||
### 4.5 分页质量不足
|
||
|
||
当前 14 份文档均没有显式分页符。Word 只能根据通用段落属性自动分页，
|
||
出现以下问题：
|
||
|
||
- `typora-like` 第 2 页只剩最后一行审核人信息，属于严重孤行页。
|
||
- `formal-feasibility`、`formal-regulation`、`formal-report` 和
|
||
`tender-blind` 的末页内容很少，下半页大面积空白。
|
||
- 代码块可以跨页，但没有专门的代码块续排或避免不佳断点策略。
|
||
- 封面与正文无法通过 Word 分节控制首页页眉页脚、起始页码和封面不计页码。
|
||
|
||
### 4.6 字体在本机正确，但没有嵌入
|
||
|
||
Word 实际导出的 PDF 中可见字体符合当前样式意图：
|
||
|
||
- 公文、正式报告和标书主要使用 `SimSun`、`SimHei`、
|
||
`Times New Roman`、`Arial`。
|
||
- 技术主题主要使用 `Microsoft YaHei`、`Arial`、`Consolas`。
|
||
|
||
但 14 份 DOCX 均没有嵌入字体文件，也没有嵌入字体引用。这意味着：
|
||
|
||
- 在本机和安装了相同字体的公司电脑上表现稳定。
|
||
- 在缺少宋体、黑体、微软雅黑或对应英文字体的环境中，Word/WPS 会替换字体，
|
||
进而改变换行、页数和视觉。
|
||
- 默认嵌入字体会显著增大文件，并涉及字体再分发许可，不适合作为默认策略。
|
||
|
||
建议明确“受支持字体清单 + fallback”，并在 Desktop/Docker 安装或内置
|
||
所需可分发字体；除非业务明确要求，不默认嵌入字体到每份 DOCX。
|
||
|
||
## 5. 逐主题视觉结论
|
||
|
||
| 主题 | Word 页数 | 主要视觉与结构问题 | 门禁结论 |
|
||
| --- | ---: | --- | --- |
|
||
| enterprise-red-simple | 1 | 无企业红头、文号、签发和版记；呈现为通用 Word 文档；表格偏窄 | 阻塞 |
|
||
| formal-feasibility | 2 | 无独立封面；项目、建设单位、版本等封面字段缺失；末页留白大 | 阻塞 |
|
||
| formal-regulation | 2 | 标题重复；视觉为通用蓝灰报告；表格偏窄；末页留白大 | 阻塞 |
|
||
| formal-report | 2 | 标题重复；主题区分度弱；末页只有少量内容 | 阻塞 |
|
||
| gov-red-letter | 2 | 无红头、文号、落款和版记；超大标题换行不佳；第 2 页外侧公文页码正确 | 阻塞 |
|
||
| gov-red-standard | 2 | 无红头、文号、紧急程度、签发和版记；奇偶外侧公文页码正确 | 阻塞 |
|
||
| red-briefing | 1 | 无简报报头、期号、编发单位和联系信息；正文段落间视觉空隙偏大 | 阻塞 |
|
||
| tender-blind | 2 | 无封面；标题和表头为蓝色，违反技术暗标黑白要求；末页留白大 | 阻塞 |
|
||
| tender-business-blue | 1 | 无封面；蓝色体系基本协调，但仍是通用标书模板；表格偏窄 | 阻塞 |
|
||
| tender-classic | 1 | 无封面；标题过大；表头仍为浅蓝色，违反经典黑白语义 | 阻塞 |
|
||
| typora-github | 2 | 标题重复；代码样式可用；表格偏窄；审计占位图黑块不计入产品缺陷 | 需修复 |
|
||
| typora-like | 2 | 标题重复；正文、引用和代码基本可用；第 2 页仅一行，孤行严重 | 阻塞 |
|
||
| typora-pixyll | 1 | 标题重复；整体可用，但与 Whitey 的 Word 风格区分不足；表格偏窄 | 需修复 |
|
||
| typora-whitey | 1 | 标题重复；整体可用，但主题专属字体和细节映射不足；表格偏窄 | 需修复 |
|
||
|
||
`typora-github` 审计图中的大黑块来自矩阵脚本使用 1×1 像素占位 PNG 后按
|
||
计划尺寸拉伸，只用于验证图片关系和 Word 尺寸，不代表真实 Mermaid 导出。
|
||
真实 Mermaid/ECharts PNG 管线已经在独立验收样例中验证，正式全主题回归
|
||
仍应改用真实捕获媒体，避免视觉报告产生歧义。
|
||
|
||
## 6. 已确认正常的能力
|
||
|
||
- DOCX 是标准 OOXML，而不是 HTML 或 PDF 嵌套。
|
||
- 正文、标题、列表、表格、代码和链接可在 Word 中继续编辑。
|
||
- A4 尺寸、方向和主题声明的四边页边距正确。
|
||
- 页眉页脚位于 Word 原生页眉区/页脚区，不再以正文表格模拟。
|
||
- 页码使用 `PAGE`/`NUMPAGES` 字段。
|
||
- `gov-red-letter` 首页不显示页码，第 2 页显示外侧 `— 2 —`。
|
||
- `gov-red-standard` 奇偶页外侧公文页码正确。
|
||
- 视觉上较淡的 `tender-classic` 和 `typora-whitey` 页码经 PDF 文本提取
|
||
确认存在，不是字段丢失。
|
||
- 所有 DOCX 均未发现 `altChunk`，可编辑性基础路线正确。
|
||
|
||
## 7. 建议修复顺序
|
||
|
||
### P0：建立统一的结构化 DOCX 文档模型
|
||
|
||
在进入 Pandoc 前，将 Markdown AST、Front Matter 和主题结构合成为统一
|
||
中间模型，再输出 Pandoc AST 或通过项目 Lua Filter 注入原生 Word 段落、
|
||
表格、分页符和分节信息。公文、简报、项目报告和标书封面不能依赖
|
||
`reference.docx` 自动生成。
|
||
|
||
### P0：实现封面与分节
|
||
|
||
- 封面使用原生段落和可编辑文字。
|
||
- 封面结束后插入 Word 分节符。
|
||
- 支持封面无页眉页脚、封面不计页码、正文从 1 开始。
|
||
- 公文首页、奇偶页脚继续使用 Word 原生节属性。
|
||
|
||
### P0：扩展主题 DOCX 清单
|
||
|
||
为主题增加可显式覆盖的 Word 语义样式，而不是只选择通用预设：
|
||
|
||
- 文档标题、作者和元数据块；
|
||
- 红头、文号、签发人、落款、抄送和版记；
|
||
- 封面项目名、分册、正副本和日期；
|
||
- H1～H6、正文、列表、引用、代码、图注；
|
||
- 表格宽度、列宽、表头、边框和底色；
|
||
- 段前段后、孤行控制、标题与下一段同页。
|
||
|
||
### P1：修复通用排版问题
|
||
|
||
- 对 YAML 标题与首个 H1 去重。
|
||
- 表格按内容区宽度生成 `pct=5000` 或明确网格宽度。
|
||
- 为标题设置 `keepNext`，为正文设置 widow/orphan 控制。
|
||
- 收敛过大的 26pt 文档标题，并按主题单独配置。
|
||
- 暗标和经典黑白主题禁止蓝色标题、表头和装饰。
|
||
|
||
### P1：完善字体可复现策略
|
||
|
||
- 固化每套主题的首选字体和 fallback。
|
||
- 在发布说明中列出 Word/WPS 目标环境所需字体。
|
||
- 仅使用许可证允许随应用分发的字体作为可选内置字体。
|
||
- 增加“字体不可用”诊断，不默认把字体嵌入每份 DOCX。
|
||
|
||
### P2：升级全主题回归门禁
|
||
|
||
- 使用真实 Mermaid、ECharts 和普通图片，不再使用纯色占位图做视觉验收。
|
||
- 自动检测标题重复、表格内容区占比、孤行页和封面分节。
|
||
- Word 与 WPS 各完成一次打开、编辑、保存、重开。
|
||
- 保存后再次校验页数、字体、页眉页脚、字段和原生结构。
|
||
|
||
## 8. 阶段判定
|
||
|
||
当前 DOCX 引擎可以认定为：
|
||
|
||
> Pandoc 路线与 Node.js 编排可行，原生可编辑基础链路成立；但完整主题
|
||
> 映射、结构化公文、封面、表格宽度和分页控制尚未达到 v0.6.0 发布门禁。
|
||
|
||
在完成 P0 项目前，不建议将阶段 10 标记为通过，也不建议创建 v0.6.0
|
||
正式发布提交或版本标签。
|
||
|
||
## 9. 阶段 12C 自动修复复验
|
||
|
||
阶段 12C 保留 Pandoc 作为可编辑 OOXML 底座，并增加项目自有的通用转换
|
||
层：统一语义文档模型生成结构计划，Lua Filter 注入可编辑段落与样式，
|
||
最终 OOXML 收口层写入真实分节、页码重启、表格宽度和分页属性。映射只
|
||
依赖语义角色与主题令牌，不包含主题 ID 分支，因此同一机制也可服务未来
|
||
外部主题。
|
||
|
||
2026-07-31 使用 Playwright Chromium 151 重新采集 14 套主题各 56 个
|
||
计算样式槽位，并由 Pandoc 3.9.0.2 重新生成全部 DOCX，自动结构结果如下：
|
||
|
||
| 检查项 | 阶段 12C 结果 | 结论 |
|
||
| --- | ---: | --- |
|
||
| 主题使用本轮真实 Chromium 令牌 | 14/14 | 通过 |
|
||
| 结构化主题字段完整映射 | 8/8 | 通过 |
|
||
| 项目报告与标书独立封面真实分节 | 4/4 | 通过 |
|
||
| 封面隐藏页眉页脚、正文页码从 1 重启 | 4/4 | 通过 |
|
||
| 封面文档使用 `SECTIONPAGES` | 4/4 | 通过 |
|
||
| 含表格主题的表格铺满内容区 | 11/11 | 通过 |
|
||
| YAML 标题与正文首个 H1 去重 | 14/14 | 通过 |
|
||
| 内部结构标记清理 | 14/14 | 通过 |
|
||
| 禁止 `altChunk`、保留原生可编辑结构 | 14/14 | 通过 |
|
||
|
||
统一复现命令仍为：
|
||
|
||
```powershell
|
||
npm run verify:docx-themes
|
||
```
|
||
|
||
该命令不会回退到合成令牌或陈旧快照。它先生成本轮 Chromium 令牌，再
|
||
执行 14 主题 Pandoc 矩阵和硬断言。阶段 10 的 P0/P1 结构阻塞因此已由
|
||
自动门禁关闭；“完整主题样式映射”的最终判定仍保留到阶段 12D，必须在
|
||
Microsoft Word 与 WPS 中完成视觉检查、编辑、保存、重开和双向互存后
|
||
才能通过。
|
||
|
||
## 10. 阶段 12C-R1 OOXML 严格性复验
|
||
|
||
2026-07-31 对阶段 12C 生成的 14 份 DOCX 做 Microsoft Word 原生打开
|
||
时，最初仅 7 份可直接打开，另外 7 份触发“发现无法读取的内容”且无法
|
||
恢复。WPS 可以容错打开，但会报告缺失字体，因此不能据此判定 OOXML
|
||
合格。
|
||
|
||
深度审计确认根因集中在生成样式与 OOXML 模式约束：
|
||
|
||
- Pandoc 消费 `custom-style` 后会追加同名降级样式，造成重复
|
||
`w:styleId`；
|
||
- CSS `text-align: justify` 被直接写成非法的 `w:jc="justify"`，正确
|
||
WordprocessingML 枚举应为 `both`；
|
||
- 表格条件样式中的 `w:rPr` 与 `w:tcPr` 顺序不符合模式；
|
||
- `w:tblW` 被写入表格样式层，和正文表格的直接宽度属性混在一起；
|
||
- 多类段落、文本、表格、单元格和分节属性缺少统一的有序写入门禁。
|
||
|
||
通用引擎已经增加有序插入、序列化规范化和严格校验，并在最终 DOCX
|
||
收口层保留前置主题样式、移除 Pandoc 同名降级样式。修复不按主题 ID
|
||
分支，也不改变正文表格的内容区全宽属性。
|
||
|
||
复验结果：
|
||
|
||
| 检查项 | 结果 | 结论 |
|
||
| --- | ---: | --- |
|
||
| 14 主题结构矩阵 | 14/14 | 通过 |
|
||
| Microsoft Open XML SDK 非兼容性错误 | 0 | 通过 |
|
||
| Microsoft Word 禁止修复打开 | 14/14 | 通过 |
|
||
| WPS 原生只读打开 | 14/14 | 通过 |
|
||
| Word 原生 PDF 导出 | 14/14，共 31 页 | 通过 |
|
||
| 31 页逐页结构检查 | 31/31 | 通过 |
|
||
|
||
Open XML SDK 2.20 仍会按 Office 2007 模式报告 Pandoc 表格上的 Office
|
||
2010 `tblLook` 六个兼容属性；这些属性在本轮 Word/WPS 实测中正常，不计
|
||
为生成错误。
|
||
|
||
逐页检查没有发现内容丢失、裁切、重叠或空白正文，但保留以下阶段 12D
|
||
视觉问题：
|
||
|
||
- 深色表头文字对比度不足；
|
||
- 部分短文档尾页留白过大；
|
||
- `gov-red-standard` 在 Word 与 WPS 中分别为 2 页和 3 页，说明字体与
|
||
客户端排版差异尚未收口；
|
||
- 当前主题矩阵的 Mermaid 仍使用黑色占位 PNG，不代表真实媒体效果。
|
||
|
||
因此 R1 只关闭 OOXML 合法性和 Word/WPS 无修复打开门禁。字体可移植性、
|
||
PDF 与 DOCX 自动视觉差异、真实媒体和双向编辑互存继续由 R2～R4 验收。
|