王明 / Food-Labeling-Management-Platform

标签模块接口对接说明.md 11.5 KB

概述

美国版后端采用 ABP 动态接口（ConventionalControllers），宿主统一前缀为 api/app。 Swagger 地址：

  • http://localhost:19001/swagger

说明：

  • 接口最终 URL 以 Swagger 展示为准（可在 Swagger 里搜索 LabelCategory / LabelType / LabelMultipleOption / LabelTemplate / Label）。
  • 本模块后端接口以各 AppService 的方法签名自动暴露。
  • 返回分页统一包含 PageIndex / PageSize / TotalCount / TotalPages / Items。

Swagger 中如何找到

  1. 启动后端宿主（Yi.Abp.Web），端口 19001。
  2. 打开 http://localhost:19001/swagger。
  3. 在接口分组里搜索以下关键词之一：
    • label-category
    • label-type
    • label-multiple-option
    • label-template
    • label

接口 1：Label Categories（标签分类）

1.1 分页列表

方法：GET /api/app/label-category

入参（LabelCategoryGetListInputVo，查询参数）：

  • skipCount（int）
  • maxResultCount（int）
  • sorting（string，可选）
  • keyword（string，可选）
  • state（boolean，可选）

示例（查询参数）：

{
  "skipCount": 0,
  "maxResultCount": 10,
  "keyword": "Prep",
  "state": true
}

1.2 详情

方法：GET /api/app/label-category/{id}

入参：

  • id：分类 Id（字符串）

1.3 新增

方法：POST /api/app/label-category

入参（Body：LabelCategoryCreateInputVo）：

{
  "categoryCode": "CAT_PREP",
  "categoryName": "Prep",
  "categoryPhotoUrl": "https://cdn.example.com/cat-prep.png",
  "state": true,
  "orderNum": 1
}

1.4 编辑

方法：PUT /api/app/label-category/{id}

入参（Body：LabelCategoryUpdateInputVo，字段同创建）：

{
  "categoryCode": "CAT_PREP",
  "categoryName": "Prep",
  "categoryPhotoUrl": null,
  "state": true,
  "orderNum": 2
}

1.5 删除（逻辑删除）

方法：DELETE /api/app/label-category/{id}

入参：

  • id：分类 Id（字符串）

删除校验：

  • 若该分类已被 fl_label 引用，则抛出友好错误，禁止删除。

接口 2：Label Types（标签类型）

2.1 分页列表

方法：GET /api/app/label-type

入参（LabelTypeGetListInputVo，查询参数）：

{
  "skipCount": 0,
  "maxResultCount": 10,
  "keyword": "Defrost",
  "state": true
}

2.2 详情

方法：GET /api/app/label-type/{id}

入参：

  • id：类型 Id（字符串）

2.3 新增

方法：POST /api/app/label-type

入参（Body：LabelTypeCreateInputVo）：

{
  "typeCode": "TYPE_DEFROST",
  "typeName": "Defrost",
  "state": true,
  "orderNum": 1
}

2.4 编辑

方法：PUT /api/app/label-type/{id}

入参（Body：LabelTypeUpdateInputVo，字段同创建）：

{
  "typeCode": "TYPE_DEFROST",
  "typeName": "Defrost",
  "state": true,
  "orderNum": 2
}

2.5 删除（逻辑删除）

方法：DELETE /api/app/label-type/{id}

删除校验：

  • 若该类型已被 fl_label 引用，则禁止删除。

接口 3：Multiple Options（多选项字典）

3.1 分页列表

方法：GET /api/app/label-multiple-option

入参（LabelMultipleOptionGetListInputVo，查询参数）：

{
  "skipCount": 0,
  "maxResultCount": 10,
  "keyword": "Allergens",
  "state": true
}

3.2 详情

方法：GET /api/app/label-multiple-option/{id}

入参：

  • id：多选项 Id（字符串）

3.3 新增

方法：POST /api/app/label-multiple-option

入参（Body：LabelMultipleOptionCreateInputVo）：

{
  "optionCode": "OPT_ALLERGENS",
  "optionName": "Allergens",
  "optionValuesJson": ["Peanuts", "Dairy", "Gluten", "Soy"],
  "state": true,
  "orderNum": 1
}

3.4 编辑

方法：PUT /api/app/label-multiple-option/{id}

入参（Body：LabelMultipleOptionUpdateInputVo，字段同创建）：

{
  "optionCode": "OPT_ALLERGENS",
  "optionName": "Allergens",
  "optionValuesJson": ["Peanuts", "Dairy"],
  "state": true,
  "orderNum": 2
}

3.5 删除（逻辑删除）

方法：DELETE /api/app/label-multiple-option/{id}

接口 4：Label Templates（标签模板）

说明：

  • 模板标识入参 id 使用 fl_label_template.TemplateCode。
  • 创建/编辑的 Body 字段名对齐你前端 editor JSON（id/name/appliedLocation/elements/config）。

4.1 分页列表

方法：GET /api/app/label-template

入参（LabelTemplateGetListInputVo，查询参数）：

{
  "skipCount": 0,
  "maxResultCount": 10,
  "keyword": "测试模板",
  "locationId": "11111111-1111-1111-1111-111111111111",
  "labelType": "PRICE",
  "state": true
}

4.2 详情

方法：GET /api/app/label-template/{id}

入参：

  • id：模板编码 TemplateCode（字符串）

4.3 新增模板

方法：POST /api/app/label-template

入参（Body：LabelTemplateCreateInputVo）：

{
  "id": "TPL_TEST_001",
  "name": "测试模板-价格签(4x6)",
  "labelType": "PRICE",
  "unit": "inch",
  "width": 4,
  "height": 6,
  "appliedLocation": "ALL",
  "showRuler": true,
  "showGrid": true,
  "state": true,
  "elements": [
    {
      "id": "el-fixed-title",
      "type": "TEXT_STATIC",
      "x": 32,
      "y": 24,
      "width": 160,
      "height": 24,
      "rotation": "horizontal",
      "border": "none",
      "zIndex": 1,
      "orderNum": 1,
      "valueSourceType": "FIXED",
      "isRequiredInput": false,
      "config": {
        "text": "商品名",
        "fontFamily": "Arial",
        "fontSize": 14,
        "fontWeight": "bold",
        "textAlign": "left"
      }
    }
  ],
  "appliedLocationIds": []
}

说明：

  • 当 appliedLocation=SPECIFIED 时，appliedLocationIds 必须至少选择一个门店。

4.4 编辑模板

方法：PUT /api/app/label-template/{id}

入参：

  • Path：id 是当前模板编码（TemplateCode）
  • Body：字段同新增（id/name/elements/...）

示例（编辑：同样字段，appliedLocation 切到 SPECIFIED）：

{
  "id": "TPL_TEST_001",
  "name": "测试模板-价格签(4x6) v2",
  "labelType": "PRICE",
  "unit": "inch",
  "width": 4,
  "height": 6,
  "appliedLocation": "SPECIFIED",
  "showRuler": true,
  "showGrid": true,
  "state": true,
  "elements": [],
  "appliedLocationIds": ["11111111-1111-1111-1111-111111111111"]
}

版本：

  • VersionNo 会在编辑时自动 +1。
  • elements 会按传入内容全量重建。

4.5 删除（逻辑删除）

方法：DELETE /api/app/label-template/{id}

入参：

  • id：模板编码 TemplateCode

删除校验：

  • 若该模板已被 fl_label 引用，则禁止删除。

接口 5：Labels（按产品展示多个标签）

说明：

  • 列表接口按 ProductId 查询，一个产品会对应多条标签记录。
  • 标签详情/编辑/删除的 id 使用 fl_label.LabelCode。

5.1 分页列表（按产品）

方法：GET /api/app/label

入参（LabelGetListInputVo，查询参数）：

{
  "skipCount": 0,
  "maxResultCount": 10,
  "sorting": "",
  "keyword": "早餐",
  "locationId": "11111111-1111-1111-1111-111111111111",
  "productId": "22222222-2222-2222-2222-222222222222",
  "labelCategoryId": "33333333-3333-3333-3333-333333333333",
  "labelTypeId": "44444444-4444-4444-4444-444444444444",
  "templateCode": "TPL_TEST_001",
  "state": true
}

5.2 详情

方法：GET /api/app/label/{id}

入参：

  • id：标签编码 LabelCode

返回：

  • productIds：该标签绑定的产品Id 列表

5.3 新增标签

方法：POST /api/app/label

入参（Body：LabelCreateInputVo）：

{
  "labelCode": "LBL_TEST_001",
  "labelName": "早餐标签",
  "templateCode": "TPL_TEST_001",
  "locationId": "11111111-1111-1111-1111-111111111111",
  "labelCategoryId": "33333333-3333-3333-3333-333333333333",
  "labelTypeId": "44444444-4444-4444-4444-444444444444",
  "productIds": ["22222222-2222-2222-2222-222222222222"],
  "labelInfoJson": { "note": "测试标签1" },
  "state": true
}

校验：

  • productIds 至少 1 个
  • templateCode/locationId/labelCategoryId/labelTypeId 不能为空

5.4 编辑标签

方法：PUT /api/app/label/{id}

入参：

  • Path：id 为当前标签编码 LabelCode
  • Body：字段同创建（LabelUpdateInputVo）
{
  "labelName": "早餐标签 v2",
  "templateCode": "TPL_TEST_001",
  "locationId": "11111111-1111-1111-1111-111111111111",
  "labelCategoryId": "33333333-3333-3333-3333-333333333333",
  "labelTypeId": "44444444-4444-4444-4444-444444444444",
  "productIds": ["22222222-2222-2222-2222-222222222222"],
  "labelInfoJson": { "note": "测试标签1 v2" },
  "state": true
}

关联维护：

  • fl_label_product 会按新 productIds 重建。

5.5 删除标签（逻辑删除）

方法：DELETE /api/app/label/{id}

入参：

  • id：标签编码 LabelCode

删除行为：

  • 逻辑删除 fl_label
  • 删除该标签对应的 fl_label_product 关联

接口 6：Products（产品）

说明：

  • 产品表：fl_product
  • 删除为逻辑删除：IsDeleted = true

6.1 分页列表

方法：GET /api/app/product

入参（ProductGetListInputVo，查询参数）：

{
  "skipCount": 0,
  "maxResultCount": 10,
  "sorting": "",
  "keyword": "Chicken",
  "state": true
}

6.2 详情

方法：GET /api/app/product/{id}

入参：

  • id：产品Id（fl_product.Id）

6.3 新增产品

方法：POST /api/app/product

入参（Body：ProductCreateInputVo）：

{
  "productCode": "PRD_TEST_001",
  "productName": "Chicken",
  "categoryName": "Meat",
  "productImageUrl": "https://example.com/img.png",
  "state": true
}

校验：

  • productCode/productName 不能为空
  • productCode 不能与未删除的数据重复

6.4 编辑产品

方法：PUT /api/app/product/{id}

入参：

  • Path：id 为当前产品Id（fl_product.Id）
  • Body：字段同新增（ProductUpdateInputVo）

6.5 删除（逻辑删除）

方法：DELETE /api/app/product/{id}

入参：

  • id：产品Id

接口 7：Product-Location（门店-产品关联）

说明：

  • 关联表：fl_location_product
  • 关联按门店进行批量替换：
    • Create：在门店下新增未存在的 product 关联
    • Update：替换该门店下全部关联（先删后建）
    • Delete：删除该门店下全部关联

7.1 分页列表

方法：GET /api/app/product-location

入参（ProductLocationGetListInputVo，查询参数）：

{
  "skipCount": 0,
  "maxResultCount": 10,
  "sorting": "",
  "locationId": "11111111-1111-1111-1111-111111111111",
  "productId": "22222222-2222-2222-2222-222222222222"
}

7.2 获取门店下全部产品

方法：GET /api/app/product-location/{id}

入参：

  • id：门店Id（location.Id，string 表示）

返回：

  • 门店Id + 该门店关联的产品列表

7.3 新增/建立门店关联

方法：POST /api/app/product-location

入参（Body：ProductLocationCreateInputVo）：

{
  "locationId": "11111111-1111-1111-1111-111111111111",
  "productIds": ["22222222-2222-2222-2222-222222222222"]
}

校验：

  • locationId 对应门店必须存在
  • productIds 必须都存在于 fl_product 且未删除

7.4 编辑/替换门店关联

方法：PUT /api/app/product-location/{id}

入参：

  • Path：id 为门店Id
  • Body：ProductLocationUpdateInputVo json { "productIds": ["22222222-2222-2222-2222-222222222222"] }

7.5 删除门店关联（按门店删除全部）

方法：DELETE /api/app/product-location/{id}

入参：

  • id：门店Id