产品模块 Categories（类别）接口对接说明（美国版）

概述

本模块用于平台端（H5）Products → Categories 页签的数据对接。

• 模块：food-labeling-us
• 接口前缀：宿主统一前缀为 /api/app
• 分类表：fl_product_category
• 关联字段：fl_product.category_id → fl_product_category.id
• 图片字段：CategoryPhotoUrl（前端字段：categoryPhotoUrl）

说明：本文以 Swagger 为准（本地示例：http://localhost:19001/swagger，搜索 ProductCategory）。

---

接口 1：类别分页列表

HTTP

• 方法：GET
• 路径：/api/app/product-category
• 鉴权：需要登录（Header：Authorization: Bearer {token}）

入参（Query 参数）

参数名	类型	必填	说明
skipCount	number	是	跳过条数（分页）
maxResultCount	number	是	每页条数（分页）
sorting	string	否	排序字段（如 OrderNum desc），不传则按 OrderNum desc, CreationTime desc
keyword	string	否	模糊搜索（匹配 CategoryCode/CategoryName）
state	boolean	否	启用状态过滤

请求示例

GET /api/app/product-category?skipCount=0&maxResultCount=10&keyword=Prep HTTP/1.1
Host: localhost:19001
Authorization: Bearer eyJhbGciOi...

出参（PagedResultWithPageDto）

字段	类型	说明
pageIndex	number	当前页（从 1 开始）
pageSize	number	每页条数
totalCount	number	总数
totalPages	number	总页数
items	array	当前页数据

items[] 字段：

字段	类型	说明
id	string	主键
categoryCode	string	类别编码
categoryName	string	类别名称
categoryPhotoUrl	string \	null
state	boolean	是否启用
orderNum	number	排序
lastEdited	string	最后编辑时间

响应示例

{
  "pageIndex": 1,
  "pageSize": 10,
  "totalCount": 1,
  "totalPages": 1,
  "items": [
    {
      "id": "a2696b9e-2277-11f1-b4c6-00163e0c7c4f",
      "categoryCode": "CAT_PREP",
      "categoryName": "Prep",
      "categoryPhotoUrl": "/picture/category/20260325123010_xxx.png",
      "state": true,
      "orderNum": 100,
      "lastEdited": "2026-03-25 12:30:10"
    }
  ]
}

---

接口 2：类别详情

HTTP

• 方法：GET
• 路径：/api/app/product-category/{id}

请求示例

GET /api/app/product-category/a2696b9e-2277-11f1-b4c6-00163e0c7c4f HTTP/1.1
Host: localhost:19001
Authorization: Bearer eyJhbGciOi...

响应示例（ProductCategoryGetOutputDto）

{
  "id": "a2696b9e-2277-11f1-b4c6-00163e0c7c4f",
  "categoryCode": "CAT_PREP",
  "categoryName": "Prep",
  "categoryPhotoUrl": "/picture/category/20260325123010_xxx.png",
  "state": true,
  "orderNum": 100
}

---

接口 3：新增类别

HTTP

• 方法：POST
• 路径：/api/app/product-category
• Content-Type：application/json

入参（Body JSON：ProductCategoryCreateInputVo）

字段	类型	必填	说明
categoryCode	string	是	类别编码（唯一）
categoryName	string	是	类别名称（唯一）
categoryPhotoUrl	string \	null	否
state	boolean	否	是否启用（默认 true）
orderNum	number	否	排序（默认 0）

请求示例

{
  "categoryCode": "CAT_PREP",
  "categoryName": "Prep",
  "categoryPhotoUrl": "/picture/category/20260325123010_xxx.png",
  "state": true,
  "orderNum": 100
}

---

接口 4：编辑类别

HTTP

• 方法：PUT
• 路径：/api/app/product-category/{id}
• Content-Type：application/json

请求示例

{
  "categoryCode": "CAT_PREP",
  "categoryName": "Prep",
  "categoryPhotoUrl": "/picture/category/20260325123010_xxx.png",
  "state": true,
  "orderNum": 100
}

---

接口 5：删除类别（逻辑删除）

HTTP

• 方法：DELETE
• 路径：/api/app/product-category/{id}

约束

• 若该类别已被 fl_label 引用（fl_label.LabelCategoryId = id），删除会失败并返回友好提示：该类别已被标签引用，无法删除。

请求示例

DELETE /api/app/product-category/a2696b9e-2277-11f1-b4c6-00163e0c7c4f HTTP/1.1
Host: localhost:19001
Authorization: Bearer eyJhbGciOi...

---

配套：类别图片上传接口

类别图片上传接口见文档：

• 项目相关文档/平台端Categories图片上传接口说明.md

推荐前端流程：

1. 调用上传接口 POST /api/app/picture/category/upload 拿到响应 url
2. 新增/编辑类别时把 categoryPhotoUrl 设为该 url