crm-backend-matt/.scratch/file-thumbnail/issues/06-office-rendering.md

06 — Office 缩略图渲染（LibreOffice）

What to build: ThumbnailRenderer 的 Office 文档实现，扩展缩略图覆盖范围到 docx/xlsx/pptx。使用 LibreOffice headless 命令行 soffice --convert-to png --outdir {tmpDir} {inputFile} 将 Office 文档转为 PNG（取第一页），再走缩放 + JPEG 输出路径。LibreOffice 不支持并发调用同一 user profile，需用 -env:UserInstallation=file:///tmp/lo-{uuid} 隔离每次调用的 profile。Dockerfile 新增 LibreOffice headless 安装（apt-get install libreoffice --no-install-recommends）。ThumbnailGenerationTask 类型判断扩展：上传 Office 文档时置 PENDING 并提交异步任务。完成后上传一个 docx，等异步任务跑完，调缩略图 API 能拿到第一页缩略图。

Blocked by: 03 — 图片异步生成

Status: ready-for-agent

• ThumbnailRenderer 的 Office 实现：临时文件落地原文件 → soffice --convert-to png -env:UserInstallation=file:///tmp/lo-{uuid} → 读输出 PNG → 缩放 + JPEG 输出
• LibreOffice profile 隔离：每次调用生成唯一 UUID 的 user installation 路径，防止并发冲突
• ThumbnailRenderer.supports() 覆盖 Office（扩展名 docx/xlsx/pptx，或 contentType application/vnd.openxmlformats-officedocument.*）
• ThumbnailGenerationTask 类型判断扩展：Office 文档 → 置 PENDING + 提交异步任务
• Dockerfile 新增 LibreOffice headless 安装（apt-get update && apt-get install -y --no-install-recommends libreoffice）
• 清理临时文件（原文件落地 + LibreOffice 输出 PNG），finally 块保证清理
• 测试：upload docx → thumbnail_status 为 PENDING + 提交异步任务
• 测试：Office 渲染成功 → 第一页缩略图写入 MinIO + 状态 READY
• 测试：ThumbnailRenderer.supports 对 docx/xlsx/pptx 返回 true
• 测试：LibreOffice 不可用（命令找不到）→ 生成失败走重试逻辑（不 crash）