From c5f9bb1065aa538f0839e798f3d03551a7b26373 Mon Sep 17 00:00:00 2001
From: API Changelog Bot <changelog@hulalv.com>
Date: Thu, 7 May 2026 12:09:25 +0800
Subject: [PATCH] =?UTF-8?q?fix(product):=20=E8=A3=85=E5=A4=87=E5=BB=BA?=
 =?UTF-8?q?=E8=AE=AE=E7=BB=84=E5=90=88=20=E7=BB=91=E5=AE=9A=E5=B1=82?=
 =?UTF-8?q?=E7=BA=A7=20product=5Fsupplement=20=E2=86=92=20product=5Fline?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

PR #1782 + PR #1786 (hotfix), Closes #1777

@mmg 前端必改: 主题表单加 equipmentTemplateId 下拉, 版本 Step5 删该字段
---
 ...ct_equipment-template-bind-product-line.md | 107 ++++++++++++++++++
 1 file changed, 107 insertions(+)
 create mode 100644 changelogs/2026-05/07_fix_product_equipment-template-bind-product-line.md

diff --git a/changelogs/2026-05/07_fix_product_equipment-template-bind-product-line.md b/changelogs/2026-05/07_fix_product_equipment-template-bind-product-line.md
new file mode 100644
index 0000000..df51b51
--- /dev/null
+++ b/changelogs/2026-05/07_fix_product_equipment-template-bind-product-line.md
@@ -0,0 +1,107 @@
+# 后端 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 请评估前端改动量并约一个上线时间。