# 产品v2 - 批量更新汇总 (4/13-4/14)

**日期**: 2026-04-14
**服务**: product-service-v2, hl-starter-mybatis
**类型**: 新增接口 + Bug修复 + 模块搬迁
**PR**: #431, #433, #442, #446, #447, #448, #449, #450, #451, #457, #472, #474

---

## 一、新增接口

### 1. 计算行程总里程
`GET /admin/product/item/{productId}/calculate-mileage`

根据行程途经点坐标调用高德驾车路线规划API自动计算总驾驶里程。

**返回**:
```json
{"code": 200, "data": 690.2}
```
- data: 总里程(km)，保留1位小数
- 前提：产品需先保存行程(Step2)，至少2个有效途经点

**建议交互**: Step3页面提供"自动计算里程"按钮，调此接口填充总里程输入框。

---

### 2. 温馨提示管理（从v1搬迁）
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/admin/product/warm-tips/list` | 全部列表（含禁用） |
| GET | `/admin/product/warm-tips/enabled` | 启用列表（下拉选择用） |
| GET | `/admin/product/warm-tips/{tipsId}` | 详情 |
| POST | `/admin/product/warm-tips` | 创建 |
| PUT | `/admin/product/warm-tips/{tipsId}` | 修改 |
| DELETE | `/admin/product/warm-tips/{tipsId}` | 删除（软删） |
| PUT | `/admin/product/warm-tips/{tipsId}/toggle?enabled=true/false` | 启用/禁用 |

**请求体**(创建/修改):
```json
{"tipsName": "草原游温馨提示", "content": "<p>富文本内容</p>", "remark": "备注"}
```

---

### 3. 预订条款管理（从v1搬迁）
接口结构与温馨提示完全一致，路径前缀改为 `/admin/product/booking-terms`，字段名改为 `termsId`/`termsName`。

---

### 4. 报价公式管理（从v1搬迁）

#### 公式组
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/admin/product/formula/group/list?productType=CORE` | 公式组列表 |
| GET | `/admin/product/formula/group/{groupId}` | 详情 |
| POST | `/admin/product/formula/group` | 创建 |
| PUT | `/admin/product/formula/group/{groupId}` | 修改 |
| PUT | `/admin/product/formula/group/{groupId}/activate` | 激活（排他） |
| DELETE | `/admin/product/formula/group/{groupId}` | 删除 |

#### 公式步骤
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/admin/product/formula/group/{groupId}/steps` | 步骤列表 |
| GET | `/admin/product/formula/step/{formulaId}` | 步骤详情 |
| POST | `/admin/product/formula/step` | 创建步骤 |
| PUT | `/admin/product/formula/step/{formulaId}` | 修改步骤 |
| PUT | `/admin/product/formula/step/{formulaId}/toggle` | 启用/禁用 |
| DELETE | `/admin/product/formula/step/{formulaId}` | 删除 |
| GET | `/admin/product/formula/step/{formulaId}/versions` | 版本历史 |
| PUT | `/admin/product/formula/step/{formulaId}/rollback/{versionNum}` | 回滚版本 |

#### 公式变量
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/admin/product/formula/var/list?category=INPUT` | 变量列表 |
| POST | `/admin/product/formula/var` | 创建变量 |
| PUT | `/admin/product/formula/var/{varId}` | 修改变量 |
| DELETE | `/admin/product/formula/var/{varId}` | 删除 |

#### 公式测试
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/admin/product/formula/test` | 测试执行 |

---

## 二、Bug修复

### 1. 产品详情 routeInfo 返回null（已修复）
**原因**: SQL JOIN返回扁平的totalMileage/routeDescription/routeMapUrl字段，但VO期望嵌套routeInfo对象，BeanUtil无法自动映射。
**影响**: Step3保存的总里程/线路描述回显为空。
**现在**: routeInfo正常返回嵌套对象。

### 2. 详情接口返回数据清理（已修复）
- **routePoints**: 去掉了createTime/updateTime/createdBy等审计字段，只返回`id/resourceId/name/longitude/latitude/sortOrder`
- **nodes/hotels/days**: 同样去掉审计字段
- **JSON字段反序列化**: photoUrls/customFields/images/extraData从JSON字符串正确转为对象/数组

### 3. supplement JSON字段双重转义（已修复）
**原因**: quickUnderstand/childExperience/growthGains等JSON字段以String存储，Jackson序列化时双重转义。
**方案**: 新增全局`JsonObjectTypeHandler`，Entity字段改为Object + `@TableField(typeHandler)`，自动在DB和Java间转换JSON。
**影响**: 前端之前收到的是转义字符串`"{\"title\":\"xxx\"}"`,现在收到正常JSON对象`{"title":"xxx"}`。

### 4. 行程保存事务不生效（已修复）
**原因**: saveItinerary()自调用doSaveItinerary()，Spring AOP代理不拦截，@Transactional无效。
**影响**: 保存行程时报"Transaction synchronization is not active"。
**现在**: 通过@Lazy setter注入自身代理解决。

### 5. 无效住宿记录过滤（已修复）
**原因**: 前端传空住宿对象`{}`时后端直接插入，导致hotel_name=NULL显示"未知"。
**现在**: 新增住宿必须有hotelId才插入。

### 6. 模板Controller路由冲突（已修复）
AdminProductTemplateController的`/booking-terms/enabled`和`/warm-tips/enabled`已迁移到独立Controller，旧方法已删除。

---

## 三、前端注意事项

1. **报价公式/温馨提示/预订条款页面**: 接口已从v1迁移到v2，路径不变，无需前端改动
2. **Step3里程**: 可调用`GET /{id}/calculate-mileage`自动计算填充
3. **supplement字段**: quickUnderstand/childExperience/growthGains现在返回JSON对象而非字符串，如果前端之前有`JSON.parse()`处理需要去掉
4. **routePoints**: 字段减少了，只有`id/resourceId/name/longitude/latitude/sortOrder`