feat: 支持 Excel 预览并优化 Office 文件缓存与加载

[CJH-12138]

变更说明

知识库 Office 文件首次预览才开始转换，已有 PDF 缓存也会等待较久；工作区尚未识别 Excel 预览，文件详情在后台生成完成后不会自动刷新。本 PR 支持 .xlsx / .xls，在原件注册后提前生成共享 PDF，缓存命中直接返回完整正文，并让现有预览入口自动显示完成结果。

• 任务类型：feature、bug-fix。
• 目标：支持 Excel 原件预览，减少首次点击和重复预览的等待，正确处理生成中、失败、关闭与离页状态。
• 非目标：聊天附件提前转换、存量文件批量补转、浏览器持久缓存、PDF 排版调整。
• substantial：涉及后台 Task 生命周期、文件缓存及 HTTP 响应语义，按非平凡变更验证。

工程主张与 Owner

• 原件注册由知识库文件记录拥有；knowledge_preview_service 在原件提交后提交独立预览 Task。预览提交异常记录告警，已成功注册的原件仍返回，解析与入库继续。
• PostgreSQL Task 拥有生成意图、lease 和终态，事务提交后通过现有 ARQ worker 执行。worker 在发布 PDF 前核对执行权与原件记录；MinIO PDF 字节拥有可读取结果。
• /workspace/knowledge/file 在授权后读取缓存，缺失时补交去重任务。已读取到内存的二进制使用完整 Response 和 Content-Length，避免 BytesIO 逐行迭代产生大量正文块。
• WorkspaceView 与 FileDetailModal 每两秒检查当前文件；错误停止等待，切换、关闭、离页及卸载隔离迟到结果。本地激活状态关闭 KeepAlive 页面残留的弹窗和遮罩。
• 架构总览在 Durable Task 清单中列出 Office 文件预览，并说明 knowledge_preview 与解析、索引状态独立；完整链路链接现有预览机制页。
• 决策记录：知识库文件预览提前生成与完整响应。

验证情况

XLSX 与真实 XLS 在首次点击前生成对应 PDF，原件不变

• 失败面：仅扩展格式识别，或把任务成功状态当作产物成功。
• 语义 Owner：Office 转换器、注册 service、worker、MinIO。
• 直接证据 / 命令：真实 HTTP 验收上传 XLSX 与 OLE 格式 XLS，在首次预览前回读 Task、PDF 文本标记及原件 SHA-256。
• 负向案例：损坏工作簿转换失败且不发布缓存。
• 结果：Passed。

缓存完整返回，读取时不再同步转换

• 失败面：HTTP 200 但正文逐行阻塞，或读取请求重新转换、重写缓存。
• 语义 Owner：Knowledge 预览模块、HTTP Response。
• 直接证据 / 命令：test_binary_preview_response.py 断言完整正文；真实 HTTP 重复读取核对 PDF 字节、Content-Length 和缓存对象。
• 负向案例：验收进程恢复旧 BytesIO 响应后产生 7102 个正文块，两条协议断言失败；恢复读取时同步转换后，读取边界测试因目标原因失败。
• 结果：Passed。

去重、权限、执行权及原件检查守住发布边界

• 失败面：重复任务、无权限读取、失权发布，或派生任务失败被误报为原件注册失败。
• 语义 Owner：Task repository、权限依赖、注册 service、预览 worker。
• 直接证据 / 命令：service unit 与真实 HTTP 核对并发任务和最终对象；独立 PostgreSQL 临时 trigger 拒绝预览 Task INSERT，上传和添加仍成功，原件记录与对象可回读。移除 trigger 后首次读取补交并生成对应 PDF。
• 负向案例：私有库、错误知识库、文件夹、失权、原件删除、存储错误和预览意图持久化异常。
• 结果：Passed。

页面自动展示完成结果，关闭和离页终止等待

• 失败面：永久 loading、迟到结果覆盖当前文件、KeepAlive 页面继续请求或残留遮罩。
• 语义 Owner：WorkspaceView、FileDetailModal、file_preview。
• 直接证据 / 命令：前端 unit 提取真实组件函数及 watcher/lifecycle 回调；另用真实 Vue/KeepAlive 页面和合成网络验证自动显示 PDF、离页请求计数停止、弹窗和遮罩 DOM display 为 none，以及返回后重新打开。
• 负向案例：错误、切换、关闭、deactivated、unmounted、迟到对象 URL；恢复旧可见性 getter、保留陈旧 props.open=true 时，两条关闭断言因 visible=true 失败。
• 结果：Passed。

后端在匹配锁文件的离线运行镜像中只读挂载源码执行，HTTP fixture 使用独立 PostgreSQL 数据库、专用 Redis、MinIO 和真实 worker；前端与文档使用锁文件对应的依赖。实际命令与结果：

• python -m pytest test/unit -m "not slow" -q -o addopts= --disable-warnings：2547 passed，7 subtests passed。
• python -m pytest test/integration/api/test_knowledge_preview_http.py --confcutdir=test/integration/api -m "not slow" -q -o addopts= -s：1 passed。
• node --test --test-concurrency=1 "test/**/*.test.js" "test/**/*.spec.js"：413 passed，其中详情轮询 9 项。
• node node_modules/eslint/bin/eslint.js . --max-warnings=0、node node_modules/vite/bin/vite.js build：Passed。
• Ruff 0.16.4 对 package 及新增后端测试执行 check / format --check：Passed。
• python scripts/verify_engineering_contracts.py、python -m unittest scripts.test_verify_engineering_contracts：Passed，后者 63 tests。
• 在 docs 执行 node node_modules/vitepress/bin/vitepress.js build：Passed。
• git diff HEAD --check、git diff --cached --check：Passed。
• 架构总览补充后重新执行工程契约检查、63 项契约单测、VitePress build 和双 diff 检查，并核对生成 HTML 的 Office 预览锚点：Passed。

简化 / 删除验收

不涉及。

独立语义 Review

全新上下文 Reviewer 读取最初 31 个文件的完整需求、仓库规范、diff、相关源码、真实 HTTP 产物回读、负向测试和最终页面截图，并独立复跑详情轮询 unit。审查发现的详情轮询、预览提交结果隔离及 KeepAlive 遮罩问题均已修复。随后补充的架构 Owner 文档由另一位全新上下文 Reviewer 对照 registry、预览 service、既有测试及机制页独立审查。最终无未解决阻断项。Review 不替代上述验证。

未验证范围与风险

• Not run：连接真实后端的浏览器 E2E。真实 HTTP/worker 验收与合成网络的真实 Vue 页面验收为两条独立证据。
• Not run：其他浏览器、暗色及响应式视觉回归、真实业务文件和 PDF 排版回归。Excel 仍采用现有 LibreOffice 转换行为。
• 提前转换占用现有 worker 槽位。原件记录与 Task 分开提交，进程崩溃造成的提交间隙由后续缺缓存读取补交；PostgreSQL 检查与 MinIO 发布不构成跨存储事务，删除竞态仍可能留下无可读取元数据的派生对象。
• GitHub CI 在 PR 创建后执行，本地检查不能替代该结果。

事故反馈

未达到高影响事故门槛：本次问题为预览等待和生成状态展示，未发现用户原件丢失或越权。已落地能恢复原缺陷的负向测试和 HTTP 失败恢复验收。

界面变更

以下截图来自原始 Vue 组件与合成文件，不包含用户业务数据。

生成完成后自动展示 PDF：

生成中离开缓存页面，弹窗与遮罩关闭：

关联事项

无。

补充说明

支持 .xlsx、.xls，.xlsm 保持不支持；复用现有 LibreOffice、30 MB 限制、转换超时、Task 队列和共享缓存。无新增依赖、配置或 Schema 迁移；API 与 worker 需使用一致的后端版本。存量文件继续在缓存缺失的首次读取时补交任务。

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-10T10:03:04.071049Z	1c12f98	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 1c12f98335

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[xerrors]

感谢贡献。这次先不合入，主要是方案取舍上的考虑。

目前将 Office 转为 PDF，是受 Web 端预览能力限制采用的权宜方案。继续围绕它增加预生成任务、状态管理和轮询，会带来较多维护成本，但没有从根本上解决各类 Office 文件的统一预览问题，收益与复杂度不太匹配。

因此暂时不继续扩展这条转换链路，这个 PR 先关闭。感谢理解。