upload-component-first

name	upload-component-first
description	MallBase Vben Admin 上传组件与字段契约规则；实现图片、视频或文件上传，以及处理 FileInfo 回填和提交值时使用。

Vben 规则：上传组件与字段契约

适用范围

frontend/admin/apps/web-antd 中的图片、视频和文件上传交互，以及编辑回填、预览和提交转换。

强制规则

1. 优先使用 #/components/upload/index.vue，禁止在业务页面重复实现上传或素材选择逻辑。
2. UI 状态使用 FileInfo；url 保存可提交值，full_url 仅用于预览，asset_id 保存素材 ID。
3. 新素材契约优先提交数值型 asset_id；只有真实后端接口明确接受存储路径时，才回退提交 url 字符串。
4. 后端字段类型是最终依据。商品媒体字段遵循 GoodsApi.MediaValue = number | string，其他模块不得未经核对直接照搬。
5. full_url、*_full_url 和前端拼接的完整地址不得作为持久化提交值。
6. 编辑回填使用后端返回的素材值与完整预览地址构造 FileInfo，不在页面硬编码域名。
7. 多图、排序或关联对象必须保留接口要求的数组/对象结构，不能统一粗暴转换成字符串数组。
8. 批量编辑若覆盖媒体字段，必须同时处理回填、预览和提交转换。

引入方式

import type { FileInfo } from '#/components/upload';
import Upload from '#/components/upload/index.vue';

用法示例

<!-- 单图上传 -->
<Upload v-model:value="formData.image" type="image" module="goods" />

<!-- 多图上传 -->
<Upload v-model:value="formData.images" type="images" module="goods" :max-count="10" />

<!-- 文件上传 -->
<Upload v-model:value="formData.file" type="file" module="setting" />

• v-model:value 单文件绑定类型通常为 FileInfo | string | undefined
• v-model:value 多文件绑定类型通常为 FileInfo[]
• module 指定上传模块（如 "goods"、"user" 等）

契约边界示例

function toMediaValue(file?: FileInfo | string): number | string {
  if (!file) return '';
  if (typeof file === 'string') {
    return /^\d+$/.test(file) ? Number(file) : file;
  }
  if (file.asset_id) return file.asset_id;
  return /^\d+$/.test(file.url) ? Number(file.url) : file.url;
}

该示例只适用于后端接受 number | string 的媒体字段。提交前仍需核对对应的 backend/route/api/admin/*.php、Controller/Service 校验和前端 API 类型。

禁止

• ❌ 使用 <a-input> 让用户手动输入图片 URL
• ❌ 手动实现图片上传逻辑
• ❌ 把 full_url 提交到只接受素材 ID 或存储路径的字段
• ❌ 看到 FileInfo.url 就假设它一定是文件路径

参考位置

• frontend/admin/apps/web-antd/src/components/upload/index.vue
• frontend/admin/apps/web-antd/src/components/upload/index.ts
• frontend/admin/apps/web-antd/src/views/goods/goods/composables/useGoodsEdit.ts
• frontend/admin/apps/web-antd/src/api/goods/goods.ts

自检清单

• 上传逻辑未重复造轮子。
• 回填对象包含可靠的提交值、预览地址和文件名。
• 素材 ID、兼容路径、单图/多图结构与真实后端契约一致。
• 提交数据不包含 full_url，保存后二次进入仍能稳定回显。