# 确认书 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 文档。