From 973b89e4f91457c3f447e2cca11fdb02b14e8b86 Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Wed, 6 May 2026 23:30:25 +0800 Subject: [PATCH] =?UTF-8?q?feat(product):=20=E8=A3=85=E5=A4=87=E5=BB=BA?= =?UTF-8?q?=E8=AE=AE=E7=BB=84=E5=90=88=E5=8F=AF=E5=A4=8D=E7=94=A8=E6=A8=A1?= =?UTF-8?q?=E6=9D=BF=20+=20=E4=BA=A7=E5=93=81=E8=AE=BE=E8=AE=A1=E7=BB=91?= =?UTF-8?q?=E5=AE=9A=20(wx/HL=20#1768=20/=20Closes=20wx/HL=20#1767)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit @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) --- .../06_feat_product_equipment_template.md | 133 ++++++++++++++++++ 1 file changed, 133 insertions(+) create mode 100644 changelogs/2026-05/06_feat_product_equipment_template.md diff --git a/changelogs/2026-05/06_feat_product_equipment_template.md b/changelogs/2026-05/06_feat_product_equipment_template.md new file mode 100644 index 0000000..16a6ecc --- /dev/null +++ b/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` (必填, 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` / `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 启动时自动创建。