Files
zkxw/docs/superpowers/specs/2026-07-01-attachment-drag-upload-design.md
T
2026-07-01 16:37:33 +08:00

235 lines
12 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
> 状态:待实现
> 需求来源:客户希望在保留「点击选择文件」的前提下,增加「拖拽文件到上传区」能力
> 已确认范围:**方案 1** — 仅附件类上传(类型 A + B + C);Logo/商品媒体/头像等(类型 D、E)留二期
---
## 1. 背景与目标
### 1.1 背景
`web-admin` 中约 30 个页面/组件使用 `fetchUploadAttachment` 实现附件上传,UI 以 OpenSpec「附件上传卡片化布局」为准(权威参考:`ProtocolFormDialog.vue`「协议附件」)。当前均仅支持点击 140×96 上传卡片触发文件选择,不支持拖拽。
### 1.2 目标
1. 在**不改变**现有点击上传交互的前提下,为方案 1 范围内所有上传区增加拖拽落文件能力。
2. 拖拽与点击共用同一套上传逻辑(校验 → 占位 → `fetchUploadAttachment` → 回填/失败移除)。
3. 按业务域**分批独立改造**,每批改完可单独回归,降低全站一次性改动风险。
### 1.3 非目标(一期不做)
- 单图/Logo 按钮上传(快递 Logo、站点图片、机构 Logo 等)
- 商品主图/轮播/详情媒体(`system/product`)
- 订单取消佐证 `picture-card`、用户头像
- 后端 API 变更
- 抽成全站统一 `AttachmentUploadField` 组件(本期各页独立加 drop 能力,避免大范围重构)
- 文件夹拖拽、剪贴板粘贴上传
---
## 2. 改造范围清单
### 2.1 类型 A — 页面内联卡片化附件(22 文件,约 33 个上传区)
| ID | 文件 | 上传区数 | 说明 |
|----|------|----------|------|
| A1 | `web-admin/src/views/cell-storage/protocol/ProtocolFormDialog.vue` | 2 | 协议附件、缴费凭证(`upload-card--sm`) |
| A2 | `web-admin/src/views/cell-storage/protocol-audit/PaymentInfoTab.vue` | 2 | 上传凭证、上传附件 |
| A3 | `web-admin/src/views/cell-storage/protocol-audit/StorageCertTab.vue` | 1 | 储存证附件 |
| A4 | `web-admin/src/views/cell-storage/protocol-audit/FullmoonTodoTab.vue` | 1 | 附件 |
| A5 | `web-admin/src/views/research-donation/list/DonationFormDialog.vue` | 2 | 两处附件 |
| A6 | `web-admin/src/views/quality-inspection/env-detect-record/index.vue` | 1 | 检测附件 |
| A7 | `web-admin/src/views/quality-inspection/storage-release-review/StorageReleaseReviewDialog.vue` | 1 | 审核附件 |
| A8 | `web-admin/src/views/production/sop/index.vue` | 1 | SOP 附件 |
| A9 | `web-admin/src/views/production/cell-product/index.vue` | 1 | 产品图片(卡片布局) |
| A10 | `web-admin/src/views/pilot-service/channel/index.vue` | 1 | 渠道协议附件 |
| A11 | `web-admin/src/views/pilot-service/channel/ChannelServiceOrderTab.vue` | 2 | 充值/退款附件 |
| A12 | `web-admin/src/views/pilot-service/channel-service-order/ServiceOrderTxnDialog.vue` | 1 | 流水附件 |
| A13 | `web-admin/src/views/pilot-service/channel-service-order-finance/index.vue` | 1 | 财务确认附件 |
| A14 | `web-admin/src/views/pilot-service/clinical-payment-confirm/index.vue` | 2 | 附件 ×2 |
| A15 | `web-admin/src/views/pilot-service/clinical-payment-confirm/RefundConfirmTab.vue` | 2 | 附件 ×2 |
| A16 | `web-admin/src/views/pilot-service/pilot-application/ApplicationFormDialog.vue` | 4 | 知情同意/诊断等 |
| A17 | `web-admin/src/views/pilot-service/pilot-application/ApplicationDetailDialog.vue` | 5 | 诊断/交付等(含非标准 `attachment-trigger-card` 样式,需对齐 drop 区) |
| A18 | `web-admin/src/views/pilot-service/pilot-application/ClinicalPaymentTab.vue` | 2 | 附件、退费附件 |
| A19 | `web-admin/src/views/pilot-service/outbound-release-review/OutboundReleaseReviewDialog.vue` | 1 | 审核附件 |
| A20 | `web-admin/src/views/pilot-service/infusion-schedule-management/InfusionScheduleHandoverDialog.vue` | 1 | 交接附件(与 C 类物料区并存) |
| A21 | `web-admin/src/views/pilot-service/checkup-management/CheckupDetailDialog.vue` | 1 | 上传报告 |
| A22 | `web-admin/src/views/pilot-service/checkup-management/CheckupMarkCheckedDialog.vue` | 1 | 上传报告 |
### 2.2 类型 B — `ProtocolFinanceConfirmFields` 共享组件(1 组件 + 6 消费页,约 8 个上传区)
| ID | 文件 | 上传区数 | 说明 |
|----|------|----------|------|
| B0 | `web-admin/src/components/business/protocol-finance-confirm-fields/index.vue` | 1 | **改组件即覆盖下列引用** |
| B1 | `web-admin/src/views/quality-inspection/sample-reception/index.vue` | 2 | 单条接收 + 批量接收 |
| B2 | `web-admin/src/views/cell-storage/payment-confirm/index.vue` | 1 | 确认收款附件 |
| B3 | `web-admin/src/views/cell-storage/payment-confirm/RefundConfirmTab.vue` | 1 | 退费财务附件 |
| B4 | `web-admin/src/views/cell-storage/payment-confirm/InvoiceRequestTab.vue` | 1 | 开票附件 |
| B5 | `web-admin/src/views/production/production-work-order/TaskPaperAttachmentsPanel.vue` | 1 | 线下纸质文档 |
| B6 | `web-admin/src/views/quality-inspection/qc-material/QcMaterialBatchAttachmentDialog.vue` | 1 | 质检附件 |
### 2.3 类型 C — 表格行内纸质材料(2 文件)
| ID | 文件 | 说明 |
|----|------|------|
| C1 | `web-admin/src/components/business/outbound-material-form-sections/index.vue` | 出库/交接物料弹窗复用;每行 `paper-att-card--trigger` |
| C2 | `web-admin/src/views/pilot-service/outbound-release-review/OutboundReleaseMaterialDialog.vue` | 独立实现同类行内上传,需与 C1 同步改法 |
**引用 C1 的页面(改 C1 后需回归)**:`OutboundReleaseMaterialDialog.vue`、`InfusionScheduleHandoverDialog.vue`(物料区)。
### 2.4 二期范围(本期不改)
类型 D(8 文件):`express`、`site`、`clean-room`、`cell-sample-type`、`insurance-company`、`checkup-institution`、`ThirdPartyCompanyTab`、`category`。
类型 E(3 文件):`system/product`、`system/order`、`UserProfileDialog`。
---
## 3. 交互与视觉规范
### 3.1 Drop Zone 范围
| 类型 | Drop Zone 元素 | 说明 |
|------|----------------|------|
| A / B | `.attachment-upload` 根容器 | 包含 `.attachment-list`(上传卡片 + 已传附件卡片)及下方 `.upload-hint` 所在整块区域 |
| C | 该行 `.paper-att-list` 或附件 cell 容器 | 行内空间较小,drop 高亮仅作用于当前行的附件列表 flex 区 |
**不采用** Element Plus `el-upload` 的 `drag` 大区域模式(会替换 slot、破坏 140×96 卡片布局)。
### 3.2 拖拽态视觉
在 `.attachment-upload` 上增加修饰类 `.is-dragover`(类型 C 对应 `.paper-att-list.is-dragover`):
- `border: 1px dashed #10b981`
- `background: #ecfdf5`
- `border-radius: 8px`
- 可选:`padding: 8px`(仅 dragover 时,避免布局跳动用 `outline` 或 `box-shadow` 代替 padding 亦可)
`.upload-hint` 默认文案追加:**「支持拖拽或点击上传」**(保留原有格式/大小限制说明)。
### 3.3 行为规则
1. **dragenter / dragover**:`preventDefault()`,设置 `is-dragover = true`(需在 `dragleave` 时判断 `relatedTarget` 仍在容器内再清除,避免闪烁)。
2. **drop**:`preventDefault()`,清除 `is-dragover`,读取 `event.dataTransfer.files`。
3. **多文件**:按文件顺序逐个调用与 `@change` 相同的上传处理(与 `:multiple="true"` 一致)。
4. **校验**:单文件 ≤ 20MB、`accept` 类型与现有点击上传一致;失败项 `ElMessage.error` 并跳过,不影响其他文件。
5. **重复文件**:与点击上传相同,依赖现有 `clearFiles` / 数组 push 逻辑。
6. **上传中**:dragover 期间若存在 `_uploading`,仍允许 drop(排队上传);提交拦截逻辑不变。
7. **禁用/只读**:只读态(如 `TaskPaperAttachmentsPanel` 的 `disabled`)不绑 drop 事件。
### 3.4 与 OpenSpec 关系
实现后 SHALL 在 `openspec/changes/zkxw-engineering-standards/specs/ui-conventions/spec.md`「附件上传卡片化布局」章节补充:
- Drop zone 为 `.attachment-upload`
- `.is-dragover` 视觉
- `.upload-hint` 文案含「拖拽或点击」
- 表格行内纸质材料 drop 区约定
---
## 4. 技术方案
### 4.1 推荐:轻量 composable + 各页独立挂载
新增 `web-admin/src/composables/useAttachmentDropZone.ts`(仅工具,非 UI 组件):
```ts
// 伪代码示意
export function useAttachmentDropZone(options: {
onFiles: (files: File[]) => void
disabled?: Ref<boolean>
}) {
const isDragover = ref(false)
// dragenter, dragleave, dragover, drop handlers
return { isDragover, dropZoneHandlers }
}
```
各页在 `.attachment-upload` 上:
```vue
<div
class="attachment-upload"
:class="{ 'is-dragover': isDragover }"
v-bind="dropZoneHandlers"
>
```
`onFiles` 内对每个 `File` 调用现有 `handleAttachmentChange({ raw: file })` 或等价函数。
**理由**:满足「每处独立修改」——各文件显式挂载 composable,diff 清晰;逻辑 DRY 但不引入新 Vue 组件,回归面可控。
### 4.2 类型 B 实施策略
改 `ProtocolFinanceConfirmFields` **一处**,对 B1–B6 做**全量回归**(视为独立一批 PR,不与 A 类混在同一 PR)。
### 4.3 类型 C 实施策略
在 `handlePaperAttachmentChange` 同级增加 drop 处理;drop zone 为行级 `.paper-att-list`。C1、C2 同批修改,并回归出库物料弹窗与输注交接弹窗。
### 4.4 全局样式(可选)
若多页重复 `.is-dragover` 样式,可在 `web-admin/src/assets/styles/core/app.scss` 增加:
```scss
.attachment-upload.is-dragover { ... }
.paper-att-list.is-dragover { ... }
```
各页 scoped 样式可省略重复定义。
---
## 5. 分批实施顺序
| 批次 | 范围 | 文件数 | 验收重点 |
|------|------|--------|----------|
| **0** | composable + 全局 dragover 样式 + OpenSpec 补充 | 2–3 | 单元/手工验证 composable |
| **1 试点** | A1 `ProtocolFormDialog` | 1 | 定稿交互,2 个上传区 |
| **2 细胞存储** | A2–A5 + B0 + B2–B4 | 6 + 组件 | 协议审核、付款确认、捐赠 |
| **3 质检** | A6–A7 + B1 + B6 | 4 + 组件已含 | 样本接收、环境检测、放行 |
| **4 中试上** | A10–A15 | 6 | 渠道、临床付款确认 |
| **5 中试下** | A16–A22 + C1–C2 | 9 + 2 | 临床申请、出库、体检、纸质材料 |
| **6 生产** | A8–A9 + B5 | 3 | SOP、细胞产品、工单纸质文档 |
每批:**仅改该批文件 → 手工测试 → 合并**,再进入下一批。
---
## 6. 测试要点(每批通用)
| 场景 | 预期 |
|------|------|
| 点击上传卡片选 1 个文件 | 与改前一致 |
| 拖拽 1 个合法文件到 upload 区 | 出现占位卡片 → 上传成功 → 可预览/下载/删除 |
| 拖拽多个文件 | 全部入队上传 |
| 拖拽超大文件(>20MB) | 提示错误,不上传 |
| 拖拽不支持类型 | 浏览器/业务校验拒绝或跳过 |
| dragover 视觉 | 进入区域高亮,离开恢复 |
| 上传中提交表单 | 仍提示「附件上传中,请稍候」 |
| 只读/禁用 | 无 drop 响应 |
---
## 7. 风险与缓解
| 风险 | 缓解 |
|------|------|
| 多文件 drop 与 `@change` 并发竞态 | 复用 `ProtocolFinanceConfirmFields` 已有 `_pendingList` 模式;A 类页面若存在竞态可参考 |
| `ApplicationDetailDialog` 样式不统一 | 该页单独测试 5 个上传区 |
| C1/C2 行内区域过小 | drop 高亮整行附件 flex 区,不要求拖到小卡片上 |
| 浏览器 dragleave 闪烁 | composable 内 counter 或 `relatedTarget` 检查 |
---
## 8. 相关文档
- OpenSpec:`openspec/changes/zkxw-engineering-standards/specs/ui-conventions/spec.md` §附件上传卡片化布局
- UI 规范:`docs/web-admin-ui-spec-fresh-mint.md`
- 权威参考页:`web-admin/src/views/cell-storage/protocol/ProtocolFormDialog.vue`
- 实施计划:`docs/superpowers/plans/2026-07-01-attachment-drag-upload.md`