diff --git a/changelogs/2026-05/11_frontend_notice_admin_product-step5-equipment-template-quick-fill.md b/changelogs/2026-05/11_frontend_notice_admin_product-step5-equipment-template-quick-fill.md new file mode 100644 index 0000000..cf52e82 --- /dev/null +++ b/changelogs/2026-05/11_frontend_notice_admin_product-step5-equipment-template-quick-fill.md @@ -0,0 +1,106 @@ +# 管理端产品编辑 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`