# 管理端产品编辑 Step5: 装备建议增加「从模板选择」快速填充按钮（前端任务，后端已就绪）

> **服务**: hl-product-service-v2 (端口 8083)
> **PR**: 无（纯前端，后端 0 改动）
> **Issue**: 无（前端 BUG/feature 不建工单）
> **日期**: 2026-05-11
> **影响范围**: 管理后台产品（版本）编辑 → Step3 预订须知 → 装备建议区域

---

## ⚠️ 关键变化

**用户反馈**：装备建议组合模板已建好，但产品（版本）编辑页 Step3 「装备建议」只能逐条手动加，没法用模板。

**方案定调（用户拍板）**：
- 装备组合模板（EquipmentTemplate）整体仍绑定在「产品线（主题）」层 —— 不动 PR #1782 的设计
- 模板对产品版本只是「装备池」：产品版本编辑时点按钮 → 拉模板 → 把装备项填入下方 `equipmentList` 表单 → 用户可继续手动增删改 → 保存的是装备项**快照**，与模板脱钩
- 后端 0 改动，纯前端做"快速填充"按钮

## 一、背景

PR #1768 → #1782 历史：
- #1768: 装备组合模板首次落地，绑在产品版本（product_supplement）层
- #1777 / #1782: 用户反馈"应该绑在主题层"，已迁移 templateId 到 product_line 层
- 但 PR #1782 配套的前端改造未完成（主题编辑页没加下拉、产品版本 Step5 还是手动逐条加）

本次 5/11 用户重新明确：
- 模板**整体绑定**仍在主题层（保留 #1782）
- 产品版本编辑时的「装备建议」需要能**从模板快速填充**到表单（不传 templateId 给后端，前端只是借模板做填充）

## 二、变更接口清单

**后端 0 个新接口、0 个 break**，前端复用以下已存在接口：

| # | 接口 | 方法 | 路径 | 用途 |
|---|------|------|------|------|
| 1 | 启用模板下拉 | GET | `/admin/equipment-template/enabled` | 获取所有 ENABLED 模板的 (templateId, name, itemCount) |
| 2 | 模板详情 | GET | `/admin/equipment-template/{templateId}` | 拿到模板的 items 数组（用于填充表单） |

## 三、前端实现要点

### UI 位置

产品版本编辑页（`/product/edit?id=xxx`）→ 第 3 步「预订须知」→「装备建议」区域：

当前：仅有「+ 新增装备 (N/20)」一个按钮，逐条手动加。

新增：「+ 新增装备」按钮**旁边**或**上方**加一个 `[ 从模板选择 ]` 按钮。

### 交互流程

1. 点击 `[ 从模板选择 ]`
2. 弹出/下拉 GET `/admin/equipment-template/enabled` 列表（显示模板名 + items 条数）
   - 可选 UX：默认高亮"当前主题已绑模板"（前端可在 ProductLineRespVO 取 `equipmentTemplateId`，匹配后置顶/打勾）
3. 用户选中某个模板 → 调 GET `/admin/equipment-template/{templateId}` 拿 items 数组
4. **填充策略**（前端拍板，建议二选一）：
   - **覆盖模式**：清空当前 equipmentList → 填入模板 items（推荐，符合"快速填充"直觉）
   - **追加模式**：模板 items 追加到当前 equipmentList 末尾（注意 ≤20 条上限校验）
5. 填充后用户可继续手动增删改单条
6. 保存时调当前 Step5 保存接口，`equipmentList` 字段照常传（**不要传 templateId 给 ProductSupplementSaveReqVO**，该字段已删除）

### 与主题绑定模板的关系

- 主题（产品线）层的 `equipment_template_id` 字段：**保持不动**，目前 MP 端读取仍以此为主
- 产品版本「从模板选择」**只是 UI 工具**，不改写主题绑定
- 保存到 `equipment_list` 后，MP 端渲染优先级：主题模板 items → fallback `equipment_list`（即用户在 Step5 手动维护的项才在主题未绑模板时生效）

### 模板装备项数据结构

GET `/admin/equipment-template/{templateId}` 返回的 `items` 数组结构：

```json
[
  { "text": "防晒霜 SPF50+", "icon": "sunscreen", "color": "#FFA726" },
  { "text": "长袖防晒衣", "icon": "clothes", "color": null }
]
```

**完全兼容** `ProductSupplementSaveReqVO.EquipmentItem`（字段同名 text/icon/color），前端 ES6 直接拷贝即可，无需字段映射。

### 校验

- 单条 text 1-50 字（后端校验）
- 总条数 ≤20（后端校验，前端填充前先比对若超出需提示）

## 四、不影响范围

- ✅ MP 端装备项展示：不变（主题模板 → fallback equipment_list）
- ✅ 主题（产品线）创建/编辑表单的「装备建议组合」下拉：**仍是 PR #1782 待办的前端任务**，本次不收口
- ✅ 后端任何接口、任何 VO、任何 DDL：0 改动
- ✅ 装备组合模板列表/编辑页（`/product/equipment-template`）：不变
- ✅ 产品保存接口：仍是 `equipmentList` 数组，无新字段

## 五、相关历史

| PR | Issue | 说明 | 是否仍有效 |
|----|-------|------|------------|
| #1768 | #1767 | 装备组合模板首版，绑产品版本层 | ⚠️ 字段已迁走 |
| #1782 | #1777 | 字段从 product_supplement 迁到 product_line | ✅ 有效（设计仍是主题层绑） |
| 本次 | - | 产品版本 Step5 加「快速填充」按钮（前端） | ✅ 最新 |

## 六、相关文档

- EquipmentTemplate 模板列表接口：`AdminEquipmentTemplateController:82-97`
- 产品版本 Step5 SaveReq：`ProductSupplementSaveReqVO`（无 templateId 字段，请勿误传）
- MP 渲染优先级：`MpProductDetailAssembler:236-253`