changelog: 酒店详情3接口+tierName+退款政策 (PR #684)

changelogs/2026-04/2026-04-16_mp-hotel-detail-apis.md

@@ -0,0 +1,188 @@
+# 小程序端酒店详情3个接口 + HotelInfo补tierName + 退款政策
+
+- **日期**: 2026-04-16
+- **服务**: hl-product-service-v2, hl-gateway
+- **PR**: #684
+- **类型**: feat
+
+## 一、每日住宿补充 tierName
+
+`GET /mp/product/{id}` 和 `GET /mp/product/{id}/day/{dayNumber}` 的 `hotels[]` 新增字段：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `tierName` | String | 档位名称（如"舒适"、"高档"） |
+
+前端可直接用 `tierName` 显示档位标签，不再需要从 `tiers` 中按 `tierSeq` 匹配。
+
+---
+
+## 二、3个新接口（酒店详情 / 房型列表 / 房型详情）
+
+### 1. 产品某天住宿详情
+
+```
+GET /mp/product/{id}/day/{dayNumber}/hotels
+```
+
+**参数**: 产品ID + 天序号（1开始）
+
+**响应**（按档位分组）:
+
+```json
+{
+  "dayNumber": 1,
+  "tiers": [
+    {
+      "tierSeq": 1,
+      "tierName": "舒适",
+      "hotels": [
+        {
+          "hotelId": 2023714929877450753,
+          "name": "呼伦贝尔香格里拉大酒店",
+          "hotelType": "HOTEL",
+          "starLevel": "FIVE",
+          "province": "内蒙古",
+          "city": "呼伦贝尔",
+          "district": "海拉尔区",
+          "address": "河东新区...",
+          "longitude": 119.736,
+          "latitude": 49.212,
+          "coverUrl": "https://oss.xxx/cover.jpg",
+          "bannerUrls": ["https://oss.xxx/1.jpg"],
+          "facilities": "{\"wifi\":true,\"parking\":true}",
+          "highlights": "{\"items\":[\"草原景观房\"]}",
+          "description": "五星级草原度假酒店...",
+          "checkInTime": "14:00",
+          "checkOutTime": "12:00",
+          "checkInNotes": "需携带身份证",
+          "tags": ["五星级", "草原景观"],
+          "roomTypeId": 3002000000000000013,
+          "roomTypeName": "豪华大床房",
+          "roomCount": 2
+        }
+      ]
+    },
+    {
+      "tierSeq": 2,
+      "tierName": "高档",
+      "hotels": [...]
+    }
+  ]
+}
+```
+
+### 2. 酒店房型列表
+
+```
+GET /mp/product/hotel/{hotelId}/room-types
+```
+
+**参数**: 酒店ID
+
+**响应**:
+
+```json
+{
+  "hotelId": 2023714929877450753,
+  "hotelName": "呼伦贝尔香格里拉大酒店",
+  "roomTypes": [
+    {
+      "roomTypeId": 3002000000000000013,
+      "name": "豪华大床房",
+      "roomCategory": "KING",
+      "bedType": "KING_BED",
+      "maxOccupancy": 2,
+      "coverUrl": "https://oss.xxx/room-cover.jpg"
+    },
+    {
+      "roomTypeId": 2023727403196502017,
+      "name": "标准双床房",
+      "roomCategory": "STANDARD",
+      "bedType": "TWIN_BED",
+      "maxOccupancy": 2,
+      "coverUrl": null
+    }
+  ]
+}
+```
+
+### 3. 房型详情
+
+```
+GET /mp/product/room-type/{roomTypeId}
+```
+
+**参数**: 房型ID
+
+**响应**:
+
+```json
+{
+  "roomTypeId": 3002000000000000013,
+  "hotelId": 2023714929877450753,
+  "name": "豪华大床房",
+  "roomCategory": "KING",
+  "roomArea": 35.0,
+  "bedType": "KING_BED",
+  "bedCount": 1,
+  "bedSize": "1.8m",
+  "maxOccupancy": 2,
+  "floorInfo": "8-15层",
+  "windowType": "FLOOR_WINDOW",
+  "bathroomType": "PRIVATE",
+  "roomFacilities": "{\"minibar\":true,\"bathtub\":true}",
+  "description": "草原景观豪华大床房...",
+  "coverUrl": "https://oss.xxx/room-cover.jpg",
+  "bannerUrls": ["https://oss.xxx/r1.jpg", "https://oss.xxx/r2.jpg"],
+  "videoUrl": null
+}
+```
+
+### 接口说明
+
+- 3个接口均**无需登录**（已加入网关JWT白名单）
+- 接口1的酒店详情通过Feign调资源服务获取，未绑定资源时用快照名称兜底
+- 接口2从酒店详情中提取房型列表（仅返回已启用房型）
+
+---
+
+## 三、退款政策字段
+
+### 管理端 Step5 保存
+
+`PUT /admin/product/item/{id}/supplement` 新增字段：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `refundPolicyId` | Long | 退款政策ID（从 `GET /admin/order/refund-policy/enabled` 下拉框选择） |
+
+根据产品支付类型选择对应退款政策（全款退款 / 定金退款）。
+
+### 小程序端
+
+`GET /mp/product/{id}` 新增字段：
+
+```json
+{
+  "refundPolicy": {
+    "policyName": "全款默认退款政策",
+    "rules": [
+      { "minDays": 15, "refundRatio": 100 },
+      { "minDays": 7, "refundRatio": 80 },
+      { "minDays": 3, "refundRatio": 50 },
+      { "minDays": 0, "refundRatio": 20 }
+    ]
+  }
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `refundPolicy` | Object | 退款政策（未配置时为null） |
+| `refundPolicy.policyName` | String | 政策名称 |
+| `refundPolicy.rules` | List | 退款规则列表 |
+| `refundPolicy.rules[].minDays` | Integer | 距出发最少天数 |
+| `refundPolicy.rules[].refundRatio` | Integer | 退款比例（百分比0-100） |
+
+含义：出发前≥15天退100%，≥7天退80%，≥3天退50%，<3天退20%。