patch(#2266): supplies-combo 列表/详情 items[] 也补 coverUrl (PR #2290 / Closes #2289)

changelogs/2026-05/14_feat_mp_admin_product_detail_supplies_with_cover.md

@@ -124,3 +124,61 @@ curl https://api.test.1814.love:9443/mp/product/2045623908178046978
 返回顶层 `supplies` 数组 4 条全部带 coverUrl 真实 OSS URL,按 sortOrder 0→1→2→3 升序。
 
 Admin 端用 `test_admin (admin_id=1002)` 测试 productId=2053665899663024129(用户截图同一产品):3 条备品(团队识别手环 / 防晒喷雾 / 便携矿泉水)全部带 coverUrl ✅
+
+---
+
+## 六、补丁(PR #2290 / Issue #2289)— 备品组合接口同步补 coverUrl
+
+紧接本文上方主体,管理后台编辑产品「路线与备品 → 从组合选择」弹窗调的 **备品组合列表/详情** 接口也补齐 coverUrl(此前只有产品自己的 supplies 数组有,组合接口 items 缺):
+
+### 变更接口
+
+| # | 接口 | 方法 | 路径 | 变更 |
+|---|------|------|------|------|
+| 3 | 启用组合列表 | GET | `/admin/supplies-combo/enabled` | `items[]` 新增 `coverUrl` |
+| 4 | 备品组合详情 | GET | `/admin/supplies-combo/{comboId}` | 同上 |
+
+### VO 字段
+
+`SupplyComboRespVO.ItemRespVO` 新增 `coverUrl: String`(放在 `suppliesName` 之后,与产品详情 SuppliesVO 对齐)。语义与上方主体一致:**快照,来自 supplies_item.cover_material_id 对应 material.oss_url,可能为 null,前端做占位图兜底**。
+
+```json
+{
+  "code": 200,
+  "data": [
+    {
+      "comboId": 2046122595429806082,
+      "name": "4",
+      "items": [
+        {
+          "id": 2048695562294710273,
+          "suppliesId": ...,
+          "suppliesName": "便携矿泉水",
+          "coverUrl": "https://hlgl-test.oss-cn-beijing.aliyuncs.com/test/material/2026/03/07/xxx.jpg",
+          "categoryCode": "personal_gear",
+          "billingType": "...",
+          "basePrice": ...,
+          "quantity": 1,
+          "sortOrder": 3
+        }
+      ]
+    }
+  ]
+}
+```
+
+### 测试服真测证据
+
+- `/admin/supplies-combo/enabled` 返回 2 个 combo,共 5 条 items 全部带真实 OSS URL coverUrl(命中率 100%)
+- `/admin/supplies-combo/{comboId}` 同款返回 4 条 items 全部带 coverUrl
+
+### 实现说明
+
+- 跨所有 combo 一次性批量 `MaterialService.getMaterialsByIds` 调用,**单测含 `verify(materialService, times(1))` 防 N+1**
+- 复用主体 #2272 引入的 `parseLongSafe(cover_material_id)` 数字防御 + `fetchCoverUrlsByMaterialIds`
+- material 查询失败 / 不存在 / cover_material_id 非数字 → coverUrl null,**不阻断接口**
+
+### 不变项
+
+- `items` 数组顺序保持后端原有逻辑(目前是 sortOrder DESC,与本工单 #2289 无关,如需调整为 ASC 请单独反馈)
+