LWLT-AIBOT/.project-docs/30-worklog/tasks/20260911-confirmation-pdf-html-import-01a0858b.md

确认书 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 未变化。未验证远程印章图片下载、生产架构及完整生产镜像一致性；本地结果不代表生产已部署。
• 不可变脱敏证据。原始客户文件、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 文档。