docs: product-v2 产品详情接口扩展快照字段（订单详情弹窗）

2026-04-17 14:56:10 +08:00 · 2026-04-17 14:56:10 +08:00 · f0f287105a
--- 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
@ -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`