SkyJourney
2c5c1bd317
新增通用 CSS 到 OOXML 翻译修复，统一字体、字距、精确行距、段落、列表、表格、引用、代码块与行内代码连续性，不引入按主题 ID 分支。 新增 MdTP Mono 并统一 Serif、Sans、Mono 三字体包的 Chromium 与 DOCX 使用链；字体声明、嵌入部件和 Word/WPS 实际采用均进入硬门禁。 重建封面整页及正文语义块视觉差分，14 套主题、纵横两个方向、五组页边距共 140 个真实场景全部通过，阻断失败和诊断失败均为零。 源码服务、Docker Web API 与实际安装 Desktop 的 red-briefing 导出均包含 5 个字体部件；Word/WPS 原生渲染和逐页复核通过。修复 Docker 构建上下文与运行层复用软链接，并完善 v0.6.1 版本、发行说明和发布归集。 验证：npm test（116 个文件、616 项测试）、npm run typecheck、npm run build、git diff --check 全部通过。Desktop 安装器与 ZIP、Docker v0.6.1 镜像已生成；Windows 产物仍为未签名内部发行。
170 lines
7.8 KiB
Markdown
170 lines
7.8 KiB
Markdown
# v0.6.1 DOCX 视觉一致性与发布门禁修复设计
|
||
|
||
状态：范围已冻结，阶段 A、B 已完成，等待阶段 C。
|
||
|
||
## 1. 版本目标
|
||
|
||
`v0.6.1` 是针对 `v0.6.0` DOCX 导出质量的维护版本，不新增与 DOCX
|
||
无关的产品功能。本版本必须完成：
|
||
|
||
1. 修复视觉报告失败但总发布门禁仍通过的判定漏洞；
|
||
2. 对四套独立封面主题建立 Chromium、Word、WPS 整页严格门禁；
|
||
3. 对 14 套内置主题建立与正文分页位置无关的语义块局部视觉门禁；
|
||
4. 修复主题样式、封面布局和字体解析、嵌入、回退问题；
|
||
5. 对源码服务、Docker Web API 和 Desktop 安装版执行发布后复验。
|
||
|
||
本版本不要求 Chromium、Word 和 WPS 的正文总页数或分页边界完全一致，
|
||
但不允许以排版引擎不同为理由放过封面、字体或语义块样式退化。
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
A["同一 Markdown、主题与配置"] --> B["生产 Chromium PDF"]
|
||
A --> C["生产 DOCX"]
|
||
C --> D["Word 原生渲染"]
|
||
C --> E["WPS 原生渲染"]
|
||
B --> F["封面整页严格比较"]
|
||
D --> F
|
||
E --> F
|
||
B --> G["正文语义块匹配"]
|
||
D --> G
|
||
E --> G
|
||
F --> H["发布硬门禁"]
|
||
G --> H
|
||
```
|
||
|
||
## 2. 问题基线
|
||
|
||
`v0.6.0` 复核确认存在以下门禁缺口：
|
||
|
||
- 视觉报告中的像素差异、墨迹 IoU、边缘 IoU 等 failure 级问题未进入
|
||
外层发布阻断集合；
|
||
- 六个布局视觉场景只覆盖五套主题，未覆盖全部 14 套主题；
|
||
- 四套独立封面只覆盖其中两套；
|
||
- “独立封面”主要检查 OOXML 分节、页眉页脚、页码重启和字段存在，
|
||
不能代表视觉一致；
|
||
- 14 主题样式门禁主要检查 CSS 槽位、令牌和 Word 样式 ID 存在，不能
|
||
代表最终 Word/WPS 呈现一致；
|
||
- 字体名称写入 `fontTable.xml`、转换无 warning，均不能证明字体已经解析、
|
||
嵌入并被 Office 实际使用；
|
||
- `red-briefing` 在门禁、Docker Web 和用户实际产物中均为零嵌入字体，
|
||
仍以零 warning 通过。
|
||
|
||
## 3. 验收模型
|
||
|
||
### 3.1 封面整页硬门禁
|
||
|
||
适用于 `formal-feasibility`、`tender-business-blue`、`tender-blind` 和
|
||
`tender-classic`：
|
||
|
||
- 封面必须独占一个物理页；
|
||
- 所有封面字段只能出现在封面页，正文不得回流到封面页；
|
||
- 封面页不显示正文页眉、页脚和页码；
|
||
- 字体、字号、字重、颜色、对齐、位置、边框、背景和装饰线必须匹配；
|
||
- 整页像素、墨迹 IoU、边缘 IoU 任一 failure 都阻断发布；
|
||
- Word 和 WPS 都必须通过，不允许只以二者相互接近替代 Chromium 基线。
|
||
|
||
### 3.2 正文语义块门禁
|
||
|
||
正文按稳定内容顺序和语义角色匹配，不按物理页号配对。允许语义块移动到
|
||
另一页，但块自身必须保持视觉一致：
|
||
|
||
| 语义块 | 必须比较 |
|
||
| --- | --- |
|
||
| 标题、正文 | 字体、字号、字重、颜色、行高、缩进、段距、对齐 |
|
||
| 引用、提示框 | 背景、边框、内边距、文字样式 |
|
||
| 代码块 | 等宽字体、字号、背景、边框、内边距、换行 |
|
||
| 列表 | 编号或项目符号、缩进、悬挂距离、文字样式 |
|
||
| 表格 | 总宽度、列宽、边框、底纹、单元格内边距、表头与文字样式 |
|
||
| 图片与图表 | 尺寸、宽高比、清晰度、对齐和题注 |
|
||
|
||
正文整页栅格差异只作为诊断，不作为最终样式结论；没有完成语义块局部比较
|
||
的主题不得标记为视觉通过。
|
||
|
||
### 3.3 字体硬门禁
|
||
|
||
- 记录 Chromium、DOCX 字体表、嵌入字体部件、Word PDF 和 WPS PDF 的
|
||
实际字体；
|
||
- 需要跨环境稳定的字体必须来自许可证允许分发的字体包；
|
||
- 应嵌入字体但字体部件为零时直接失败；
|
||
- 字体包未应用、字体回退或 Office 未使用目标字体时必须产生阻断错误；
|
||
- 字体名称存在但没有字体二进制不得视为通过。
|
||
|
||
### 3.4 发布链路门禁
|
||
|
||
同一验收输入必须覆盖：
|
||
|
||
1. 源码测试服务；
|
||
2. 正式 Docker Web API；
|
||
3. 正式 Desktop 安装版。
|
||
|
||
任一底层报告状态为 `failed` 时，总门禁必须失败。只有已经证明属于合法
|
||
正文自然分页流动的问题才能降级为 warning；封面、字体、内容、语义块
|
||
样式和媒体失败不得降级。
|
||
|
||
### 3.5 全量配置矩阵
|
||
|
||
发布门禁不是少量代表用例，而是固定执行 `14 × 2 × 5 = 140` 个排版
|
||
场景：
|
||
|
||
- 14 套内置主题；
|
||
- 纵向、横向两个纸张方向；
|
||
- 主题默认、标准、紧凑、宽松和非对称装订五组页边距。
|
||
|
||
“主题默认”必须使用 `marginMode: theme`，验证主题清单中的真实默认值；
|
||
即使解析后的数值与某组显式边距相同，也不得去重。其余四组使用显式
|
||
`custom` 配置，验证配置覆盖链路。每个场景生成 Chromium PDF、DOCX、
|
||
Word PDF 和 WPS PDF，并在报告中保留主题、方向、边距场景、导出链和
|
||
渲染引擎维度，不允许用汇总绿灯掩盖单个失败。
|
||
|
||
场景 ID 固定为 `<theme-id>--<orientation>--<margin-scenario>`。总报告同时
|
||
输出机器可读 JSON 和 14 行 × 10 列 HTML 矩阵；每个单元格必须显示通过、
|
||
失败或未执行，并链接到 Chromium/Word、Chromium/WPS、Word/WPS 三份
|
||
详细报告。完整门禁必须执行 140 个场景后才允许标记 `complete: true`；
|
||
单场景筛选只用于开发复现，不能冒充全矩阵结果。
|
||
|
||
## 4. 实施阶段
|
||
|
||
1. 阶段 A：修复 failure 聚合策略，补齐四套封面场景和封面正文隔离；
|
||
2. 阶段 B：建立跨页无关的语义块观察、匹配、局部栅格和样式比较协议；
|
||
3. 阶段 C：建立 14 主题、2 个方向、5 组页边距的 140 场景全量语义块
|
||
矩阵和版本化门限；
|
||
4. 阶段 D：逐主题修复封面、正文块样式和字体嵌入；
|
||
5. 阶段 E：完成源码、Docker Web、Desktop 安装版发布后复验；
|
||
6. 阶段 F：更新版本、发行说明、发布产物、发布提交和 annotated tag。
|
||
|
||
每个阶段必须先提交真实失败基线，再修复到通过。不得通过删除用例、提高
|
||
门限、过滤 failure 或把 failure 改名为 warning 取得绿灯。
|
||
|
||
## 5. v0.6.1 发布条件
|
||
|
||
- 14 套主题在纵向、横向和五组页边距下全部生成真实 Chromium PDF、
|
||
DOCX、Word PDF 和 WPS PDF；
|
||
- 四套独立封面全部通过整页严格门禁；
|
||
- 14 套主题声明支持的语义块全部通过局部视觉门禁；
|
||
- 字体解析、嵌入和实际使用结果符合主题预期；
|
||
- 源码、Docker Web 和 Desktop 安装版结果一致；
|
||
- 单元测试、类型检查、生产构建和 `git diff --check` 通过；
|
||
- 发布报告中不存在被忽略的 failure；
|
||
- 完成真实 Word/WPS 逐页人工复核后才能发布。
|
||
|
||
## 6. 最终验收结果
|
||
|
||
2026-08-04 已完成全部发布条件：
|
||
|
||
- `14 × 2 × 5 = 140` 个场景全部实际执行，矩阵报告为
|
||
`complete: true`、`gatePassed: true`，阻断失败和诊断失败均为 0；
|
||
- 四套独立封面共 40 个方向/边距组合全部通过 Chromium 对 Word/WPS
|
||
整页严格门禁；其余页面按跨页无关的语义块完成视觉比较；
|
||
- 通用 CSS 到 OOXML 翻译已覆盖字体、字距、精确行距、段落、列表、表格、
|
||
引用、代码和行内代码连续性，全程未增加按主题 ID 分支；
|
||
- Serif、Sans、Mono 三套可分发字体进入同一字体包解析链，140 个场景的
|
||
DOCX 均包含 5 个字体部件，Word/WPS 实际字体使用门禁通过；
|
||
- `red-briefing` 已分别从源码服务、正式 Docker Web API 和实际安装的
|
||
Desktop 导出；三份 DOCX 均约 24.17 MB、含 5 个字体部件，并通过真实
|
||
Word/WPS 渲染复核；
|
||
- 根级测试、类型检查、生产构建和空白检查通过；Docker 镜像、Desktop
|
||
安装器及免安装 ZIP 已生成。
|
||
|
||
最终矩阵报告位于 `output/docx-layout-visual-matrix/summary.json`，发行说明
|
||
见 [`docs/releases/v0.6.1.md`](releases/v0.6.1.md)。
|