unis-oa/docs/attachment-preview.md

12 KiB
Raw Blame History

附件与审批随附文件的预览设计

流程里上传的附件、审批意见随附的图片与文件,字节一律在 MinIO(落点见 architecture.md 的存储层,配置入口在「系统设置 → 文件存放位置」)。 这篇讲的是怎么把它们显示给审批人看。

1. 一句话结论

字节早就进 MinIO 了,缺的是"取回来之后怎么画"。所以这一层不搬文件、不加表、 不加配置段,只在存储层加一个分类器,在接口加一个读取正文的出口, 前端加一个按类型分派的预览面板。

2. 三条渲染路线

分类只看扩展名(MIME 兜底),不看字节——为了认格式把文件从 MinIO 拉回来一遍不值得。

路线 谁渲染 覆盖格式 走哪个接口
browser 浏览器自己 图片、PDF、音频、视频 /attachment/{id}/download?inline=1
backend 后端读出正文,前端用模板画 Word、Excel、PPT、纯文本/代码、Markdown、CSV/TSV、HTML /attachment/{id}/preview
none 只能下载 压缩包、.doc/.xls/.ppt 旧二进制格式 /attachment/{id}/download

renderer 这个字段的取值就是前端要挂的组件名:image pdf media html text markdown table document workbook slides none。

为什么 Word/Excel 要后端解析

浏览器打不开 .docx/.xlsx,而 OA 里的"文档"绝大多数就是这几种。后端用 python-docx / openpyxl / python-pptx 把正文读出来(三个库都延迟导入, 没装也能起服务,只是那三种格式退回"请下载后查看")。

没有走"服务端转 PDF"那条路:那要求服务器上装 LibreOffice,单机部署十有八九没有, 还多一份临时文件和缓存要管。

为什么回 JSON 而不是 HTML

附件是别人传上来的,属于不可信输入。后端拼 HTML 等于把 XSS 的活儿揽到自己身上 (![x](javascript:...) 这类)。所以 /preview 回的是结构化数据——段落、标题、 表格、单元格、逐页文本——前端用 Vue 模板画,脚本没有能执行的地方。

两个例外自己处理:

  • HTML 附件:后端原样回文本,前端用 <iframe :srcdoc sandbox=""> 装,空 sandbox 意味着不脚本、不同源;
  • Markdown:前端 marked 转 HTML 后过一道 DOMPurify(两个库仓库里本来就有)。

SVG 走的是 <img>,<img> 里的脚本不会执行,所以不必另开一类。

3. 接口

GET /api/v1/attachment/{id}/preview
  • 权限与 /download 一致(要求登录,附件本身按单据可见性由调用方控制)
  • 浏览器直出的类型回 mode: "inline" + 一个 url,后端不碰字节
  • 其余回 mode: "payload" 加结构化正文
  • 不能预览回 400 PREVIEW_UNSUPPORTED,消息就是给人看的那句原因

响应形状(节选):

// 图片 / PDF / 音视频
{ "kind": "pdf", "renderer": "pdf", "mode": "inline", "url": "/api/v1/attachment/xxx/download?inline=1" }

// Word
{ "renderer": "document", "mode": "payload",
  "blocks": [ {"t":"heading","level":1,"text":"请假申请单"},
              {"t":"paragraph","text":"申请人:张三","list":0},
              {"t":"table","rows":[["日期","时长"],["2026-09-21","1 天"]]} ],
  "truncated": false }

// Excel / CSV 共用一种形状:一组带名字的二维表
{ "renderer": "workbook", "mode": "payload",
  "sheets": [ {"name":"费用明细","rows":[["项目","金额"],["打车","38.5"]]} ] }

// PPT
{ "renderer": "slides", "mode": "payload",
  "slides": [ {"index":1,"title":"","texts":["收入增长 12%"],"notes":"备注 1"} ] }

顺带把结论塞进了序列化结果:每条附件都带一个 preview 字段 ({kind, renderer, previewable, reason}),列表页据此决定画不画那只"眼睛", 不必每条再问一次接口。审批轨迹里的随附文件是历史 JSON 快照,老数据没这个字段, 前端按扩展名兜底。

4. 规模上限

上限 默认 说明
max_preview_mb 50 系统设置里改,存库即生效。只卡需要后端读正文的格式

图片与 PDF 不受这条限制——两百兆的扫描件也该能直接看,那本来就是浏览器在解。

代码里还有几道硬闸门,防的是"一份大附件把接口拖住、把响应撑爆":正文 20 万字、 表格 500 行 × 60 列、单元格 2000 字、Word 2000 个块、PPT 200 页。 超了就置 truncated: true,面板顶部明确告诉用户"这里只画了前面一部分,完整内容请下载", 不装作看全了。

5. 错误怎么分

沿用存储层"按原因给状态码"的规矩,新增一个 StorageUnreadableError:

情况 状态码 reason
不支持在线预览(压缩包、旧格式) 400 PREVIEW_UNSUPPORTED
文件损坏 / 加了密 / 改了后缀 / 没有正文 400 STORAGE_UNREADABLE
连不上 MinIO 502 STORAGE_UNAVAILABLE
附件不存在 404 NOT_FOUND

python-docx 抛 BadZipFile、openpyxl 抛 KeyError、pptx 抛 lxml 的东西—— 这些在 preview.render() 里统一收成一个 StorageUnreadableError。 "这个文件读不了"从来不是服务器故障,让它冒到 500 会把人引去翻服务端日志。

6. 编码

审批附件里 GBK 的 txt / csv 很常见。preview.decode_text() 按 utf-8-sig → utf-8 → gb18030 → big5 → shift_jis → utf-16 → latin-1 依次试, 解出来替换符过多就换下一个,latin-1 永远不失败所以只垫底。 CSV 一律交给 csv 模块,带引号的逗号和引号里的换行都按 RFC 4180 走,不按逗号切。

7. 前端

components/common/FilePreviewDialog.vue 一个面板按 renderer 分派, 所有格式共用一条顶栏(文件名、类型、大小、第几张、下载、关闭)和左右翻页。 入口铺在五个地方:

位置 组件 说明
审批轨迹随附文件、单据附件区 AttachmentGallery 图片出缩略图,其余按类型给图标
表单附件字段(填写态)、待办页单据附件 AttachmentUploader 文件名和眼睛图标都能点
表单附件字段(只读态:审批人看单、打印页、锁着的明细列) FormFieldControl 图标按类型给,点了就地开面板
审批意见 / 批注输入框 OpinionComposer 贴完先看见缩略图,点开看大图
网盘(首页面板 + 网盘页) FilePanel / FileDriveView 文件名即预览入口,行内另给眼睛

点了"不能预览"的文件直接下载,不先弹一个面板再告诉用户看不了。

只读态那一行是补的口径,不是加的功能:手机端早就走画廊,桌面端却把附件字段渲染成 一排「下载箭头 + 文件名」,FormRenderer 四五个 @attachment-open 接的又都是 save(),于是同一个 .docx「手机点得开、电脑只能存」。改在 FormFieldControl 的只读分支里,是因为明细表、锁定格、打印页都从这一支出去——修一处比在五处各修一次 靠谱,attachment-open 这个事件留着,它现在只承载"这份看不了,交给调用方下载"。

8. 审批时贴图

OpinionComposer 一个输入框管三种进件方式:点附件按钮、点图片按钮、直接 Ctrl/⌘+V。 几个约定:

  • 剪贴板里只有文字时放行这次粘贴,不能把用户复制文字都吞掉;
  • 浏览器给贴图起的名字常常是 image.png 甚至没后缀,前端按 MIME 补后缀 (后缀一丢,扩展名白名单和缩略图判断两头都认不出来),再换成带时间戳的 screenshot-YYYYMMDD-HHmmss.png,连贴三张也分得清;
  • 先上传拿到 id,提交审批时才 claim_attachments 认领成 type = opinion, 并只认"本人上传 + 尚未被别人认领"这两条硬规则。唯一的例外是批量登记待阅 (mark_reads_batch):一句共用的处理意见带着同一张图登记 N 条需处理的待阅,而一条 附件行只认一个 business_id,第二条起就撞"已被其它批注使用"——勾 5 条贴一张图, 最后只办成 1 条。这一路传 clones=True,后认领的那几条各插一条指针行:只复制 内容列,storage 仍是同一个 URI(MinIO 里一份字节),归属互不覆盖。批注与单条处理 意见不传这一档,一张图被两条批注抢仍然是错误;
  • 传好了又把图删掉,顺手把 MinIO 上的对象一起删,别留孤儿。release_attachments 认的是 "business_id 不是我就什么都不动",所以上面那些指针行里删掉任何一条已阅, 都带不跑别人那份引用。

随附文件不进单据附件清单(Attachment.KIND_LINKED),跟着那条批注/意见一起显示。

9. 地址只有一份,前端进 axios 前要收正

后端下发的 download_url / preview_url 是带 base 的完整路径(/api/v1/...), 因为它要能直接写进 <img src>、<a href> 和 fetch。代价是它不能直接喂给 http.*:axios 自己还挂着 baseURL=/api/v1,两边各拼一次就是 /api/v1/api/v1/cms/attachments/...,而 FastAPI 只会回一句"接口不存在", 404 还要等用户点开那份附件才看得见(真出过一次)。

所以口径固定成两句话:

  • 往浏览器里写(<img>、<a>、fetch)用 buildApiUrl();
  • 往 http.* 里送用 trimAPIBase()(src/api/url.ts), utils/attachment.ts 的 locationOf() 与 supportAPI.previewAttachment() 已经这么做了。

apiClient 的请求拦截器还兜了一道 guardDoubledBase():新字段忘了收正也会被自动纠正 并在开发期 console.warn 喊一声,不至于变成静默 404。下载因此只有一条通道 (http.save / saveAttachment),网盘页与首页网盘面板各自手写的 fetch + 手动拼 Authorization 头已经收掉——那条路还额外漏掉了 X-Identity 与 401 静默续期。

10. 资讯附件与网盘文件复用同一套

「系统管理 → 信息发布」里传的附件走的是另一张表(oa_cms_attachment)、另一组路由 (/cms/attachments/...),但预览这层一点没重写:分类器、正文解析、mode: inline 与 mode: payload 的约定全部照用,只是把出口换成

GET /api/v1/cms/attachments/{id}/preview
GET /api/v1/cms/attachments/{id}/download?inline=1

序列化时一并回 download_url / preview_url,所以前端 utils/attachment.ts 与 FilePreviewDialog 不用关心这条附件挂在流程单据上、挂在一条资讯上,还是挂在网盘里—— 两边喂进去的形状一样(AttachmentItem)。资讯详情页还能把附件直接当正文摊开:图片直接 <img>、PDF 用 <iframe>、其余给一张能预览能下载的卡片。

网盘(oa_file,/api/v1/files/...)走的是同一件事:分类器、正文解析、 mode: inline / mode: payload 一律照用,只是出口换成

GET /api/v1/files/{id}/preview
GET /api/v1/files/{id}/download?inline=1

/download 从此认 inline=1,而预览取字节不涨 downloads——否则界面上 「点了五眼看一看」会显示成「下载过五次」。可见性沿用下载那一条(归属人 + 共享名单), 预览不该比下载多放行一个人。

11. 验收

python3 tests/oa_preview.py            # 分类表、编码、Word/Excel/PPT/CSV 解析、坏文件(离线,不连库)
python3 tests/oa_rich_annotation.py    # 上传与随附文件真落 MinIO、inline 预览、审批带图(自起隔离实例)
cd frontend && pnpm test:run