缺陷 1008567 - Word 文件解析失败
原始需求（一字不差）
缺陷标题：word-文件解析失败
状态：new ｜ 负责人：张倩如;尹帮会 ｜ 严重程度：未设置 ｜ 优先级：未设置 ｜ 创建者：小润润
创建时间：2025-12-25 14:37:49 ｜ 修改时间：2026-03-19 12:27:46
原始描述：
[图片: https://file.tapd.cn//tfl/captures/2025-12/tapd_67139335_base64_1766644675_344.png]
图片理解
截图1 - 原始描述（1920 × 960）- Word 解析错误提示
画面内容：
- 工作台页面顶部红色错误横幅：
文档加载失败：Word 文档解析失败: Can't find end of central directory : is this a zip file ? If it is, see https://stuk.github.io/jszip/documentation/howto/read_zip.html - 左侧文件树显示多个文件（kisling2022.pdf、ZJ-TD-OT 系列文件等）
- 右侧为 AI 对话面板，正常运行
关键细节：
- 错误来自 jszip 库，.docx 本质是 ZIP 包，jszip 无法识别文件头
- 错误出现在文档加载阶段，文件内容本身可能损坏/旧格式
截图2 - 评论附图（925 × 898）- OnlyOffice 转换失败
画面内容：
- 工作台左侧编辑区显示两个 tab（afc22...、ZJ-T...）
- 当前 tab 显示警告图标 + 「加载失败: Conversion failed with code: 88」+ 「重试」按钮
- 右侧 AI 面板正在对文档内容进行问答（文件已被知识库解析，可提问）
关键细节：
- 错误码 88 来自 X2T WASM 本地转换失败
- 文件在知识库侧可正常解析提问，说明文件本身是完好的
- 问题出在前端本地 X2T WASM 转换旧版 Office 格式时失败
评论
[2026-03-11 14:33:34] 张倩如：
https://linkmed.tos-cn-beijing.volces.com/docs-parsed/prod{file_id}/convert.{toExt}转换成新版office会上传到tos这个位置，前端可以拉取预览
↳ [2026-03-11 14:33:57] 张倩如：
仅预览，不要支持修改！！！！
[2026-02-12 12:48:47] 张倩如（含截图2）：
文件可解析可提问，只是前端渲染不出来
关键约束：
- 后端已将 Word 文件转换为新版 Office 格式并上传至 TOS
- 前端只需从 TOS 拉取预览，禁止支持编辑修改
- TOS 路径规则：
docs-parsed/prod{fileId}/convert.{toExt}
根因分析
两个错误来源不同
-
jszip 错误（
Can't find end of central directory）：前端尝试直接用 jszip 解析旧版.doc文件，旧版 Word 不是标准 ZIP 格式 - X2T code 88：前端本地 WASM 转换工具（X2T）处理某些 Word 文件时转换失败
根本问题
OnlyOfficeViewer.vue 下载原始文件后直接交给 X2T WASM 本地转换，X2T 对旧版或特殊 Word 文件兼容性不足。
解决路径
后端已有文件转换 pipeline，将 Word 文件转为新版格式上传至 TOS。前端优先使用后端转换好的版本，X2T 处理新版 docx 兼容性更好，若 TOS 无转换版本（老文件）则静默回退原文件。
涉及文件
-
src/components/Workspace/OnlyOfficeViewer.vue：文件加载入口 -
src/utils/onlyoffice/converter.ts：X2T 转换和 OnlyOffice 编辑器初始化
修复方案
TOS 转换版本优先策略
在 OnlyOfficeViewer.vue 的 initViewer() 中，下载原文件前先尝试从 TOS 拉取后端转换版本：
TOS key: docs-parsed/prod{fileId}/convert.{toExt}
扩展名映射: doc/docx → docx, ppt/pptx → pptx, xls/xlsx → xlsx成功 → 使用转换版本；失败（老文件无转换版本）→ 静默回退下载原文件。
只读预览
createEditorInstance 新增 readOnly 参数，permissions: { edit: !readOnly }。OnlyOfficeViewer 调用 openDocument 时传入 readOnly: true。
修改的文件
-
src/components/Workspace/OnlyOfficeViewer.vue：TOS 优先逻辑 + 只读模式 -
src/utils/onlyoffice/converter.ts：createEditorInstance/openDocument新增readOnly参数
测试结果
-
npm run type-check通过，无 TypeScript 错误 -
npm run test:unit通过，19 个用例全部通过
测试覆盖
单元测试（Vitest）
文件：src/test/features/onlyoffice-tos-fallback.test.ts（12 个用例）
| 测试组 | 用例 |
|---|---|
| TOS storageKey 构造 | doc/docx/ppt/pptx/xls/xlsx 路径正确；不支持格式返回 null；无扩展名返回 null |
| 转换后文件名构造 | 各格式文件名扩展名正确替换；新格式保持不变 |
E2E 测试（Playwright）
文件：e2e/tests/onlyoffice-word-preview.spec.ts（1 个用例，通过）
- 工作台加载不出现 jszip Word 解析错误
验收条件
- 打开 Word/PPT/Excel 文件时优先从 TOS 加载后端转换版本 ✅
- TOS 无转换版本（老文件）静默回退原文件 ✅
- 预览模式为只读，OnlyOffice 编辑按钮不可用 ✅
- 不影响 PDF、图片、Markdown 等其他文件类型 ✅