# 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 启动时自动创建。