word转pdf问题修复

2026-09-11 16:18:44 +08:00
1 parent a4d55a5c55
commit 712ec51d68
@@ -0,0 +1,42 @@
+# 确认书 PDF 首页空白与标题丢失修复
+
+- Task ID: `20260911-confirmation-pdf-html-import-01a0858b`
+- Mode: Feature
+- Status: Complete (local implementation and validation)
+- Scope: 根据用户持续排查和修复确认书导出问题的请求，修复服务端 HTML 文档转 PDF 的导入方式；本地验证，不部署。
+
+## Concurrent Worktree Check
+
+- Branch: `main`
+- Worktree: `/Users/andy/IdeaProjects/LWLT-AIBOT`
+- Base commit: `a4d55a5c55032a166f6d1a3c76eadf471ba36535`
+- Existing changes: 未跟踪 `.idea/` 和 `dist/ltjt-order-assistant-0.5.173.zip`，保留，不涉及当前改动。
+- Other local worktrees: 无。
+- Overlap result: Clear；转换器及测试无既有改动。单 Agent 实现与复核。
+
+## Findings and implementation
+
+- 原始 `.doc` 实际是 UTF-8 Word HTML。本地 Debian 12 容器中的 LibreOffice `7.4.7.2 40(Build:2)` 及四项 Fontconfig 匹配结果与用户提供的 ACK 输出一致；架构为 arm64，生产架构未核实。
+- 现有转换函数可稳定复现 4 页 PDF、首页完全空白、中文标题缺失。仅改字体映射、HTML 字体名、命名页面或 layout-grid 均未消除问题。
+- 在相同版本、字体、输入下显式增加 `--infilter=HTML (StarWriter)` 后得到 3 页，中文标题恢复。全部页面已渲染检查；原始 HTML 中 121 个至少 4 个非空白字符的文本片段全部可在结果中找到。
+- 已在 PDF 转换参数中按现有 HTML 检测结果增加 `--infilter=HTML (StarWriter)`；保留原有宽度规范化、隔离 profile、超时、大小限制及失败回退。二进制 Word、RTF、PDF 透传与 XLSX 转换不强制 HTML 导入。
+- 原始客户文件与实验 PDF 仅在用户文件位置和本机临时目录；仓库只保存脱敏验证结论，不保存业务正文。测试容器断网，不访问 ERP 或外发消息。
+
+## Verification
+
+- 回归先行：旧实现新增用例中的 5 个 HTML 子用例失败，3 个非 HTML 子用例通过；修复后转换器测试 15/15 PASS。覆盖 ERP vendor MIME、BOM、DOCTYPE、body-only HTML、HTML 扩展名/MIME，以及二进制 DOC、DOCX、RTF 的格式边界，已有 XLSX/PDF 透传和宽度测试通过。
+- `node --run check`：PASS；`node --run build`：PASS；`node --run test:control-plane`：211/211 PASS。
+- 工作目录 `check:repo` 为 8/10、`test:legacy` 为 288/290；失败仅为既有 `.idea`、根目录和 `chrome-extension/` 下 `.DS_Store`。保留这些文件，在 `/private/tmp/ltjt-pdf-clean-verify-k61osr4z` 的当前文件副本中排除编辑器杂项和秘密后，`check:repo` 10/10、`test:legacy` 290/290 PASS。legacy 测试经授权允许本机临时 HTTP 监听，不启动业务服务。
+- 用 `node --run build` 生成的实际转换模块、原始输入、默认 `soffice` 路径和隔离 profile 在断网 Linux 容器复验：3 页、首面标题存在、121/121 正文片段匹配；全部 3 页渲染与已逐页检查的参数实验结果逐像素一致。
+- 原始文件 SHA-256 未变化。未验证远程印章图片下载、生产架构及完整生产镜像一致性；本地结果不代表生产已部署。
+- [不可变脱敏证据](../../../archive/evidence/2026-09-11/20260911-confirmation-pdf-html-import-01a0858b/README.md)。原始客户文件、PDF 和截图不进入仓库。
+- 最终自行只读复核 PASS：源码仅增加 HTML 条件导入参数，未改 XLSX 路径、超时、回退或业务路由；`git diff --check` PASS。无子 Agent、无部署、无数据库或 ERP 操作。
+
+## Outcome and follow-ups
+
+- 本地实现与验证完成。生效需用户重建并部署服务端镜像；不需要插件、数据库、字体包或 LibreOffice 升级。
+- 部署后需重新导出确认书，既有 OSS/PDF 文件不会因代码升级自动重生成。生产部署和实际导出验收由用户执行。
+
+## Promotion Candidates
+
+- 集成时可在文档导出架构说明中登记 HTML-in-DOC PDF 转换必须显式使用 Writer HTML 导入器，避免 LibreOffice 7.4 默认导入导致首段丢失；本任务不改 canonical 文档。