本次接口变更汇总（标签 / 产品类别 / 模板组件 / App 树 / Web 会话）

说明：本文只汇总本次迭代中相关内容：

• 标签模块 Label Categories：对齐“新增类别”原型图（buttonAppearance + categoryPhotoUrl / 展示文案 / 门店范围）
• 产品模块 Categories：对齐“新增产品类别”原型图（同上）
• 模板组件（fl_label_template_element）：新增字段 TypeAdd（并补齐 ElementName）
• App labeling-tree：L1 标签分类返回 buttonAppearance
• Web 管理端 auth-session：当前用户菜单与权限、退出登录（食品标签-美国版模块）
• Web rbac-menu 列表/详情：补充返回 routerName、router
• 产品 Products：POST/PUT /api/app/product 支持可选 Body 字段 locationIds（多门店批量绑定 / 编辑时整表替换关联），详见 项目相关文档/标签模块接口对接说明.md §6

其余标签打印相关接口不在本文范围内。

---

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：JSON 格式字符串落库（如 ["TEXT","COLOR"]、["IMAGE"]）；兼容历史单行 TEXT/COLOR/IMAGE（保存时规范为 JSON 数组）
  • CategoryPhotoUrl：JSON 格式字符串落库（展示数据由前端解析）；非 JSON 纯文本（色值、URL 等）保存时会被后端包成 JSON 字符串
  • 已删除列（需在库上执行 DROP COLUMN）：ButtonTextColor、ButtonBgColor、ButtonImageUrl、ButtonStyleJson
  • AvailabilityType：ALL/SPECIFIED（门店可用范围）
• fl_product_category_location（关联表）：
  • (CategoryId, LocationId) 唯一约束；用于 AvailabilityType=SPECIFIED 指定门店

2.2 CRUD 接口（字段扩展）

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

2.2.1 列表

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

2.2.2 详情

• 方法：GET
• 路径：/api/app/product-category/{id}
• 新增返回字段：
  • displayText
  • buttonAppearance、categoryPhotoUrl（JSON 格式字符串，展示语义由前端解析）
  • availabilityType
  • locationIds（当 availabilityType=SPECIFIED 返回门店 Id 列表，否则为空数组）

2.2.3 新增

• 方法：POST
• 路径：/api/app/product-category
• 新增入参字段：
  • displayText
  • buttonAppearance、categoryPhotoUrl
  • 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：须为 合法 JSON（任意对象/数组），或为兼容的 TEXT/COLOR/IMAGE 单行；其它字符串拒绝。categoryPhotoUrl 非空且非 JSON 时后端会序列化为 JSON 字符串存储；是否必填由业务/前端约定

---

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

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

3.1 表结构要点

• fl_label_category（主表）关键字段：
  • DisplayText：按钮展示文案（为空可回退 CategoryName）
  • ButtonAppearance：JSON 格式字符串落库（如 ["TEXT","COLOR"]、["IMAGE"]）；兼容历史单行 TEXT/COLOR/IMAGE（保存时规范为 JSON 数组）
  • CategoryPhotoUrl：JSON 格式字符串落库（展示数据由前端解析）；非 JSON 纯文本（色值、URL 等）保存时会被后端包成 JSON 字符串
  • 已删除列（需在库上执行 DROP COLUMN）：ButtonTextColor、ButtonBgColor、ButtonImageUrl、ButtonStyleJson
  • 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
  • categoryPhotoUrl
  • availabilityType

3.2.2 详情

• 方法：GET
• 路径：/api/app/label-category/{id}
• 新增返回字段：
  • displayText
  • buttonAppearance、categoryPhotoUrl（JSON 格式字符串，展示语义由前端解析）
  • availabilityType
  • locationIds（当 availabilityType=SPECIFIED 返回门店 Id 列表，否则为空数组）

3.2.3 新增

• 方法：POST
• 路径：/api/app/label-category
• 新增入参字段：
  • displayText
  • buttonAppearance、categoryPhotoUrl
  • 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：须为 合法 JSON（任意对象/数组），或为兼容的 TEXT/COLOR/IMAGE 单行；其它字符串拒绝。categoryPhotoUrl 非空且非 JSON 时后端会序列化为 JSON 字符串存储；是否必填由业务/前端约定

---

4. App 端 GET /api/app/us-app-labeling/labeling-tree

• L1（标签分类）节点：返回 categoryPhotoUrl、buttonAppearance（均为库中字符串，多为 JSON，与 CRUD 一致）；缺省或空时 buttonAppearance 后端默认 "TEXT"（兼容旧数据，不再对整段做 ToUpperInvariant 以免破坏 JSON）。
• L2（产品分类）节点：返回 displayText、buttonAppearance、categoryPhotoUrl、availabilityType、orderNum 等；外观数据由 buttonAppearance + categoryPhotoUrl 承载（已不再返回 buttonTextColor、buttonBgColor、buttonImageUrl、buttonStyleJson）。

4.1 数据库迁移（两张主表）

在确认历史数据已按需迁到 CategoryPhotoUrl 后，可执行（列不存在时需跳过或调整）：

ALTER TABLE `fl_label_category`
  DROP COLUMN `ButtonTextColor`,
  DROP COLUMN `ButtonBgColor`,
  DROP COLUMN `ButtonImageUrl`,
  DROP COLUMN `ButtonStyleJson`;

ALTER TABLE `fl_product_category`
  DROP COLUMN `ButtonTextColor`,
  DROP COLUMN `ButtonBgColor`,
  DROP COLUMN `ButtonImageUrl`,
  DROP COLUMN `ButtonStyleJson`;

---

5. Web 管理端会话（AuthSession / 食品标签-美国版）

实现：IAuthSessionAppService / AuthSessionAppService。需携带与后台一致的 JWT（Authorization: Bearer {token}）。具体 action 路径以部署环境 Swagger / OpenAPI 为准；下列为 ABP 常规约定（RootPath = api/app）。

5.1 获取当前登录用户菜单与权限

• 方法：GET
• 路径（约定）：/api/app/auth-session/my-menus
• 鉴权：需要登录
• 用途：前端动态路由、侧边栏、按钮级权限（permissionCodes）
• 返回体（CurrentUserMenuPermissionsOutputDto，JSON 字段名为 camelCase）：

字段	类型	说明
user	object	当前用户简要信息（无密码）
user.id	guid	用户 Id
user.userName	string	登录名
user.nick	string?	昵称
user.email	string?	邮箱
user.icon	string?	头像
roleCodes	string[]	角色编码列表（已排序）
permissionCodes	string[]	权限码列表（已排序；超级管理员常见为 *:*:*）
menus	array	菜单树（根节点列表，子节点在 children）

菜单树节点（CurrentUserMenuNodeDto）主要字段：

字段	说明
id / parentId	菜单 Id、父 Id（根父级多为 "0"）
menuName	菜单名称
routerName / router	路由名、路径
permissionCode	权限标识（按钮/接口控制用）
menuType / menuSource	枚举整型值（与 Menu 表一致）
orderNum / state	排序、是否启用
menuIcon / component / isLink / isCache / isShow / query / remark	与菜单表一致
children	子节点数组

业务说明：

• 数据来源与框架 UserManager.GetInfoAsync 一致：按用户角色合并菜单与权限码。
• 用户名为 admin 时：与 AccountService.GetVue3Router 对齐，返回 Menu 表中未逻辑删除 的全部菜单再组树（permissionCodes 仍为超级管理员约定值）。

5.2 退出登录

• 方法：POST
• 路径（约定）：/api/app/auth-session/logout
• 鉴权：需要登录（未登录或无法解析用户时返回 false）
• 请求体：无
• 返回：boolean
  • true：已清除服务端 用户信息分布式缓存（与 AccountService.PostLogout 一致）
  • false：当前请求未识别到用户 Id（例如未登录）
• 说明：JWT 为无状态令牌，前端仍需丢弃本地 Token；退出接口主要清理服务端缓存侧用户信息。

---

6. 权限菜单 rbac-menu 列表/详情补充字段

• 路径：GET /api/app/rbac-menu（列表）、GET /api/app/rbac-menu/{id}（详情）
• 新增返回（与 menu 表字段一致，JSON 一般为 camelCase）：
  • routerName：路由名称
  • router：路由路径
• 说明：树接口 GET /api/app/rbac-menu/tree（若已使用）本身已包含完整菜单字段，无需重复改动。