API Changelog Bot 11dc90c960 docs: C 端班期 schedules 补 remain 字段 + 下单后清缓存 (PR #1296 )

- GET /mp/product/{id}/schedules 响应体新增 remainParticipants(余可报名数) / remainFamilies(余家庭数)
- 下单 enroll/unenroll 后自动清缓存,前端 GET 立即拿新余量

Issue #1292

2026-04-23 15:30:49 +08:00

3.9 KiB

原始文件 Blame 文件历史

C 端班期: schedules 接口补 `remainParticipants` / `remainFamilies` 字段, 订单后不再缓存穿透

服务: hl-product-service-v2 (端口 8083) PR: #1296 Issue: #1292 日期: 2026-04-23 影响范围: C 端小程序小蒙马(GROUP 类型)产品详情页"余多少家庭/余多少可报名"展示 + 下单后班期余量刷新

⚠️ 关键变化

新增 2 个字段: GET /mp/product/{id}/schedules 每个班期对象新增 remainParticipants(余可报名数, 人数口径) 和 remainFamilies(余家庭数, 房间口径) — 之前只返 maxParticipants/enrolledCount/maxRooms/bookedRooms 原始字段, 前端需要自己算差值。现在后端直接给聚合值。
缓存失效修复: 之前下单成功后 5 分钟内重复调 schedules 返回旧 enrolledCount/bookedRooms(Redis 缓存未失效), 现在入团(enroll)/取消报名(unenroll)事务提交后立刻清 mp:product:schedules:{productId} 缓存, 前端下次 GET 立即拿到最新余量。

前端影响: 无破坏。旧前端忽略新字段继续工作; 新前端直接用 remainParticipants / remainFamilies 展示, 不需自己 max-used。

一、背景

原 MpScheduleRespVO 只返回 4 个库级原始字段, C 端小蒙马产品详情页"余多少家庭""余多少可报名"需前端 max - used 自算; 即使前端算了, 因 schedules 查询 Redis 缓存 5 分钟 TTL 且下单链路不清缓存, 下单成功后展示余量 5 分钟内仍是旧值。

二、变更接口清单

#	接口	方法	路径	变更类型	说明
1	小程序查班期列表	GET	`/mp/product/{id}/schedules`	响应体新增字段	`remainParticipants` + `remainFamilies`

内部接口行为变化(前端无感, 仅后端服务调用):

POST /internal/product/batch/{batchId}/enroll — 成功后清 mp:product:schedules:{productId} 缓存
POST /internal/product/batch/{batchId}/unenroll — 同上

三、接口详情

1. 查询班期列表 `GET /mp/product/{id}/schedules`

VO: MpScheduleRespVO

响应字段(只列新增)

字段	类型	说明
`remainParticipants`	Integer	余可报名数(人数口径) = `maxParticipants - enrolledCount`。`maxParticipants` 为 `null` 或 `0` 时返回 `null` 表示"不限人数"。
`remainFamilies`	Integer	余家庭数(房间口径, 1 家庭 ≈ 1 房间起) = `maxRooms - bookedRooms`。`maxRooms` 为 `null` 或 `0` 时返回 `null` 表示"不限家庭"。

响应示例

{
  "code": 200,
  "message": "成功",
  "data": [
    {
      "batchId": 2042973109799215105,
      "productId": 2042973108708696065,
      "batchNo": "Q2026051101",
      "batchName": "五一特别班",
      "adultPrice": 2999.00,
      "childPrice": 1599.00,
      "departureDate": "2026-05-01",
      "endDate": "2026-05-05",
      "enrollmentDeadline": "2026-04-30",
      "maxParticipants": 23,
      "enrolledCount": 2,
      "maxRooms": 19,
      "bookedRooms": 1,
      "remainParticipants": 21,
      "remainFamilies": 18,
      "batchStatus": "ENROLLING"
    }
  ]
}

"不限"场景示例:

{
  "maxParticipants": null,
  "enrolledCount": 0,
  "maxRooms": 0,
  "bookedRooms": 0,
  "remainParticipants": null,
  "remainFamilies": null
}

前端建议: 判空优先于展示。null 表示"不限/无上限"(对应 UI 可显示 "不限" 或隐藏)。

四、前端接入点

下单前: 展示 remainFamilies 代替原本的 maxRooms - bookedRooms 自算逻辑
下单后: 无需改动逻辑。下单调用订单服务后, 再次 GET /mp/product/{id}/schedules 返回值已即时反映新余量(无需等 5 分钟缓存过期)
首次详情展示: 若对应字段为 null, 当作"不限/无上限", UI 做相应文案或隐藏

五、不向后兼容风险

无。纯响应体新增字段, 未改任何现有字段类型/语义。

3.9 KiB 原始文件 Blame 文件历史

C 端班期: schedules 接口补 remainParticipants / remainFamilies 字段, 订单后不再缓存穿透