平台端 Categories 图片上传接口说明

概述

平台端（H5）Products 模块的 Categories 页面，类别图片字段为 CategoryPhotoUrl（后端已在 fl_label_category 与分类 CRUD 接口中贯通）。

图片上传由 food-labeling-us 模块提供上传接口，文件会保存到服务器目录，并通过静态资源路径 /picture/... 直接访问。

---

接口：上传类别图片

HTTP

• 方法：POST
• 路径：/api/app/picture/category/upload
• Content-Type：multipart/form-data
• 鉴权：需要登录（Header：Authorization: Bearer {token}）

表单参数（multipart/form-data）

参数名	类型	必填	说明
file	file	是	图片文件
subDir	string	否	可选子目录（相对路径），例如 category、category/2026-03；禁止包含 ..

限制

• 大小：最大 5MB
• 格式：仅支持 jpg/jpeg/png/webp/gif
• 文件名策略：后端自动生成唯一文件名（避免覆盖）

请求示例（curl）

Windows（PowerShell/命令行注意路径转义）：

curl -X POST "http://localhost:19001/api/app/picture/category/upload" ^
  -H "Authorization: Bearer <token>" ^
  -F "file=@C:\\tmp\\category.png" ^
  -F "subDir=category"

请求示例（Postman/Apifox）

• 选择 POST
• URL：http://localhost:19001/api/app/picture/category/upload
• Headers：Authorization: Bearer <token>
• Body：form-data
  • Key=file，类型选 File，选择图片文件
  • Key=subDir，类型 Text，填 category（可选）

响应体（PictureUploadOutputDto）

字段	类型	说明
url	string	图片访问的相对路径，可直接保存到 CategoryPhotoUrl（例如：/picture/category/xxx.png）
fileName	string	服务器保存的文件名
size	number	文件大小（字节）

响应示例

{
  "url": "/picture/category/20260325123010_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.png",
  "fileName": "20260325123010_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.png",
  "size": 123456
}

---

文件保存位置与访问方式

落盘目录

后端会按环境自动选择落盘目录（不存在会自动创建）：

• 优先：/www/wwwroot/FoodLabelingManagementUs/picture
• 否则（Windows 本地开发）：<项目根>/wwwroot/FoodLabelingManagementUs/picture

访问 URL

静态资源映射为：

• GET /picture/{subDir}/{fileName}

举例：

• http://localhost:19001/picture/category/20260325123010_xxx.png

---

如何写入 Categories（CategoryPhotoUrl）

推荐前端流程：

1. 调用本上传接口，拿到返回的 url
2. 再调用分类新增/编辑接口，把 categoryPhotoUrl 设置为该 url

说明：分类 CRUD 已支持 CategoryPhotoUrl 字段；你只需要在页面表单里新增该字段即可。