文件上传集成指南

概述

本系统使用 yudao-module-system 模块的 Storage API 作为统一的文件上传服务，支持多种存储方式（本地、S3/OSS）。

重要：所有业务模块必须使用 system 模块的 Storage API，**禁止使用 infra 模块的 /infra/file/* 接口，禁止为每个模块新增上传接口**。

一、通用接口

1.1 文件上传

方法	路径	说明
POST	`/system/storage-blob/upload`	通用文件上传

请求参数：files（MultipartFile 数组）

响应：

[
  {
    "id": 123,
    "resourceKey": "abc123",
    "contentType": "application/pdf",
    "originalFilename": "合同.pdf",
    "uidFilename": "u_abc123.pdf",
    "byteSize": 102400,
    "path": "/storage/2024/01/abc123.pdf",
    "previewURL": "https://xxx.com/preview/u_abc123.pdf",
    "url": "https://xxx.com/u_abc123.pdf",
    "name": "合同.pdf",
    "downloadURL": "https://xxx.com/download/u_abc123.pdf"
  }
]

1.2 附件绑定

方法	路径	说明
POST	`/system/storage-attachment/bind`	将已上传文件绑定到业务记录

请求参数：

参数	类型	必填	说明
application	String	否	文件用途，如 `file`
recordType	String	是	关联记录类型，如 `mes_purchase_order`
recordId	Long	是	关联记录 ID
blobItems	List<BlobItem>	是	待绑定文件列表

BlobItem：

参数	类型	必填	说明
blobId	Long	是	上传返回的文件 ID
application	String	否	覆盖外层的文件用途

1.3 查询附件列表

方法	路径	说明
GET	`/system/storage-attachment/list`	查询业务记录的附件

请求参数：

参数	类型	必填	说明
recordType	String	是	关联记录类型
recordId	Long	是	关联记录 ID
application	String	否	按用途过滤

1.4 删除附件

方法	路径	说明
DELETE	`/system/storage-attachment/delete`	批量删除附件

请求体：文件 ID 数组 [1, 2, 3]

二、前端集成

2.1 使用封装好的 API

import { bindAttachments, listAttachments, uploadFile } from '#/api/system/storage';

// 1. 上传文件
const handleUpload = async (file: File) => {
  const blobs = await uploadFile([file]);
  // 获取 blob ID
  const blobId = blobs[0]!.id;
  return blobId;
};

// 2. 绑定到业务记录
const handleBind = async (blobIds: number[], recordId: number) => {
  await bindAttachments({
    application: 'file',
    recordType: 'mes_pro_work_order',
    recordId,
    blobItems: blobIds.map(id => ({ blobId: id })),
  });
};

// 3. 查询附件列表
const handleLoad = async (recordId: number) => {
  const attachments = await listAttachments({
    recordType: 'mes_pro_work_order',
    recordId,
  });
  return attachments;
};

2.2 标准流程

用户选择文件 → 调用 POST /system/storage-blob/upload 上传
业务记录保存时 → 调用 POST /system/storage-attachment/bind 绑定附件到记录
详情/编辑页 → 调用 GET /system/storage-attachment/list 加载已有附件
用户删除附件 → 调用 DELETE /system/storage-attachment/delete

2.3 displayUpload 组件

项目中已有文件上传显示组件，可直接使用系统 Storage API。

三、recordType 命名规范

格式：{模块前缀}_{业务表名}

模块	recordType	说明
MES 采购订单	`mes_purchase_order`	采购订单附件
MES 工单	`mes_pro_work_order`	生产工单附件
MES 设备	`mes_dv_machinery`	设备档案附件
MES 文档	`mes_pd_document`	项目文档附件
CRM 客户	`crm_customer`	客户附件
ERP 产品	`erp_product`	产品附件

四、禁止行为

❌ 禁止调用 /infra/file/upload 或 /infra/file/presigned-url
❌ 禁止在 MES/CRM/ERP 等业务模块 Controller 新增 @PostMapping("/upload")
❌ 禁止注入 cn.iocoder.yudao.module.infra.api.file.FileApi
❌ 禁止使用旧版 src/api/infra/file/index.ts 中的 uploadFile() 函数

五、前端 API 模块位置

src/api/system/storage/index.ts

导出函数：uploadFile、listAttachments、bindAttachments、deleteAttachments

六、注意事项

使用通用接口：所有上传走 system 模块，通过 recordType 区分业务
上传后绑定：文件上传只是暂存，必须调用 bind 接口关联到业务记录
文件预览：使用响应中的 previewURL 或 url 字段
文件下载：使用 GET /system/storage-blob/download/{fileName}?token=xxx