# 产品设计页面改版（8项改进）

- **日期**: 2026-04-15
- **服务**: hl-product-service-v2, hl-gateway
- **PR**: #602
- **Issue**: #601
- **类型**: feat (新功能)

## 概述

产品设计页面（Step2行程/Step3路线/Step5补充）和小程序详情页的一组改进，涉及8项需求。

---

## 1. 行程节点名可自定义

保存行程时，`nodeName` 由前端自定义（用户可改），`resourceName` 由后端自动填充资源原名快照，互不影响。

**行为变更**：
- `PUT /admin/product/item/{id}/itinerary` 保存时自动通过Feign查资源名填充 `resourceName`
- 前端传什么 `nodeName` 就存什么，改名不影响资源库

**响应字段**：
| 字段 | 说明 |
|------|------|
| `nodeName` | 展示名称（可自定义） |
| `resourceName` | 资源原名快照（自动填充，不可改） |

---

## 2. 每日行程距离计算接口

### 新增接口

```
GET /admin/product/item/{productId}/daily-mileage
```

按天计算每日驾车距离（含酒店坐标），调用高德驾车路线规划API。

**响应示例**：
```json
{
  "code": 200,
  "data": [
    {"dayNumber": 1, "mileage": 280.5},
    {"dayNumber": 2, "mileage": 195.3},
    {"dayNumber": 3, "mileage": 320.1}
  ]
}
```

---

## 3. 行程线路名称

### GET /mp/product/{id} 新增字段

| 字段 | 类型 | 说明 |
|------|------|------|
| `routeName` | String | 路线名称（如"草原环线体验"） |

### PUT /admin/product/item/{id}/route（Step3保存）新增字段

| 字段 | 类型 | 说明 |
|------|------|------|
| `routeName` | String | 路线名称 |

---

## 4. 集合地/出发地/解散地

### ⚠️ 保存位置：Step2 行程编排（不是Step3）

⚠️ **出发地已删除**（与集合地相同），只保留集合地+解散地。

| 字段 | 类型 | 说明 |
|------|------|------|
| `gatherPlace` | String | 集合地（高德行政区搜索到镇级） |
| `dismissalPlace` | String | 解散地（高德行政区搜索到镇级） |

这2个字段在以下接口中可读写：
- **`PUT /admin/product/item/{id}/itinerary`（Step2保存，主入口）** — 可单独传这2个字段不传days
- `PUT /admin/product/item/{id}/route`（Step3保存，也可设置）
- `GET /admin/product/item/{id}`（管理端详情，在routeInfo中）
- `GET /mp/product/{id}`（小程序详情）

---

## 5. 产品卖点改为选择节点

`quickUnderstand` 字段结构变更（后端仍为JSON存取，无接口变化）：

**旧结构**：`{text: "富文本", images: [...]}`

**新结构**：
```json
[
  {
    "nodeId": 12345,
    "nodeName": "白桦林景区",
    "nodeType": "SCENIC",
    "image": "https://...",
    "description": "走进白桦林..."
  }
]
```

前端在Step5选择行程中的景区/游玩项目节点，按新结构传即可。后端原样存取。

---

## 6. 行程保障模板（全新CRUD）

### 新增接口

| 方法 | URL | 说明 |
|------|-----|------|
| POST | `/admin/travel-guarantee-template` | 创建/更新模板 |
| DELETE | `/admin/travel-guarantee-template/{id}` | 删除模板 |
| GET | `/admin/travel-guarantee-template/list` | 全部模板列表（含禁用） |
| GET | `/admin/travel-guarantee-template/enabled` | 启用模板下拉（Step5选择用） |
| GET | `/admin/travel-guarantee-template/{id}` | 模板详情 |

**创建/更新请求体**：
```json
{
  "templateId": null,
  "name": "标准行程保障",
  "items": [
    {"icon": "shield", "title": "无忧退改", "description": "出发前7天全额退款"},
    {"icon": "users", "title": "5人专属团队", "description": "定制+管家+摄影+领队+客服"},
    {"icon": "clock", "title": "24小时客服", "description": "200位真实客服即时响应"},
    {"icon": "badge", "title": "旅行社责任险100万", "description": "正规资质全程投保"},
    {"icon": "heart", "title": "全程纯玩无购物", "description": "无强制消费无隐形购物点"}
  ],
  "isDefault": false
}
```

**Step5补充信息保存** 新增字段：

| 字段 | 类型 | 说明 |
|------|------|------|
| `guaranteeTemplateId` | Long | 行程保障模板ID |

**小程序详情** 新增字段：

| 字段 | 类型 | 说明 |
|------|------|------|
| `guaranteeItems` | Array | 行程保障项（自动解析模板内容） |

---

## 7. 线路概览自动生成

保存行程（Step2）后，自动根据各天的景区/活动节点名称生成线路概览文本，写入 `routeDescription`。

**生成格式示例**：
```
Day1 海拉尔/额尔古纳 | Day2 呼籁营地/牧云山顶 | Day3 白桦林/恩和 | Day4-5 满洲里/返程
```

连续天节点相同时自动合并（如Day4-5）。

---

## 8. 评价取真实数据

### GET /mp/product/{id} 新增字段

| 字段 | 类型 | 说明 |
|------|------|------|
| `reviewSummary` | Object | 评价摘要（从评价服务实时获取） |

`reviewSummary` 结构（由评价服务 `/internal/review/product-highlights` 返回）：
```json
{
  "avgScore": 4.9,
  "totalCount": 296,
  "topReview": {
    "content": "超赞的行程！呼籁营地安静私密...",
    "nickname": "小明同学",
    "reviewTime": "2026-03"
  },
  "tags": ["安静私密", "孩子玩疯了", "管家贴心", "强烈推荐"]
}
```

评价服务不可用时该字段为null，不影响其他数据。