changelog: 产品v2批量更新汇总(新接口+bug修复+模块搬迁)

changelogs/2026-04/2026-04-14_product-v2_batch_update.md

@@ -0,0 +1,126 @@
+# 产品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`