feat(product): 装备建议组合可复用模板 + 产品设计绑定 (wx/HL #1768 / Closes wx/HL #1767)

@mmg

后端: hl-product-service-v2 新增 7 个 admin 接口 /admin/equipment-template
产品端 SaveReqVO 加 equipmentTemplateId, DetailRespVO.supplement 加 equipmentTemplateName
MP 端 GET /mp/product/{id} 三态渲染(绑模板优先实时取/软删 fallback/未绑用 equipment_list)
菜单挂"配置中心"分组,与安全保障/FAQ/行程保障模板并列

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

changelogs/2026-05/06_feat_product_equipment_template.md

@@ -0,0 +1,133 @@
+# 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 后台)
+
+新菜单「装备建议组合」放「配置中心」分组下,与「安全保障模板」「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 启动时自动创建。