实现Excel转PDF手动转换接口

2026-07-16 18:25:51 +07:00
parent ed37d5f955
commit 8d53b72363
30 changed files with 1995 additions and 52 deletions
--- a/docs/project/requirements/M008-excel-to-pdf-conversion-v1.md
+++ b/docs/project/requirements/M008-excel-to-pdf-conversion-v1.md
@@ -0,0 +1,318 @@
+# M008 Excel 转 PDF 文件转换能力 V1
+
+| 项目 | 内容 |
+| --- | --- |
+| 文档状态 | 当前有效 |
+| 适用范围 | 手动上传 Excel 转 PDF、邮件附件 Excel 自动派生 PDF |
+| 推荐方案 | LibreOffice headless 作为后端受控转换引擎 |
+| 当前目标 | CP2 已实现手动上传 Excel 转 PDF 后端接口；邮件附件自动转换、持久化转换任务和 worker 后置 |
+
+## 1. 背景
+
+系统后续会出现两类 Excel 转 PDF 需求：
+
+- 前端 Debug / 后台页面手动上传 `.xls` / `.xlsx`，后端转换为 PDF 后返回下载或 OSS URL。
+- 邮件来源链路中，AgentBus 或 Debug EML 解析到 Excel 附件后，系统自动派生 PDF，便于前端预览、人工复核或后续证据沉淀。
+
+这两类场景不应各自实现转换逻辑。第一版应把 Excel 转 PDF 做成平台级文件转换能力，手动上传和自动转换都调用同一套 Service / Adapter。
+
+## 2. 设计原则
+
+- 文件转换属于 `platform` 通用能力，不绑定 `reservation` 订单任务流程。
+- 业务代码只依赖内部稳定 Service，不直接调用 `soffice` 命令。
+- LibreOffice 作为外部运行时依赖，需要通过 Adapter 隔离。
+- 手动上传接口和邮件附件自动转换共享同一套校验、超时、并发、临时文件清理、OSS 上传和错误处理规则。
+- 转换失败不能影响 SourceMessage 原始邮件入库；自动转换失败只记录失败原因和可重试状态。
+- Excel 原文件和 PDF 派生文件必须能建立来源关系，便于审计和排查。
+- 默认不支持宏执行，不支持外部链接刷新，不支持把 Excel 内容写入普通日志。
+
+## 3. 方案选择
+
+### 3.1 推荐方案：LibreOffice headless
+
+后端把 Excel 文件写入隔离临时目录，然后调用 LibreOffice headless：
+
+```bash
+soffice --headless --nologo --nofirststartwizard --norestore \
+  -env:UserInstallation=file:///tmp/th-hotel-lo-profile-xxx \
+  --convert-to pdf \
+  --outdir /tmp/th-hotel-convert-output-xxx \
+  /tmp/th-hotel-convert-input-xxx/source.xlsx
+```
+
+中文说明：
+
+- `soffice` 负责按照 Excel 自身页面设置、分页、合并单元格、图片和样式生成 PDF。
+- `UserInstallation` 必须为每次转换使用独立临时目录，降低并发转换时的 profile 冲突风险。
+- 后端必须设置转换超时；超时后销毁进程并清理临时文件。
+
+### 3.2 不推荐第一版使用 POI 手工绘制 PDF
+
+Apache POI 可以读取 Excel，但要完整还原页面设置、分页、图表、图片、字体、合并单元格和打印区域，需要大量手工逻辑，维护成本高，不适合作为第一版主方案。
+
+### 3.3 商业库作为备选
+
+Aspose / Spire 等商业库可以降低运行时部署复杂度，但需要确认授权、费用和商用合规。除非项目明确采购，否则第一版不采用。
+
+## 4. 后端模块边界
+
+建议新增平台模块：
+
+```text
+server/src/main/java/cn/nianxx/thhotel/platform/documentconversion
+├── control
+├── service
+│   └── impl
+├── domain
+├── mapper
+├── repository
+└── common
+    ├── dto
+    ├── request
+    ├── result
+    └── enums
+
+server/src/main/java/cn/nianxx/thhotel/integrations/document/libreoffice
+└── adapter
+```
+
+中文说明：
+
+| 模块 | 中文职责 |
+| --- | --- |
+| `platform.documentconversion` | 平台文件转换能力，负责请求校验、转换任务、OSS 输出、审计和结果查询 |
+| `integrations.document.libreoffice.adapter` | LibreOffice 外部进程适配器，只负责调用 `soffice`、收集退出码和输出文件 |
+| `integrations.storage.aliyunoss` | 继续作为 OSS 上传端口，转换服务只依赖 `ObjectStorageService` |
+
+后端实现时继续遵守当前项目包结构规范：`control`、`service`、`service.impl`、`domain`、`mapper`、`repository`、`common.request`、`common.result`、`common.dto`、`common.enums`。
+
+## 5. 第一版数据流
+
+### 5.1 手动上传转换
+
+```text
+前端上传 Excel
+  -> 后端校验文件类型和大小
+  -> 写入隔离临时目录
+  -> 调用 LibreOffice headless 转 PDF
+  -> 校验 PDF 输出存在且非空
+  -> 上传 PDF 到 OSS 或直接返回文件流
+  -> 返回转换结果
+  -> 清理临时文件
+```
+
+建议第一版优先返回 OSS URL，原因：
+
+- 与现有 Debug EML 附件处理和阿里云 OSS 上传能力一致。
+- PDF 可以被前端预览或下载。
+- 转换结果可以被后续审计和自动转换链路复用。
+
+### 5.2 邮件附件自动转换
+
+```text
+SourceMessage 入库 / EML 调试链路解析附件
+  -> 识别 Excel 附件
+  -> 创建文件转换任务
+  -> 异步 worker 执行转换
+  -> PDF 上传 OSS
+  -> 回写转换任务状态和派生 PDF 结果
+```
+
+自动转换不应阻塞邮件入库、AgentBus WebSocket 回调、SuperAgent dispatch 或任务结果入站。第一版如果转换失败，只记录 `FAILED` / `RETRYABLE_FAILED` 和安全错误摘要，不影响原附件可见。
+
+## 6. 建议接口边界
+
+### 6.1 手动上传接口
+
+CP2 已实现：
+
+```text
+POST /api/system/document-conversions/excel-to-pdf
+```
+
+中文说明：
+
+- 接口分类：`FRONTEND_DEBUG` 或 `FRONTEND_ADMIN`，不能作为普通公开接口。
+- 鉴权方式：CP2 使用环境开关 + 受控 access key；后续可统一迁移到登录权限体系。
+- Header：`X-TH-Hotel-Document-Conversion-Key: <文件转换访问口令>`。
+- 请求类型：`multipart/form-data`。
+- 文件字段：`file`。
+- 可选字段：`hotel_id`，用于 OSS 对象路径分组；CP2 不做酒店访问权校验，生产启用前应迁移到登录权限体系。
+- 返回：转换状态、PDF OSS URL、对象路径、文件名、大小、转换耗时、安全错误摘要。
+
+请求示例：
+
+```bash
+curl -X POST "$BASE_URL/api/system/document-conversions/excel-to-pdf" \
+  -H "X-TH-Hotel-Document-Conversion-Key: $DOCUMENT_CONVERSION_ACCESS_KEY" \
+  -F "hotel_id=HOTEL-TEST" \
+  -F "file=@booking-request.xlsx"
+```
+
+成功响应示例：
+
+```json
+{
+  "conversion_status": "SUCCEEDED",
+  "source_file_name": "booking-request.xlsx",
+  "source_size_bytes": 12345,
+  "pdf_file_name": "booking-request.pdf",
+  "pdf_url": "https://oss.example.test/document-conversions/excel-to-pdf/HOTEL-TEST/2026-07-16/.../booking-request.pdf",
+  "object_key": "document-conversions/excel-to-pdf/HOTEL-TEST/2026-07-16/.../booking-request.pdf",
+  "content_type": "application/pdf",
+  "pdf_size_bytes": 67890,
+  "duration_millis": 1200
+}
+```
+
+错误码：
+
+| HTTP | 错误码 | 中文含义 |
+| --- | --- | --- |
+| `401` | `DOCUMENT_CONVERSION_KEY_INVALID` | 文件转换访问口令缺失或错误 |
+| `404` | `DOCUMENT_CONVERSION_DISABLED` | 文件转换接口未启用 |
+| `400` | `DOCUMENT_CONVERSION_FILE_REQUIRED` | 缺少上传文件或文件为空 |
+| `400` | `DOCUMENT_CONVERSION_FILE_TYPE_UNSUPPORTED` | 不是 `.xls` / `.xlsx` |
+| `400` | `DOCUMENT_CONVERSION_FILE_CONTENT_INVALID` | 文件扩展名是 Excel，但文件头不是 `.xlsx` ZIP / `.xls` OLE 格式 |
+| `413` | `DOCUMENT_CONVERSION_FILE_TOO_LARGE` | 超过配置的文件大小限制 |
+| `429` | `DOCUMENT_CONVERSION_BUSY` | 转换并发已满，稍后重试 |
+| `502` | `DOCUMENT_CONVERSION_FAILED` | LibreOffice 转换失败或未生成有效 PDF |
+| `502` | `DOCUMENT_CONVERSION_OSS_UPLOAD_FAILED` | PDF 上传 OSS 失败 |
+| `504` | `DOCUMENT_CONVERSION_TIMEOUT` | LibreOffice 转换超时 |
+
+### 6.2 自动转换内部入口
+
+建议后续只暴露内部 Service，不提供给前端直接调用：
+
+```text
+DocumentConversionService.createExcelToPdfRun(...)
+DocumentConversionWorker.processPendingRuns(...)
+```
+
+中文说明：
+
+- 邮件链路、Debug EML 链路和未来其他附件来源都只创建转换任务。
+- worker 统一处理重试、超时和状态流转。
+
+## 7. 建议数据模型
+
+如需要持久化转换记录，建议新增表：
+
+```text
+platform_document_conversion_run
+```
+
+建议核心字段：
+
+| 字段 | 中文含义 |
+| --- | --- |
+| `id` | 内部转换任务 ID |
+| `hotel_id` | 酒店 ID，手动上传或来源消息所属酒店 |
+| `conversion_type` | 转换类型，第一版为 `EXCEL_TO_PDF` |
+| `source_type` | 来源类型，例如 `MANUAL_UPLOAD`、`SOURCE_MESSAGE_ATTACHMENT`、`DEBUG_EML_ATTACHMENT` |
+| `source_object_id` | 来源对象 ID，例如 SourceMessage ID 或 Debug run ID |
+| `source_file_name` | 原始文件名 |
+| `source_content_type` | 原始文件 MIME |
+| `source_oss_url` | 原文件 OSS URL；手动上传如不保留原文件可为空 |
+| `target_file_name` | 生成 PDF 文件名 |
+| `target_oss_url` | 生成 PDF OSS URL |
+| `status` | 转换状态 |
+| `attempt_count` | 已尝试次数 |
+| `safe_error_code` | 安全错误码 |
+| `safe_error_summary` | 安全错误摘要，不包含文件内容和敏感 URL |
+| `created_by` | 创建人或机器身份 |
+| `created_at` / `updated_at` | UTC 时间 |
+
+建议状态：
+
+| 状态 | 中文含义 |
+| --- | --- |
+| `PENDING` | 等待转换 |
+| `RUNNING` | 正在转换 |
+| `SUCCEEDED` | 转换成功 |
+| `RETRYABLE_FAILED` | 可重试失败 |
+| `FAILED` | 不可重试失败 |
+| `CANCELED` | 已取消 |
+
+## 8. 配置与部署要求
+
+建议配置项：
+
+| 配置 | 是否 Secret | 中文说明 |
+| --- | --- | --- |
+| `DOCUMENT_CONVERSION_DEV_ENABLED` / `DOCUMENT_CONVERSION_TEST_ENABLED` / `DOCUMENT_CONVERSION_PROD_ENABLED` | 否 | 是否启用文件转换能力 |
+| `DOCUMENT_CONVERSION_DEV_ACCESS_KEY` / `DOCUMENT_CONVERSION_TEST_ACCESS_KEY` / `DOCUMENT_CONVERSION_PROD_ACCESS_KEY` | 是 | 手动上传转换访问口令；未配置时可兜底 `DOCUMENT_CONVERSION_ACCESS_KEY` |
+| `DOCUMENT_CONVERSION_SOFFICE_PATH` | 否 | `soffice` 可执行文件路径，默认 `soffice` |
+| `DOCUMENT_CONVERSION_TEMP_DIR` | 否 | 临时文件根目录 |
+| `DOCUMENT_CONVERSION_MAX_FILE_BYTES` | 否 | 单个 Excel 最大字节数 |
+| `DOCUMENT_CONVERSION_TIMEOUT_SECONDS` | 否 | 单次转换超时时间 |
+| `DOCUMENT_CONVERSION_MAX_CONCURRENT` | 否 | 最大并发转换数 |
+| `DOCUMENT_CONVERSION_OUTPUT_OSS_PREFIX` | 否 | PDF 输出 OSS 前缀 |
+| `DOCUMENT_CONVERSION_WORKER_ENABLED` | 否 | 自动转换 worker 是否启用 |
+
+服务器需要准备：
+
+- 安装 LibreOffice / LibreOffice Calc。
+- 安装中文、英文、泰文等业务需要字体，例如 Noto CJK、Noto Thai、Arial 兼容字体。
+- 确认运行后端的系统用户可以执行 `soffice`，并有临时目录读写权限。
+- 确认临时目录磁盘空间、清理策略和权限隔离。
+- 测试机和生产机 LibreOffice 版本尽量一致，避免同一 Excel 输出 PDF 差异过大。
+
+## 9. 安全与稳定性要求
+
+- 只允许 `.xls` / `.xlsx`；第一版不支持 `.xlsm`。后端会同时校验扩展名和文件头：`.xlsx` 必须是 ZIP / OOXML 头，`.xls` 必须是 OLE 复合文档头。
+- 文件大小必须有限制，默认建议不超过 20 MB，具体值实现前再确认。
+- 使用 `ProcessBuilder` 参数数组调用外部进程，禁止拼接 shell 字符串。
+- 每次转换使用独立输入目录、输出目录和 LibreOffice profile 目录。
+- 转换完成、失败或超时后必须清理临时文件。
+- 日志只记录转换 ID、文件类型、大小、耗时、状态和安全错误摘要，不记录 Excel 内容、PDF 内容、OSS 签名 URL 或客户敏感信息。
+- 自动转换 worker 必须限制并发，避免大量附件同时转换拖垮后端。
+- 生产环境默认关闭，待测试机验证转换质量、字体和性能后再开启。
+
+## 10. Checkpoint 规划
+
+### CP1：方案和部署验证
+
+- 落地本文档。
+- 测试机安装 LibreOffice 和字体。
+- 用真实业务样式 Excel 手工执行 `soffice` 命令，确认 PDF 保真度。
+- 明确 PDF 输出是直接下载还是 OSS URL，建议第一版 OSS URL。
+
+### CP2：手动上传转换接口
+
+- 新增平台文件转换模块。
+- 实现 `POST /api/system/document-conversions/excel-to-pdf`。
+- 接入 OSS 输出。
+- 补充文件类型、大小、超时、临时文件清理和错误返回测试。
+- 更新前后端沟通文档和上线注意事项。
+
+当前状态：已完成第一版后端接口。CP2 不落库、不做 worker、不自动处理邮件附件；返回的 PDF 会上传 OSS，接口受 `document-conversion.enabled` 和 `X-TH-Hotel-Document-Conversion-Key` 控制。
+
+### CP3：持久化转换任务和 worker
+
+- 新增 `platform_document_conversion_run`。
+- 实现 PENDING / RUNNING / SUCCEEDED / RETRYABLE_FAILED / FAILED 状态流转。
+- 支持自动重试、错误摘要和结果查询。
+
+### CP4：邮件附件自动转换
+
+- SourceMessage / Debug EML 链路识别 Excel 附件后创建转换任务。
+- PDF 派生结果和原附件建立来源关系。
+- 自动转换失败不影响原邮件入库和业务主流程。
+
+### CP5：前端展示和下载
+
+- 手动上传页面展示转换进度和 PDF 链接。
+- 邮件会话或附件区域展示 Excel 原件和派生 PDF。
+- 前端不得把 OSS URL 写入普通日志、埋点或 URL query。
+
+## 11. 当前未确定事项
+
+实现前需要确认：
+
+- 手动上传第一版返回 PDF 文件流，还是上传 OSS 后返回 URL；当前建议 OSS URL。
+- 手动上传接口是放在 Debug 页面、系统管理页面，还是单独工具页面。
+- 第一版最大文件大小和最大转换时长；当前代码默认 20 MB 和 60 秒，可通过环境变量调整。
+- 自动转换是否只处理邮件附件，还是也处理用户手动上传后保存的 Excel。
+- PDF 是否需要长期保存；如果长期保存，需要确认 OSS 生命周期和清理策略。
+- 是否需要把 Excel 原文件也统一转存 OSS；自动附件场景通常已有 OSS URL，手动上传场景需要确认。