From f0f287105a56d7a02af8d8b9fefd02a6ef1bff34 Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Fri, 17 Apr 2026 14:56:10 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20product-v2=20=E4=BA=A7=E5=93=81?= =?UTF-8?q?=E8=AF=A6=E6=83=85=E6=8E=A5=E5=8F=A3=E6=89=A9=E5=B1=95=E5=BF=AB?= =?UTF-8?q?=E7=85=A7=E5=AD=97=E6=AE=B5=EF=BC=88=E8=AE=A2=E5=8D=95=E8=AF=A6?= =?UTF-8?q?=E6=83=85=E5=BC=B9=E7=AA=97=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ..._product-v2_detail_snapshot_fields_done.md | 119 ++++++++++++++++++ 1 file changed, 119 insertions(+) create mode 100644 changelogs/2026-04/2026-04-17_product-v2_detail_snapshot_fields_done.md diff --git a/changelogs/2026-04/2026-04-17_product-v2_detail_snapshot_fields_done.md b/changelogs/2026-04/2026-04-17_product-v2_detail_snapshot_fields_done.md new file mode 100644 index 0000000..6b07f9b --- /dev/null +++ b/changelogs/2026-04/2026-04-17_product-v2_detail_snapshot_fields_done.md @@ -0,0 +1,119 @@ +# product-v2 产品详情接口扩展快照字段（完成） + +- **日期**: 2026-04-17 +- **服务**: hl-product-service-v2（含 hl-common-core / hl-resource-service 配合） +- **PR**: https://git.1814.love:8443/wx/HL/pulls/742 +- **Issue**: https://git.1814.love:8443/wx/HL/issues/741 +- **影响**: C端订单详情页 6 个服务详情弹窗所需字段已可从订单快照直接读取 + +## 接口 + +### `GET /internal/product/{productId}/detail` + +- **签名不变**，新增字段向前兼容 +- **新增可选 query 参数**：`date=yyyy-MM-dd`（出发日期，匹配班期员工；为空时 staff=[]） + +## 新增/扩展字段 + +### 1. `itinerary[].nodes[]`（NodeItem）新增 4 字段 + +| 字段 | 类型 | 说明 | +|------|------|------| +| `coverUrl` | String | 资源封面图URL | +| `description` | String | 资源描述 | +| `price` | BigDecimal | 单价（暂传null，后续门票定价体系落地再补） | +| `tags` | String[] | 资源标签（如"5A景区"、"网红打卡"） | + +### 2. 根级新增 `hotels[]`（HotelItem） + +| 字段 | 类型 | 说明 | +|------|------|------| +| `hotelId` | Long | 酒店ID | +| `hotelName` | String | 酒店名称 | +| `roomType` | String | 房型名称 | +| `coverUrl` | String | 酒店封面图URL | +| `hotelType` | String | 酒店类型（"5星"/"特色民宿"/"蒙古包"） | + +> 产品全部住宿按 `hotelId` 去重（多日连住的酒店只出现一次）。 + +### 3. 根级新增 `restaurants[]`（RestaurantItem） + +| 字段 | 类型 | 说明 | +|------|------|------| +| `restaurantId` | Long | 餐厅ID | +| `restaurantName` | String | 餐厅名称 | +| `mealType` | String | 餐别（暂传null，后续补） | +| `description` | String | 菜品描述（如"含奶茶/手把肉/烤包子"） | + +> 从行程节点 `nodeType=RESTAURANT` 按 `resourceId` 去重。 + +### 4. 根级新增 `staff[]`（StaffItem） + +| 字段 | 类型 | 说明 | +|------|------|------| +| `staffRole` | String | 员工角色（LEADER/PHOTOGRAPHER/DRIVER） | +| `staffName` | String | 员工姓名 | +| `staffPhone` | String | 员工电话 | +| `avatarUrl` | String | 头像URL（员工档案未建时为null） | +| `remark` | String | 备注/简介 | + +> 按 `productId + date` 匹配班期，查询 `group_batch_staff`。 +> `date` 为空或无匹配班期时 `staff=[]`。 + +## 调用示例 + +``` +GET /internal/product/1001/detail?date=2026-05-01 +``` + +```json +{ + "code": 200, + "data": { + "productId": 1001, + "name": "呼伦贝尔5日游", + "itinerary": [ + { + "dayId": 10, + "dayNumber": 1, + "dayTitle": "第一天", + "nodes": [ + { + "nodeId": 101, + "nodeType": "SCENIC", + "nodeName": "莫日格勒河", + "resourceId": 2001, + "coverUrl": "https://oss/scenic.jpg", + "description": "天下第一曲水...", + "price": null, + "tags": ["5A景区", "网红打卡"] + } + ] + } + ], + "hotels": [ + { "hotelId": 4001, "hotelName": "草原酒店", "roomType": "标间", + "coverUrl": "https://oss/hotel.jpg", "hotelType": "5星" } + ], + "restaurants": [ + { "restaurantId": 3001, "restaurantName": "蒙古包餐厅", + "mealType": null, "description": "含奶茶/手把肉/烤包子" } + ], + "staff": [ + { "staffRole": "LEADER", "staffName": "张领队", + "staffPhone": "13800001111", "avatarUrl": null, "remark": "10年带团经验" } + ] + } +} +``` + +## 兼容性 + +- **所有新增字段向前兼容**，订单服务侧未改之前不受影响（旧客户端忽略新字段） +- 接口URL与请求参数不变（`date` 为可选新增） +- 下游订单服务侧序列化为 `product_snapshot` 存库，消费端按需读取 + +## 相关改动 + +- `hl-common-core` 的 `ResourceDetailDTO` 新增 `hotelType` 字段 +- `hl-resource-service` 的 `/internal/mp/resource/batch-details` 返回酒店时填充 `hotelType`