feat: 实现 Pandoc DOCX 转换服务

2026-07-30 15:05:50 +08:00
parent fa159d916f
commit bf43433d38
32 changed files with 2908 additions and 61 deletions
@@ -3,7 +3,9 @@
 纯 Node.js 的 DOCX 模板和 Pandoc 编排核心。当前阶段负责读取固定 Pandoc
 版本的默认 `reference.docx`、验证 ZIP 安全边界，将主题 DOCX 样式声明
 解析为完整样式预设，并生成纸张、页边距、字体、段落、代码、表格、
-页眉、页脚和页码均已映射的动态模板。
+页眉、页脚和页码均已映射的动态模板。Pandoc 转换器通过静态 Lua Filter
+将普通图片、Mermaid 和 ECharts 节点替换为受控 PNG，同时保留 Markdown
+正文、标题、列表、表格、代码和公式的可编辑文档结构。

 ## 设计边界

@@ -12,7 +14,10 @@
 - OOXML 使用 `@xmldom/xmldom`，不拼接未经转义的用户 XML；
 - 不解析任意主题 CSS，主题通过 `docxStyle` 提供受限结构化覆盖；
 - 生成结果会复验全部 XML、包内关系、内容类型、最终节和关键样式；
- Pandoc 进程定位、超时和临时目录属于后续转换服务阶段。
+- 每次转换使用独立临时目录、隔离 Pandoc data 目录并在 `finally` 清理；
+- 媒体映射检查顺序、PNG、像素、单图/总大小和物理显示尺寸；
+- 并发排队、跨端用例编排和错误协议映射由
+  `@md-to-pdf/application` 的 `DocxExportService` 统一负责。

 ## 安全限制

@@ -21,6 +26,7 @@
 - 解压后总大小不超过 64 MiB；
 - 拒绝加密、ZIP64、未知压缩方法、重复路径和路径穿越；
 - 必须包含文档、样式、字体、编号、设置、关系和内容类型等关键部件。
+- 最终 DOCX 不超过 64 MiB、512 个部件和 128 MiB 解压内容。

 ## 验证

@@ -29,9 +35,10 @@ npm run test -w @md-to-pdf/docx-engine
 npm run typecheck -w @md-to-pdf/docx-engine
 npm run build -w @md-to-pdf/docx-engine
 npm run verify:docx-reference
+npm run verify:docx-conversion
 ```

 `verify:docx-reference` 要求本机 `PATH` 中存在 Pandoc 3.9.0.2，也可以通过
-`MD_TO_PDF_PANDOC_PATH` 指定可执行文件。脚本从 Pandoc 读取原始默认模板，
+`DOCX_PANDOC_PATH` 指定可执行文件。脚本从 Pandoc 读取原始默认模板，
 分别验证公文 A4 与自定义横向模板，并在系统临时目录中完成转换和清理，
 不会保留用户文档或验收产物。