本次新增与优化接口汇总(1).md
5.44 KB
本次接口变更汇总（仅：标签类别 + 产品类别 + 模板组件字段）
说明：本文只汇总本次迭代中三块内容：
- 标签模块 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/IMAGEButtonTextColor/ButtonBgColor/ButtonImageUrlButtonStyleJson：样式扩展 JSON（可选）AvailabilityType：ALL/SPECIFIED（门店可用范围）
fl_product_category_location（关联表）：(CategoryId, LocationId)唯一约束；用于AvailabilityType=SPECIFIED指定门店
2.2 CRUD 接口（字段扩展）
接口路径不变，仅扩展字段。
2.2.1 列表
- 方法：
GET - 路径：
/api/app/product-category - 列表行新增返回：
displayTextbuttonAppearanceavailabilityType
2.2.2 详情
- 方法：
GET - 路径：
/api/app/product-category/{id} - 新增返回字段：
displayTextbuttonAppearance/buttonTextColor/buttonBgColor/buttonImageUrl/buttonStyleJsonavailabilityTypelocationIds（当availabilityType=SPECIFIED返回门店 Id 列表，否则为空数组）
2.2.3 新增
- 方法：
POST - 路径：
/api/app/product-category - 新增入参字段：
displayTextbuttonAppearance/buttonTextColor/buttonBgColor/buttonImageUrl/buttonStyleJsonavailabilityTypelocationIds（当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/SPECIFIEDSPECIFIED时locationIds至少 1 个
buttonAppearance仅允许TEXT/COLOR/IMAGEIMAGE时必须有buttonImageUrlCOLOR时必须有buttonBgColor
3. 标签模块 Label Categories（Labels → Label Categories）
数据库侧新增：
fl_label_category新字段、fl_label_category_location新表。
3.1 表结构要点
fl_label_category（主表）关键字段：DisplayText：按钮展示文案（为空可回退CategoryName）ButtonAppearance：TEXT/COLOR/IMAGEButtonTextColor/ButtonBgColor/ButtonImageUrlButtonStyleJson：样式扩展 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 - 列表行新增返回：
displayTextbuttonAppearanceavailabilityType
3.2.2 详情
- 方法：
GET - 路径：
/api/app/label-category/{id} - 新增返回字段：
displayTextbuttonAppearance/buttonTextColor/buttonBgColor/buttonImageUrl/buttonStyleJsonavailabilityTypelocationIds（当availabilityType=SPECIFIED返回门店 Id 列表，否则为空数组）
3.2.3 新增
- 方法：
POST - 路径：
/api/app/label-category - 新增入参字段：
displayTextbuttonAppearance/buttonTextColor/buttonBgColor/buttonImageUrl/buttonStyleJsonavailabilityTypelocationIds（当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/SPECIFIEDSPECIFIED时locationIds至少 1 个
buttonAppearance仅允许TEXT/COLOR/IMAGEIMAGE时必须有buttonImageUrlCOLOR时必须有buttonBgColor