王明 / Food-Labeling-Management-Platform

平台端Categories图片上传接口说明.md 3.2 KB

平台端 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 采用 JSON 存展示数据，请将该 url 放入你方约定的 JSON 结构中。若仍传纯路径字符串，后端会序列化为 JSON 字符串再入库。
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. 再调用分类新增/编辑接口：按平台与 buttonAppearance（JSON 字符串） 的约定组装 categoryPhotoUrl（JSON）；或继续传纯 url 由后端自动包成 JSON 字符串。

说明：详见 项目相关文档/产品模块Categories接口对接说明.md、项目相关文档/标签模块接口对接说明.md 中「JSON 字符串」约定。