## 概述

美国版后端采用 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，可选）

示例（查询参数）：

```json
{
  "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`）：

```json
{
  "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`，字段同创建）：

```json
{
  "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`，查询参数）：

```json
{
  "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`）：

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

### 2.4 编辑

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

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

```json
{
  "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`，查询参数）：

```json
{
  "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`）：

```json
{
  "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`，字段同创建）：

```json
{
  "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`，查询参数）：

```json
{
  "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`）：

```json
{
  "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）：

```json
{
  "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`，查询参数）：

```json
{
  "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`）：

```json
{
  "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`）

```json
{
  "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`，查询参数）：
```json
{
  "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`）：
```json
{
  "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`，查询参数）：
```json
{
  "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`）：
```json
{
  "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