diff --git a/changelogs/2026-04/2026-04-20_supplies-combo-enabled-with-items.md b/changelogs/2026-04/2026-04-20_supplies-combo-enabled-with-items.md new file mode 100644 index 0000000..060210c --- /dev/null +++ b/changelogs/2026-04/2026-04-20_supplies-combo-enabled-with-items.md @@ -0,0 +1,78 @@ +# /admin/supplies-combo/enabled 响应结构扩展(带完整备品明细) + +**日期**:2026-04-20 +**PR**:#987 +**影响**:管理端 产品编辑页 Step3「备品组合」下拉/列表 + +--- + +## 为什么变 + +原 `/admin/supplies-combo/enabled` 仅返回精简 VO(`comboId/name/itemCount`),前端要展开组合里的备品只能再逐个调 `/admin/supplies-combo/{comboId}` 详情 → N+1、体验差。 + +本次把明细直接吐在列表接口里,一次请求全量拿到。 + +--- + +## 接口契约变化 + +**Path / Method 不变**:`GET /admin/supplies-combo/enabled`(仍不分页,仅返回 `status=ENABLED`) + +### 新响应结构(`Result>`) + +```ts +{ + "code": 0, + "data": [ + { + "comboId": 7001, + "name": "亲子研学基础包", + "description": "适用 3-8 岁儿童", + "status": "ENABLED", // ENABLED / DISABLED (本接口固定 ENABLED) + "sortOrder": 10, + "createdBy": 999, + "updatedBy": 999, + "createdAt": "2026-04-01 10:00:00", + "updatedAt": "2026-04-20 15:00:00", + "itemCount": 3, // 明细数量 + "items": [ // ⭐ 新增:完整备品明细 + { + "id": 9001, // 明细主键 + "suppliesId": 100, // 备品ID + "quantity": 2, + "sortOrder": 10, + "suppliesName": "帐篷", // 快照回填:备品名 + "categoryCode": "CAMP", // 字典 supplies_category + "billingType": "BY_COUNT", // 字典 billing_type: BY_PERSON/BY_COUNT + "basePrice": 88.00 // 备品基础单价 + } + ] + } + ] +} +``` + +### 旧响应结构(已废弃,字段参考) + +```ts +{ "comboId": 7001, "name": "亲子研学基础包", "itemCount": 3 } +``` + +--- + +## 前端改造建议 + +- **下拉框展示**:继续用 `comboId`(value)+ `name`(label)+ `itemCount`(辅助信息) +- **组合卡片/悬浮预览**:直接读 `items` 数组渲染明细(suppliesName / quantity / basePrice / billingType),**不要再调详情接口** +- **产品编辑选中组合后带入备品清单**:用 `items.map(it => ({ suppliesId, quantity, unitPrice: basePrice, billingType, resourceName: suppliesName }))` 初始化表单 + +## 注意 + +- `items` 内只带「启用可见」的备品快照字段,组合保存后前端无需再追加 Feign/后端调用 +- 若某备品被下架(`status != 1` 或软删),本接口仍会把它放在 items 里(含快照字段),但产品保存时后端 Feign 展开会跳过失效项 —— 展示端如需标灰,可按需再挂钩详情接口或 `suppliesItem` 的 status 查询 + +## 不影响的接口 + +- `GET /admin/supplies-combo/{comboId}` 详情(依然返回单个组合含 items,行为不变) +- `GET /admin/supplies-combo/page` 分页(items 仍为 null,只返回 itemCount) +- `POST/PUT/DELETE /admin/supplies-combo` 全部 CRUD 接口(无变化)