feat: 实现动态 DOCX 模板与样式映射

2026-07-30 14:10:43 +08:00
parent fe5d67fb6d
commit fa159d916f
41 changed files with 3610 additions and 7 deletions
@@ -0,0 +1,37 @@
+# @md-to-pdf/docx-engine
+
+纯 Node.js 的 DOCX 模板和 Pandoc 编排核心。当前阶段负责读取固定 Pandoc
+版本的默认 `reference.docx`、验证 ZIP 安全边界，将主题 DOCX 样式声明
+解析为完整样式预设，并生成纸张、页边距、字体、段落、代码、表格、
+页眉、页脚和页码均已映射的动态模板。
+
+## 设计边界
+
+- 不依赖 Fastify、Electron 或浏览器 UI；
+- ZIP 使用纯 JavaScript `fflate`；
+- OOXML 使用 `@xmldom/xmldom`，不拼接未经转义的用户 XML；
+- 不解析任意主题 CSS，主题通过 `docxStyle` 提供受限结构化覆盖；
+- 生成结果会复验全部 XML、包内关系、内容类型、最终节和关键样式；
+- Pandoc 进程定位、超时和临时目录属于后续转换服务阶段。
+
+## 安全限制
+
+- 输入模板压缩包不超过 2 MiB；
+- ZIP 条目不超过 256 个；
+- 解压后总大小不超过 64 MiB；
+- 拒绝加密、ZIP64、未知压缩方法、重复路径和路径穿越；
+- 必须包含文档、样式、字体、编号、设置、关系和内容类型等关键部件。
+
+## 验证
+
+```powershell
+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
+```
+
+`verify:docx-reference` 要求本机 `PATH` 中存在 Pandoc 3.9.0.2，也可以通过
+`MD_TO_PDF_PANDOC_PATH` 指定可执行文件。脚本从 Pandoc 读取原始默认模板，
+分别验证公文 A4 与自定义横向模板，并在系统临时目录中完成转换和清理，
+不会保留用户文档或验收产物。