# 本次接口变更汇总（仅：标签类别 + 产品类别 + 模板组件字段）

> 说明：本文只汇总本次迭代中三块内容：
> - 标签模块 Label Categories：对齐“新增类别”原型图（按钮外观/展示文案/门店范围）
> - 产品模块 Categories：对齐“新增产品类别”原型图（按钮外观/展示文案/门店范围）
> - 模板组件（`fl_label_template_element`）：新增字段 `TypeAdd`（并补齐 `ElementName`）
>
> 其余标签打印相关接口不在本文范围内。

---

## 1. 模板组件字段（`fl_label_template_element`）

### 1.1 字段变更

- 新增字段：`TypeAdd`（元素附加类型，如 `label_Duration`）
- 新增字段：`ElementName`（元素名称，用于更稳定的显示/快照）

### 1.2 接口影响范围

- 模板新增/编辑：保存 `elements[].typeAdd` / `elements[].elementName`
- 模板详情/预览：返回 `elements[].typeAdd` / `elements[].elementName`

### 1.3 JSON 对齐（elements[]）

| 前端字段 | 后端字段 | 说明 |
|---|---|---|
| `type` | `ElementType` | 元素类型 |
| `typeAdd` | `TypeAdd` | 元素附加类型 |
| `elementName` | `ElementName` | 元素名称 |

---

## 2. 产品模块 Categories（Products → Categories）

> 数据库侧你已完成：`fl_product_category` 新字段、`fl_product_category_location` 新表。

### 2.1 表结构要点

- `fl_product_category`（主表）关键字段：
  - `DisplayText`：按钮展示文案（为空可回退 `CategoryName`）
  - `ButtonAppearance`：`TEXT/COLOR/IMAGE`
  - `ButtonTextColor` / `ButtonBgColor` / `ButtonImageUrl`
  - `ButtonStyleJson`：样式扩展 JSON（可选）
  - `AvailabilityType`：`ALL/SPECIFIED`（门店可用范围）
- `fl_product_category_location`（关联表）：
  - `(CategoryId, LocationId)` 唯一约束；用于 `AvailabilityType=SPECIFIED` 指定门店

### 2.2 CRUD 接口（字段扩展）

接口路径不变，仅扩展字段。

#### 2.2.1 列表

- **方法**：`GET`
- **路径**：`/api/app/product-category`
- **列表行新增返回**：
  - `displayText`
  - `buttonAppearance`
  - `availabilityType`

#### 2.2.2 详情

- **方法**：`GET`
- **路径**：`/api/app/product-category/{id}`
- **新增返回字段**：
  - `displayText`
  - `buttonAppearance/buttonTextColor/buttonBgColor/buttonImageUrl/buttonStyleJson`
  - `availabilityType`
  - `locationIds`（当 `availabilityType=SPECIFIED` 返回门店 Id 列表，否则为空数组）

#### 2.2.3 新增

- **方法**：`POST`
- **路径**：`/api/app/product-category`
- **新增入参字段**：
  - `displayText`
  - `buttonAppearance/buttonTextColor/buttonBgColor/buttonImageUrl/buttonStyleJson`
  - `availabilityType`
  - `locationIds`（当 `availabilityType=SPECIFIED` 必填且至少 1 个）

#### 2.2.4 编辑

- **方法**：`PUT`
- **路径**：`/api/app/product-category/{id}`
- **入参同新增**

#### 2.2.5 删除

- **方法**：`DELETE`
- **路径**：`/api/app/product-category/{id}`
- **说明**：逻辑删除；若被产品引用会阻止删除（保持原行为）

### 2.3 后端校验规则（本次新增）

- `availabilityType` 仅允许 `ALL/SPECIFIED`
  - `SPECIFIED` 时 `locationIds` 至少 1 个
- `buttonAppearance` 仅允许 `TEXT/COLOR/IMAGE`
  - `IMAGE` 时必须有 `buttonImageUrl`
  - `COLOR` 时必须有 `buttonBgColor`

---

## 3. 标签模块 Label Categories（Labels → Label Categories）

> 数据库侧新增：`fl_label_category` 新字段、`fl_label_category_location` 新表。

### 3.1 表结构要点

- `fl_label_category`（主表）关键字段：
  - `DisplayText`：按钮展示文案（为空可回退 `CategoryName`）
  - `ButtonAppearance`：`TEXT/COLOR/IMAGE`
  - `ButtonTextColor` / `ButtonBgColor` / `ButtonImageUrl`
  - `ButtonStyleJson`：样式扩展 JSON（可选）
  - `AvailabilityType`：`ALL/SPECIFIED`（门店可用范围）
- `fl_label_category_location`（关联表）：
  - `(CategoryId, LocationId)` 唯一约束；用于 `AvailabilityType=SPECIFIED` 指定门店（`LocationId` 对应 `location` 表主键）

### 3.2 CRUD 接口（字段扩展）

接口路径不变，仅扩展字段。

#### 3.2.1 列表

- **方法**：`GET`
- **路径**：`/api/app/label-category`
- **列表行新增返回**：
  - `displayText`
  - `buttonAppearance`
  - `availabilityType`

#### 3.2.2 详情

- **方法**：`GET`
- **路径**：`/api/app/label-category/{id}`
- **新增返回字段**：
  - `displayText`
  - `buttonAppearance/buttonTextColor/buttonBgColor/buttonImageUrl/buttonStyleJson`
  - `availabilityType`
  - `locationIds`（当 `availabilityType=SPECIFIED` 返回门店 Id 列表，否则为空数组）

#### 3.2.3 新增

- **方法**：`POST`
- **路径**：`/api/app/label-category`
- **新增入参字段**：
  - `displayText`
  - `buttonAppearance/buttonTextColor/buttonBgColor/buttonImageUrl/buttonStyleJson`
  - `availabilityType`
  - `locationIds`（当 `availabilityType=SPECIFIED` 必填且至少 1 个）

#### 3.2.4 编辑

- **方法**：`PUT`
- **路径**：`/api/app/label-category/{id}`
- **入参同新增**

#### 3.2.5 删除

- **方法**：`DELETE`
- **路径**：`/api/app/label-category/{id}`
- **说明**：逻辑删除；若被标签引用会阻止删除（保持原行为）

### 3.3 后端校验规则（本次新增）

- `availabilityType` 仅允许 `ALL/SPECIFIED`
  - `SPECIFIED` 时 `locationIds` 至少 1 个
- `buttonAppearance` 仅允许 `TEXT/COLOR/IMAGE`
  - `IMAGE` 时必须有 `buttonImageUrl`
  - `COLOR` 时必须有 `buttonBgColor`