diff --git a/changelogs/2026-04/2026-04-18_mp-group-product-list.md b/changelogs/2026-04/2026-04-18_mp-group-product-list.md new file mode 100644 index 0000000..ec16d82 --- /dev/null +++ b/changelogs/2026-04/2026-04-18_mp-group-product-list.md @@ -0,0 +1,338 @@ +# 小程序端 - 新增小蒙马产品全部列表接口 + +- **日期**: 2026-04-18 +- **PR**: [#847](https://git.1814.love:8443/wx/HL/pulls/847) (Closes #843) +- **类型**: FEATURE +- **状态**: 已合并到 dev + 测试环境部署中 +- **服务**: hl-mp-service + hl-product-service-v2 + +--- + +## 一、功能说明 + +### 业务场景 +小程序「**小蒙马专题页**」需要一次性铺满展示**全部已上架的小蒙马（GROUP）产品**： + +- 不分页（瀑布流/卡片墙一屏看全） +- 每个产品卡片要直接显示**最近的可售团期**（出发日期、起步价、剩余名额） +- 支持关键词模糊搜索（产品名 / 副标题 / 标签） + +### 设计要点 + +| 维度 | 设计 | 说明 | +|------|------|------| +| **是否分页** | 否 | hard cap 100 条（业务上小蒙马产品总数远 < 100，专题页一次性渲染） | +| **排序** | `sort_order ASC, product_id DESC` | 运营通过 `sort_order` 控制置顶；同序号按新产品在前 | +| **缓存** | 服务端 600s TTL | `@MpCache(prefix="product:group:list:", ttl=600)`，发布/下架后 10 分钟内生效 | +| **batches 注入** | 与 `/mp/product/list` **完全一致** | 复用 `injectBatchesForGroupItems` 私有方法，并行 Feign 调用，单个失败不影响整体 | +| **productId 类型** | String | `@JsonSerialize(ToStringSerializer)` 防 JS 雪花 ID 精度丢失 | +| **详情接口** | **零改动** | 直接复用 `GET /mp/product/{productId}`（详见下方"重要提示"） | +| **N+1 防护** | 4 步批量查询 | basic 列表 + paymentType 批量 + 起步价日历批量 + lineName 批量 | +| **权限** | OPTIONAL | 无需登录即可访问 | + +--- + +## 二、变更接口清单 + +| # | 方法 | 路径 | 说明 | 鉴权 | 缓存 | +|---|------|------|------|------|------| +| 1 | GET | `/mp/product/group/list` | 小蒙马产品全部列表（不分页 + batches） | OPTIONAL | 600s | + +--- + +## 三、接口详细定义 + +### 1. 小蒙马产品全部列表 + +``` +GET /mp/product/group/list +``` + +#### 鉴权 +- **OPTIONAL**：登录与未登录均可访问，逻辑无差异 +- 已加入网关白名单，可直接调用 + +#### 请求参数 + +| 参数 | 位置 | 类型 | 必填 | 说明 | +|------|------|------|------|------| +| `keyword` | query | String | 否 | 模糊搜索关键词（匹配产品名/副标题/标签） | + +#### 请求示例 + +``` +GET /mp/product/group/list +GET /mp/product/group/list?keyword=亲子 +``` + +#### 完整响应示例 + +```json +{ + "code": 200, + "message": "success", + "data": [ + { + "productId": "120000000000001", + "productType": "GROUP", + "name": "草原星空亲子3日游", + "subtitle": "8人精品小团·1对1管家", + "coverImageUrl": "https://oss.example.com/cover.jpg", + "tripDays": 3, + "tripNights": 2, + "lineName": "亲子草原", + "tags": ["亲子", "星空"], + "seasons": ["summer", "autumn"], + "startPrice": 3980.00, + "startPriceLabel": "¥3980起/人", + "paymentType": "DEPOSIT", + "sortOrder": 10, + "batches": [ + { + "batchId": "9001000000000001", + "departureDate": "2026-05-01", + "batchLabel": "五一团", + "batchName": "草原星空亲子3日游 5月1日团", + "batchStatus": "ENROLLING", + "startingPrice": 3980.00, + "enrolledCount": 6, + "remainingSlots": 2, + "isConfirmed": false + }, + { + "batchId": "9001000000000002", + "departureDate": "2026-05-15", + "batchLabel": "5月中旬团", + "batchName": "草原星空亲子3日游 5月15日团", + "batchStatus": "CONFIRMED", + "startingPrice": 3980.00, + "enrolledCount": 8, + "remainingSlots": 0, + "isConfirmed": true + } + ] + }, + { + "productId": "120000000000002", + "productType": "GROUP", + "name": "呼伦贝尔大环线4日游", + "subtitle": "深度纯玩·全程5星住宿", + "coverImageUrl": "https://oss.example.com/cover2.jpg", + "tripDays": 4, + "tripNights": 3, + "lineName": "呼伦贝尔环线", + "tags": ["纯玩", "5星"], + "seasons": ["summer"], + "startPrice": 5680.00, + "startPriceLabel": "¥5680起/人", + "paymentType": "FULL", + "sortOrder": 20, + "batches": [] + } + ] +} +``` + +> **空数据**：当不存在已上架 GROUP 产品时，`data` 返回 `[]`（**不是 null**）。 +> **batches 为空**：某产品当前无可售团期时，该产品的 `batches` 返回 `[]`。 + +#### 响应字段说明 + +| 字段 | 类型 | 必有 | 说明 | +|------|------|------|------| +| `data[].productId` | **String** | 是 | 产品ID（**字符串**，由后端 `ToStringSerializer` 序列化，前端**禁止用 Number 接收**） | +| `data[].productType` | String | 是 | 产品类型，固定值 `GROUP`（小蒙马） | +| `data[].name` | String | 是 | 产品名称 | +| `data[].subtitle` | String | 否 | 副标题/卖点（一行短文案） | +| `data[].coverImageUrl` | String | 否 | 封面图 URL（OSS CDN 地址） | +| `data[].tripDays` | Integer | 是 | 行程天数 | +| `data[].tripNights` | Integer | 是 | 行程晚数 | +| `data[].lineName` | String | 否 | 产品线（主题）名称 | +| `data[].tags` | List\ | 否 | 标签数组（如 `["亲子","星空"]`） | +| `data[].seasons` | List\ | 否 | 适合季节数组，字典 `product_season` | +| `data[].startPrice` | BigDecimal | 否 | 起步价（元，未来日期最低成人售价） | +| `data[].startPriceLabel` | String | 否 | 起步价文案（用于卡片标价，如 `¥3980起/人`） | +| `data[].paymentType` | String | 是 | 支付方式，字典 `payment_type` | +| `data[].sortOrder` | Integer | 否 | 运营排序号（值越小越靠前） | +| `data[].batches` | List\ | 是 | **可售团期列表（即使为空也返回 `[]`）**，结构见下表 | + +#### `batches[]` 字段说明（与 `/mp/product/list` 完全一致） + +| 字段 | 类型 | 说明 | +|------|------|------| +| `batches[].batchId` | String/Long | 团期 ID（与 v1 团期接口一致，建议用 String 接收） | +| `batches[].departureDate` | String | 出发日期 `yyyy-MM-dd`（**列表已按出发日期升序**） | +| `batches[].batchLabel` | String | 团期标签（如 `五一团` `暑假首发` 等运营自定义） | +| `batches[].batchName` | String | 团期完整名称 | +| `batches[].batchStatus` | String | 团期状态，字典 `batch_status` | +| `batches[].startingPrice` | BigDecimal | 团期起步价（元） | +| `batches[].enrolledCount` | Integer | 已报名人数 | +| `batches[].remainingSlots` | Integer | 剩余名额 | +| `batches[].isConfirmed` | Boolean | 是否已成团 | + +--- + +## 四、重要提示给前端 + +### 1. 详情接口零改动 — 直接复用现有接口 + +> **不要再问"小蒙马是不是要专属详情接口"，没有，也不需要。** + +``` +GET /mp/product/{productId} +``` + +这个接口**已经支持 GROUP 产品**，会自动注入 `batches` 字段（详情接口 notes 已写明）。 + +**前端动作**： +- 列表页：调用 `GET /mp/product/group/list` 拿到 productId +- 详情页：直接 `GET /mp/product/{productId}`（productId 用 String 拼接，**不要 parseInt**） +- 详情返回结构与现有产品详情完全一致，GROUP 产品的 `batches` 字段在 detail VO 中已存在 + +### 2. productId 必须用 String 处理 + +后端 VO 字段： + +```java +@JsonSerialize(using = ToStringSerializer.class) +private Long productId; +``` + +序列化结果：`"productId": "120000000000001"` （**带引号的字符串**） + +前端**禁止**： + +```javascript +// ❌ 错误：JS Number 最大安全整数 2^53，会精度丢失 +const id = Number(item.productId); + +// ✅ 正确：直接用 String +const id = item.productId; +fetch(`/mp/product/${id}`); +``` + +### 3. 与 `/mp/product/list?productType=GROUP` 的差异 + +| 维度 | `/mp/product/list?productType=GROUP` | `/mp/product/group/list` | +|------|--------------------------------------|--------------------------| +| 分页 | 有（page+pageSize） | **无**（hard cap 100） | +| 返回结构 | `Result>` | `Result>` | +| 字段 | 通用产品字段 + batches | 同左（一致） | +| 缓存 key | `product:list:` | `product:group:list:` | +| 适用场景 | 通用列表（带筛选/分页） | **小蒙马专题页一次性铺满** | + +> **建议**：专题页用 `/mp/product/group/list`；通用列表（首页、搜索）继续用 `/mp/product/list`。 + +--- + +## 五、缓存说明 + +- **服务端缓存**：`@MpCache(prefix="product:group:list:", ttl=600)` +- **TTL**：600 秒（10 分钟） +- **缓存粒度**：按 `keyword` 区分，无 keyword 与有 keyword 是不同的 cache key +- **失效时机**：依赖自然过期（10 分钟内运营发布/下架的产品不会立即可见） +- **前端缓存建议**：列表数据可在小程序端短期缓存（如 30 秒），下拉刷新时强制清缓存 + +--- + +## 六、字典对照 + +### `product_type`（产品类型） + +| 值 | 中文 | 说明 | +|----|------|------| +| `CORE` | 核心产品 | 主推标准产品 | +| `ROUTE` | 自驾路书 | 自驾游线路 | +| `CUSTOM` | 私人定制 | 1对1定制行程 | +| `GROUP` | **小蒙马** | **本接口固定返回此类型** | + +### `batch_status`（团期状态） + +| 值 | 中文 | UI 建议 | +|----|------|---------| +| `ENROLLING` | 报名中 | 显示绿色标签 + 剩余名额 | +| `CONFIRMED` | 已成团 | 显示蓝色标签"已成团" | +| `FULL` | 已满员 | 显示灰色标签 + 禁用报名按钮 | +| `CLOSED` | 已关闭 | 显示灰色标签 + 隐藏 CTA | + +### `payment_type`（支付方式） + +| 值 | 中文 | +|----|------| +| `FULL` | 全额支付 | +| `DEPOSIT` | 订金 + 尾款 | + +### `product_season`（适合季节） + +| 值 | 中文 | +|----|------| +| `spring` | 春季 | +| `summer` | 夏季 | +| `autumn` | 秋季 | +| `winter` | 冬季 | + +--- + +## 七、前端实现建议 + +### 推荐：瀑布流 / 卡片墙 + +``` +┌──────────────────────── 小蒙马专题页 ────────────────────────┐ +│ [搜索框 keyword] │ +│ │ +│ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ │ +│ │ [封面图] │ │ [封面图] │ │ [封面图] │ │ +│ │ 草原星空亲子3日 │ │ 呼伦贝尔大环线 │ │ 阿尔山雪国5日 │ │ +│ │ 8人精品小团 │ │ 深度纯玩 │ │ 冬季限定 │ │ +│ │ #亲子 #星空 │ │ #纯玩 #5星 │ │ #雪景 │ │ +│ │ ¥3980起/人 │ │ ¥5680起/人 │ │ ¥6280起/人 │ │ +│ │ ────────────── │ │ ────────────── │ │ ────────────── │ │ +│ │ 最近团期： │ │ 最近团期： │ │ 最近团期： │ │ +│ │ • 5/1 报名中(2) │ │ • 5/8 报名中(5) │ │ • 12/20 报名中 │ │ +│ │ • 5/15 已成团 │ │ │ │ │ │ +│ └────────────────┘ └────────────────┘ └────────────────┘ │ +└──────────────────────────────────────────────────────────────┘ +``` + +### 卡片渲染要点 + +1. **顶部图区**：`coverImageUrl`，建议固定宽高比（如 16:10） +2. **标题区**：`name`（粗体）+ `subtitle`（小字灰色） +3. **标签区**：`tags` 取前 2-3 个，超出折叠 +4. **价格区**：用 `startPriceLabel` 直接渲染（已带 `¥` 和 `起/人` 后缀） +5. **团期区**：`batches` 取前 2 条展示（按出发日期升序），显示 `departureDate` + 状态标签 + 剩余名额 +6. **空团期**：`batches=[]` 时显示"暂无可售团期"或灰显 + +### 跳转详情 + +```javascript +// 卡片点击 +function onCardTap(item) { + // productId 必须用 String 拼接 + wx.navigateTo({ url: `/pages/product/detail?id=${item.productId}` }); +} + +// 详情页加载 +function loadDetail(id) { + // 直接复用现有详情接口，无需任何改动 + return request.get(`/mp/product/${id}`); +} +``` + +--- + +## 八、回归验证 + +测试环境部署完成后，前端可通过以下方式验证： + +``` +GET https://api.test.1814.love/mp/product/group/list +``` + +**预期**： +- HTTP 200 +- `data` 为数组（即使为空也是 `[]`） +- 每个 item 的 `productType === "GROUP"` +- 每个 item 的 `productId` 是带引号的 String +- GROUP 产品有可售团期时 `batches.length > 0`，否则 `batches === []`