hl-api-changelog/changelogs/2026-05/07_fix_product_equipment-template-bind-product-line.md

后端 BUG 修复 — 装备建议组合 绑定层级 product_supplement → product_line

日期: 2026-05-07 类型: 后端 BUG 修复（admin 后台 + 小程序） 模块: 产品管理（产品线 / 主题）+ 装备建议组合 通知: @mmg 关联: PR #1782 + PR #1786 (hotfix)，Closes #1777 测试服: dev 已部署 + round-trip 验收 PASS 前端是否需改动: ✅ 必改（API 契约 break，前后端必须同步上线）

---

背景

PR #1768（2026-05-06）实现「装备建议组合模板 + 产品绑定」时，把 equipment_template_id 加在 product_supplement 表（每个版本独立绑一个模板）。

业务正确做法：装备需求由目的地、季节、产品类型决定 —— 这些都是**产品线（主题）**层级属性。同主题下不同版本（如「短途版」「南线经典」）只在行程时长、价格、班期上差异，装备需求几乎一致。一主题一份装备建议是合理粒度，运营不必每开新版本都重选模板。

PR #1782 把绑定层级从 product_supplement（版本）下沉到 product_line（主题）。

---

前端改动清单

1. 主题（产品线）创建/编辑表单 — 新增「装备建议组合」字段

项	值
字段名	equipmentTemplateId
类型	Long（前端传字符串数字也接受）
必填	否（可选）
label	装备建议组合
控件	下拉框（搜索/清除）
选项数据	GET /admin-api/admin/equipment-template/enabled （已就绪，返 EquipmentTemplateSimpleRespVO[]，含 templateId/name）
表单回显	GET /admin-api/admin/product/line/{lineId} 返回的 equipmentTemplateId 字段
保存接口	POST /admin-api/admin/product/line（创建/更新统一入口） body 含 equipmentTemplateId（取消绑定传 null，已通过 hotfix PR #1786 修复 null 落库 BUG）

特殊提示展示：当 equipmentTemplateId != null && equipmentTemplateName == null 时（模板被软删），展示提示「该装备建议组合已删除，请重新选择」。

2. 版本编辑 Step5 表单 — 移除「装备建议组合」字段

ProductSupplementSaveReqVO.equipmentTemplateId 已删；/admin-api/admin/product/{productId}/step5 提交即使带上该字段也会被静默忽略。请前端表单直接移除该字段，避免误导用户以为版本级也能配。

3. 版本详情 — supplement.equipmentTemplateId/Name 已删

/admin-api/admin/product/{productId} 详情接口的 supplement 节点不再返 equipmentTemplateId/Name。如版本详情页面需要展示装备建议，从主题（产品线）详情接口拿（GET /admin-api/admin/product/line/{lineId}）。

4. 模板 CRUD 入口位置（建议）

当前位置：「产品 → 主题列表」工具栏「装备建议组合」按钮（PR #1768 引入）。

建议新位置：「系统管理 → 模板管理 / 数据字典」之类全局入口（理由：装备建议组合是全局共享资源，不挂在任何产品维度下；与「合同方案」「保险方案」「行程保障模板」「温馨提示」类一致）。

具体放哪由前端拍板，不影响后端。

5. 小程序端 — 透明（无需改）

GET /mp/product/{productId} 详情接口的 equipmentList 字段语义不变；后端实现已切到 product → line → equipmentTemplateId，三态规则保留：

• 主题绑模板 → 返模板 items
• 主题未绑 / 模板软删 → fallback supplement.equipmentList（版本自定义）

---

API 字段差异（前后端对账）

新增字段（主题相关 VO）

接口	VO	字段	类型	说明
POST/PUT /admin/product/line	ProductLineSaveReqVO	equipmentTemplateId	Long 可选	装备建议组合模板 ID；null 取消绑定
GET /admin/product/line/{id}	ProductLineRespVO	equipmentTemplateId	Long	同上
GET /admin/product/line/{id}	ProductLineRespVO	equipmentTemplateName	String	模板名称回显（模板软删时为 null）
GET /admin/product/line/list	ProductLineRespVO（列表项同 VO）	同上两字段	—	已批量回填（不 N+1）

删除字段（版本相关 VO）

接口	VO	字段	处理
POST/PUT /admin/product/{id}/step5	ProductSupplementSaveReqVO	equipmentTemplateId	删除；前端表单需移除
GET /admin/product/{id}	ProductDetailRespVO.SupplementVO	equipmentTemplateId	删除
GET /admin/product/{id}	ProductDetailRespVO.SupplementVO	equipmentTemplateName	删除

---

后端验收实测（测试服 dev round-trip PASS）

验收项	实测
网关 /admin/equipment-template/** 路由	hl-gateway dev 已部署
取消绑定 (equipmentTemplateId=null) 落库	hotfix PR #1786 后 PASS（FieldStrategy.IGNORED 注解）
列表回填 templateName	PASS（中文非 null）
mp 详情三态 fallback	PASS
模板更新反向清缓存	PASS（前后两次 GET 反映 items 变化）
模板被引用拒绝软删	PASS（code 440102）
不存在 templateId 校验	PASS（code 440103）

---

上线时序（前后端协同）

后端 dev 已合 + 测试服已部署 + round-trip 通过。前端必须同步上线，否则：

• 主题创建/编辑表单缺「装备建议组合」字段 → 运营无法配置主题级装备建议
• 版本编辑 Step5 表单仍显示「装备建议组合」字段 → 提交时被静默忽略，误导

正式服由运维管理员部署 hl-product-service-v2 + hl-gateway（PR #1782 + PR #1770）+ hl-ui（前端发版后）。

@mmg 请评估前端改动量并约一个上线时间。