hl-api-changelog/changelogs/2026-05/06_feat_product_equipment_template.md

feat(product): 装备建议组合可复用模板 + 产品设计绑定

日期: 2026-05-06 通知对象: @mmg (前端) 关联 PR: wx/HL #1768 关联工单: wx/HL #1767 (closed) 测试服部署: dev 已合并 commit 6c879da9,等自动部署 + /@qa round-trip(部署完后会在工单 #1767 下补 verification comment)

---

一、背景

产品编辑「补充信息→预订须知→装备建议」当前每个产品要逐条录入(≤20 条 文本+图标),重复劳动。新增可复用模板:运营在 admin 维护一份「装备建议组合」清单,产品设计时绑定 1 个组合,实时引用(模板修改 → 已绑产品 MP 详情自动跟随)。

---

二、后端新增接口(admin 端,7 个)

服务: hl-product-service-v2 (8083) · 网关 path: /admin/equipment-template

Method	Path	说明
POST	/admin/equipment-template	创建模板 (EquipmentTemplateSaveReqVO)
PUT	/admin/equipment-template/{id}	更新模板 (EquipmentTemplateSaveReqVO)
DELETE	/admin/equipment-template/{id}	软删 (被产品引用时返业务码 EQUIPMENT_TEMPLATE_IN_USE + 引用产品数)
PUT	/admin/equipment-template/{id}/status	切启用/停用 (EquipmentTemplateStatusReqVO)
GET	/admin/equipment-template/page?keyword=&status=&page=&pageSize=	分页查询
GET	/admin/equipment-template/{id}	详情
GET	/admin/equipment-template/enabled	启用项下拉(不分页,按 sort_order/template_id)

Request/Response 字段(关键)

EquipmentTemplateSaveReqVO:

• name: String (必填, 1-30 字, 全局未删重名禁建)
• items: List<EquipmentItem> (必填, 1-20 条, @Valid 嵌套校验)
  • text: String (必填, 1-50 字)
  • icon: String (必填, 前端约定短标识或完整 SVG XML, 长度 1-8000)
  • color: String (可选, 长度 ≤16, 如 #FFA726)
• sortOrder: Integer (可选, 默认 0, 越小越靠前)

EquipmentTemplateStatusReqVO:

• status: String (必填, ENABLED 或 DISABLED, @Pattern 校验)

EquipmentTemplateRespVO (详情/分页项):

• templateId: Long / name / items: List<EquipmentItem> / itemCount: Integer(衍生)/ status / statusLabel: String(中文启用/停用)/ sortOrder / createdBy: Long(仅 ID,首版不返姓名)/ createTime / updateTime

EquipmentTemplateSimpleRespVO (/enabled 下拉用):

• templateId / name / itemCount / status (4 字段)

---

三、产品端字段改动(前端必改)

1. 产品保存接口 PUT /admin/product/item/{id}/supplement

ProductSupplementSaveReqVO 新增字段:

• equipmentTemplateId: Long (可选, 非空时即绑定模板)

2. 产品详情接口 GET /admin/product/item/{id}

ProductDetailRespVO.supplement 新增字段:

• equipmentTemplateId: Long (当前绑定模板 ID)
• equipmentTemplateName: String (绑定模板的名字, 即使模板已停用也能显示, 前端可在下拉里给停用项加灰色 + "已停用"前缀)

3. 产品 Step5 三态 UI(关键)

状态	UI 行为
① 未绑模板 (equipmentTemplateId 为空)	现有 equipment_list 录入区可编辑(必填 ≥1 条,与现状一致)
② 绑模板	下方 equipment_list 录入区变只读预览, 展示模板的 items, 标注「来自组合 XX, 如需修改请去装备建议组合管理」;equipment_list 原值在 DB 里保留不清空(为③解绑后恢复用)
③ 解绑模板(下拉清空)	equipment_list 恢复可编辑, 显示原值(用户切换前的内容)

4. 模板下拉策略

• 默认仅显示 status=ENABLED 的模板, 按 sort_order, template_id 排序
• 若当前产品已绑模板, 即使该模板被停用, 也保留显示并标"已停用"前缀(用户可保留或换为启用项) — 此时前端用 equipmentTemplateName 渲染下拉文本

5. 必填规则

提交审核校验: 装备建议非空 = (equipmentTemplateId 非空 AND 模板未删) OR (equipment_list 非空) — 二选一

---

四、MP 端(小程序)行为(无新接口)

GET /mp/product/{id} 返回的 equipmentList 字段:

• 若 equipment_template_id 非空 AND 模板未软删 → 实时返回模板的 items(模板修改自动跟随,清缓存后 5 分钟内可见)
• 若模板被软删 → fallback 用 equipment_list(避免 MP 端报错)
• 若 equipment_template_id 为空 → 直接用 equipment_list(保持现状)
• equipmentAdvice 旧字段保留兼容,逻辑不变

订单详情边界: 订单生成时已固化 equipment_list 副本到订单快照, 订单详情永远走快照不读模板, 模板后续修改对已成订单 0 影响。

---

五、错误码(ProductTemplateErrorCode,段位 440000-449999)

Code	含义	触发场景
440101	EQUIPMENT_TEMPLATE_NAME_DUPLICATED	创建/更新时同名模板已存在(未软删)
440102	EQUIPMENT_TEMPLATE_IN_USE	删除时被 N 个产品引用,前端展示「已被 {N} 个产品绑定,请先解除绑定」
440103	EQUIPMENT_TEMPLATE_NOT_FOUND	模板不存在或已软删

---

六、入口挂载(admin 后台)

⚠️ 更正(2026-05-07 用户澄清):不是独立菜单,是在产品线页面(/product/line)右上角加「装备建议组合」按钮,点击打开管理面板/弹窗(列表 + 新增/编辑/启停/删除),复用后端 7 个 /admin/equipment-template/* 接口。

之前 changelog 写的「配置中心独立菜单 + 安全保障/FAQ/行程保障并列」作废 — 实际入口在产品线列表页内嵌按钮,管理面板不占独立路由。

---

七、不在范围(本期不做)

• 装备图标素材库化(继续保持前端约定)
• 模板适用产品类型筛选(applicable_types 列)
• 模板分类标签 / 适用季节
• 多组合叠加绑定
• 模板版本历史
• 模板创建人姓名(createdByName),首版仅返 createdBy: Long ID

---

八、需要重启的服务

• hl-product-service-v2 (8083) — 测试服部署 dev 后自动重启
• 其他服务无影响

---

九、本地启动需要的事(参考 PR #1065 会话隔离)

后端无需新 nacos 配置, Flyway 自动 apply V20260507_002 DDL。 equipment_template 表 + product_supplement.equipment_template_id 列在 product-v2 启动时自动创建。