# 平台端 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/命令行注意路径转义）：

```bash
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 | 文件大小（字节） |

### 响应示例

```json
{
  "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 字符串」约定。