Files

2026-07-16 18:25:51 +07:00

13 KiB

Raw Blame History

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：

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. 后端模块边界

建议新增平台模块：

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 手动上传转换

前端上传 Excel
  -> 后端校验文件类型和大小
  -> 写入隔离临时目录
  -> 调用 LibreOffice headless 转 PDF
  -> 校验 PDF 输出存在且非空
  -> 上传 PDF 到 OSS 或直接返回文件流
  -> 返回转换结果
  -> 清理临时文件

建议第一版优先返回 OSS URL，原因：

与现有 Debug EML 附件处理和阿里云 OSS 上传能力一致。
PDF 可以被前端预览或下载。
转换结果可以被后续审计和自动转换链路复用。

5.2 邮件附件自动转换

SourceMessage 入库 / EML 调试链路解析附件
  -> 识别 Excel 附件
  -> 创建文件转换任务
  -> 异步 worker 执行转换
  -> PDF 上传 OSS
  -> 回写转换任务状态和派生 PDF 结果

自动转换不应阻塞邮件入库、AgentBus WebSocket 回调、SuperAgent dispatch 或任务结果入站。第一版如果转换失败，只记录 FAILED / RETRYABLE_FAILED 和安全错误摘要，不影响原附件可见。

6. 建议接口边界

6.1 手动上传接口

CP2 已实现：

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、对象路径、文件名、大小、转换耗时、安全错误摘要。

请求示例：

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"

成功响应示例：

{
  "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，不提供给前端直接调用：

DocumentConversionService.createExcelToPdfRun(...)
DocumentConversionWorker.processPendingRuns(...)

中文说明：

邮件链路、Debug EML 链路和未来其他附件来源都只创建转换任务。
worker 统一处理重试、超时和状态流转。

7. 建议数据模型

如需要持久化转换记录，建议新增表：

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，手动上传场景需要确认。

13 KiB Raw Blame History Unescape Escape

M008 Excel 转 PDF 文件转换能力 V1

1. 背景

2. 设计原则

3. 方案选择

3.1 推荐方案：LibreOffice headless

3.2 不推荐第一版使用 POI 手工绘制 PDF

3.3 商业库作为备选

4. 后端模块边界

5. 第一版数据流

5.1 手动上传转换

5.2 邮件附件自动转换

6. 建议接口边界

6.1 手动上传接口

6.2 自动转换内部入口

7. 建议数据模型

8. 配置与部署要求

9. 安全与稳定性要求

10. Checkpoint 规划

CP1：方案和部署验证

CP2：手动上传转换接口

CP3：持久化转换任务和 worker

CP4：邮件附件自动转换

CP5：前端展示和下载

11. 当前未确定事项

13 KiB

Raw Blame History