12 KiB
附件与审批随附文件的预览设计
流程里上传的附件、审批意见随附的图片与文件,字节一律在 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 的活儿揽到自己身上
( 这类)。所以 /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