Files
zkxw/docs/superpowers/specs/2026-07-01-qc-work-order-attachment-export-design.md
T
2026-07-01 16:37:33 +08:00

194 lines
6.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 质检工单批量导出任务附件 — 设计文档
> 日期:2026-07-01
> 状态:待实现
> 范围:`web-admin` 【质检工单】【我的质检任务】
> 已确认:**方案 A — 纯前端 JSZip 打包下载**
> 已确认:导出过程需**可见进度反馈**(任务较慢)
---
## 1. 背景与目标
### 1.1 业务需求
用户在【质检工单】或【我的质检任务】中勾选一条或多条质检工单,将该工单下**所有检测批次、所有质检任务**的附件打包为 ZIP 下载。
目录结构:
```
{工单}/
{批次}/
{任务}/
附件文件…
```
### 1.2 目标
1. 工单卡片支持多选(checkbox)。
2. 工具栏提供「导出附件」按钮(`btn-ghost` + Download 图标)。
3. 浏览器端聚合附件、按层级建目录、生成 ZIP 并触发下载。
4. 导出过程展示**进度弹窗**(阶段 + 百分比 + 当前文件名),避免用户误以为卡死。
### 1.3 非目标(一期不做)
- 后端流式 ZIP / 异步任务中心
- 跨分页保留勾选
- 工单级其他附件(诊断附件、样本接收附件等)
- 【我的质检任务】仅导出「本人负责任务」的子集模式(与 manage 一致,导出工单下全部任务附件)
---
## 2. 技术方案
### 2.1 方案选定:纯前端 JSZip
| 步骤 | 说明 |
|------|------|
| 1 | 收集已选 `workOrderId[]` |
| 2 | `POST /web/admin/qc-work-orders/inspection-batches/batch` 获取批次及内嵌 `tasks[].attachmentFiles` |
| 3 | 扁平化附件清单,计算 ZIP 内路径 |
| 4 | 逐个 `fetchAttachmentBlob`(预签名 URL)写入 JSZip |
| 5 | `zip.generateAsync({ type: 'blob' }, onUpdate)` 生成压缩包 |
| 6 | `FileSaver.saveAs` 下载 |
依赖:`jszip`、`file-saver`(已存在于 `package.json`)。
### 2.2 附件数据来源
- 表字段:`biz_qc_task.third_party_attachments`(逗号分隔 URL)
- API 字段:`attachmentFiles`(含 `fileUrl`、`fileName`)
- 实验室自检与第三方检测共用该字段
### 2.3 目录命名
| 层级 | 规则 |
|------|------|
| 工单 | `{workOrderNo}`;若重名追加 `_样本{sampleCode}` 等短标识 |
| 批次 | `{batchNo}_{batchName}`;无 `batchNo` 时用 `批次{orderNum}` |
| 任务 | `{taskNo}_{itemName}` |
| 文件 | 优先 `fileName`;同目录重名用 `(2)` 后缀 |
无附件的任务/批次不创建空目录。所选工单均无附件时提示「所选工单暂无附件」。
### 2.4 安全与权限
- 批次批量接口已受 `QC_TASK_READONLY_MENU_CODES` 与租户隔离约束。
- 两菜单共用实现;导出范围为工单下**全部任务**附件(非仅当前用户任务)。
---
## 3. 进度弹窗 UX(核心补充)
环境检测页的「批量下载附件」仅按钮 `loading`,无细粒度进度。本功能附件量大、耗时长,**必须**使用独立进度弹窗。
### 3.1 组件
新建:`web-admin/src/components/business/attachment-zip-progress-dialog/index.vue`
- `el-dialog`,`append-to-body`,`modal-class="protocol-dialog-mask"`(无背景模糊)
- `close-on-click-modal="false"`,`show-close="false"`(进行中不可点遮罩关闭)
- 宽度约 `480px`,单栏居中
### 3.2 三阶段进度
整体进度条 `0–100%`,按阶段加权:
| 阶段 | 权重 | 说明 |
|------|------|------|
| `preparing` | 0–5% | 请求批次/任务元数据 |
| `downloading` | 5–85% | 逐个拉取附件 blob 并 `zip.file()` |
| `zipping` | 85–100% | `generateAsync` 压缩(使用 JSZip `metadata.percent`) |
展示文案示例:
- 准备中:正在加载工单附件清单…
- 下载中:正在下载附件(12/48)— `报告.pdf`
- 压缩中:正在生成压缩包…
副文案:当前工单 `ZJGD…` / 批次 `首批检测`(可选,简短一行 `text-muted`)。
### 3.3 进度条
- `el-progress`:`stroke-width="8"`,`:percentage="overallPercent"`,`:status` 完成时 `success`
- 数字百分比与「已完成 N / 共 M 个文件」并列
### 3.4 完成与失败
| 结果 | 行为 |
|------|------|
| 全部成功 | 进度 100%,状态 success,1s 后自动关闭弹窗;`ElMessage.success('已打包下载 N 个附件')` |
| 部分失败 | 仍生成 ZIP(跳过失败项);关闭后 `ElMessage.warning('已下载 N 个,M 个失败')` |
| 全部失败 | 不下载;`ElMessage.error('附件下载失败,请稍后重试')` |
| 无附件 | 不打开进度弹窗;`ElMessage.warning('所选工单暂无附件')` |
### 3.5 取消
- 底部提供「取消」按钮(`Close` 图标 + 文案)
- 使用 `AbortController` 中断进行中的 `fetch`;设置 `cancelled` 标志跳过后续文件
- 取消后关闭弹窗,`ElMessage.info('已取消导出')`
- 已写入 ZIP 的 blob 丢弃,不触发 `saveAs`
### 3.6 并发与性能
- 附件下载**串行**(与环境检测一致),避免浏览器连接数耗尽;进度更准确
- 可选:限制单次最多 **50 个工单** 或 **500 个文件**,超出时 `ElMessageBox.confirm` 二次确认
---
## 4. 页面改动
### 4.1 勾选
在 `QcWorkOrderSingleCard` 卡片头部左侧增加 `el-checkbox`:
- `QcWorkOrderProtocolGroup` / `QcWorkOrderSampleGroup` 内每张工单卡片各自可勾选
- 状态由 `QcWorkOrderTabPanel` 持有:`selectedWorkOrderIds: Set<string>`
- 翻页或重新搜索时清空选择
### 4.2 工具栏
`QcWorkOrderTabPanel.vue` 在卡片列表上方增加(manage / mine 均显示):
```
已选 N 项 | [导出附件](btn-ghost,N=0 时 disabled)
```
### 4.3 逻辑抽离
| 文件 | 职责 |
|------|------|
| `@/utils/attachment-zip.ts` | 从 `env-detect-record` 抽出 `fetchAttachmentBlob`、`ensureUniqueZipEntryName`、`sanitizeZipPathSegment` |
| `@/utils/qc-work-order-attachment-export.ts` | 构建导出清单、ZIP 路径、`runQcWorkOrderAttachmentExport()` |
| `attachment-zip-progress-dialog` | 进度 UI |
| `useQcWorkOrderAttachmentExport.ts` | 组合 API + 进度回调 + 弹窗显隐 |
---
## 5. 接口
一期**不新增**后端接口,复用:
- `POST /web/admin/qc-work-orders/inspection-batches/batch`
- `POST /web/admin/attachment/download-url`
---
## 6. 测试要点
| # | 场景 | 预期 |
|---|------|------|
| 1 | 勾选 1 个工单,含多批次多任务附件 | ZIP 目录三层正确,文件可打开 |
| 2 | 勾选多个工单 | 根目录下多个工单文件夹 |
| 3 | 工单无附件 | 提示暂无附件,不弹进度窗 |
| 4 | 导出中取消 | 中断下载,无文件落盘 |
| 5 | 单个文件 404 | 其余正常打包,warning 提示失败数 |
| 6 | 【我的质检任务】与【质检工单】 | 行为一致 |
| 7 | 协议组 / 样本组 | 各工单独立勾选、导出 |
---
## 7. 后续演进
若生产反馈单次导出经常超过 500 文件或超时,再评估**方案 B**(后端 `StreamingResponse` ZIP)并保留相同目录规范与进度语义(改为轮询任务状态)。