# 接口变更记录 — 2026-03-17 12:44

> **提交** `87da085` · **作者** wx · **时间** 2026-03-17 12:44:59 +0800
>
> feat: 产品统一保存接口 + 资源价格日历字段增强 + Knife4j分组名修复

## 变更总览

- **产品服务**
  - Product (+1)

---

## 产品服务

### Product

#### 🆕 `POST` /admin/product/item/save — 保存产品（统一创建/更新）

**请求体** `ProductSaveRequest`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `productId` | `Long` | 产品ID（传入则更新，不传则创建） |
| `name` | `String` | 产品名称 |
| `subtitle` | `String` | 副标题 |
| `productType` | `String` | 产品类型：CORE=核心产品 ROUTE=线路产品 CUSTOM=定制产品 GROUP=小蒙马拼团（创建时必填，更新时忽略） |
| `tripDays` | `Integer` | 行程天数 |
| `departureCity` | `String` | 出发城市 |
| `destinationCity` | `String` | 目的地城市 |
| `seasons` | `List<String>` | 适用季节列表，如 [\ |
| `tags` | `List<String>` | 产品标签列表，如 [\ |
| `isBooking` | `Boolean` | 是否预约产品 |
| `adultCount` | `Integer` | 成人人数 |
| `childCount` | `Integer` | 儿童人数 |
| `youngChildCount` | `Integer` | 小童人数 |
| `babyCount` | `Integer` | 婴儿人数 |
| `minAdultPerOrder` | `Integer` | 每单最少成人数(不填默认1) |
| `maxAdultPerOrder` | `Integer` | 每单最大成人数(不填则不限制) |
| `maxChildPerOrder` | `Integer` | 每单最大儿童数(不填则不限制) |
| `coverImageUrl` | `String` | 封面图URL |
| `carouselImages` | `List<String>` | 轮播图列表 |
| `carouselVideoUrl` | `String` | 轮播视频URL |
| `folderId` | `String` | 所属文件夹ID |
| `lineId` | `String` | 产品线ID |
| `creatorAvatarUrl` | `String` | 定制师头像URL |
| `creatorIntro` | `String` | 创作者寄语 |
| `groupChatQrUrl` | `String` | 群聊二维码URL |
| `chatMessages` | `List<ChatMessageVO>` | 群聊消息列表 |
| `showReview` | `Boolean` | 是否显示评价 |
| `showChatGroup` | `Boolean` | 是否显示群聊入口 |
| `showTripTime` | `Boolean` | 是否显示行程时间 |
| `showTripDistance` | `Boolean` | 是否显示行程距离 |
| `bookingNotice` | `String` | 预定须知 |
| `cancelPolicy` | `String` | 退改政策 |
| `warmTips` | `String` | 温馨提示 |
| `customizerId` | `String` | 定制师ID |
| `sortOrder` | `Integer` | 排序序号 |
| `teamExperienceYears` | `Integer` | 团队经验年数 |
| `lineSubtitle` | `String` | 产品线副标题 |
| `mchId` | `String` | 商户号：shanhe/wenlu |
| `groupRoomId` | `String` | 企微群聊ID(用于会话存档展示群消息) |

**响应** `Result<ProductVO>`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `productId` | `String` | 产品ID |
| `productNo` | `String` | 产品编号 |
| `productType` | `String` | 产品类型：CORE=核心产品 ROUTE=线路产品 CUSTOM=定制产品 GROUP=小蒙马拼团 |
| `name` | `String` | 产品名称 |
| `subtitle` | `String` | 副标题 |
| `tripDays` | `Integer` | 行程天数 |
| `tripNights` | `Integer` | 行程晚数 |
| `departureCity` | `String` | 出发城市 |
| `destinationCity` | `String` | 目的地城市 |
| `destinationCities` | `List<String>` | 途经城市列表（从行程节点资源去重提取） |
| `seasons` | `List<String>` | 适用季节列表 |
| `isBooking` | `Boolean` | 是否预约产品 |
| `paymentMode` | `String` | 支付模式：FULL=全款 DEPOSIT=定金+尾款 |
| `adultCount` | `Integer` | 成人人数 |
| `childCount` | `Integer` | 儿童人数 |
| `youngChildCount` | `Integer` | 小童人数 |
| `babyCount` | `Integer` | 婴儿人数 |
| `minAdultPerOrder` | `Integer` | 每单最少成人数(null=默认1) |
| `maxAdultPerOrder` | `Integer` | 每单最大成人数(null=不限) |
| `maxChildPerOrder` | `Integer` | 每单最大儿童数(null=不限) |
| `routeMapUrl` | `String` | 路径图URL（后端自动生成） |
| `status` | `String` | 产品状态：DRAFT/PENDING_REVIEW/REVIEWED/REJECTED/PUBLISHED/UNPUBLISHED/COMPLETED |
| `tags` | `List<String>` | 产品标签列表 |
| `coverImageUrl` | `String` | 封面图URL |
| `carouselImages` | `List<String>` | 轮播图列表 |
| `carouselVideoUrl` | `String` | 轮播视频URL |
| `folderId` | `String` | 所属文件夹ID |
| `lineId` | `String` | 产品线ID |
| `lineName` | `String` | 产品线名称 |
| `creatorAvatarUrl` | `String` | 定制师头像URL |
| `creatorIntro` | `String` | 创作者寄语 |
| `groupChatQrUrl` | `String` | 群聊二维码URL |
| `chatMessages` | `List<ChatMessageVO>` | 群聊消息列表 |
| `showReview` | `Boolean` | 是否显示评价 |
| `showChatGroup` | `Boolean` | 是否显示群聊入口 |
| `showTripTime` | `Boolean` | 是否显示行程时间 |
| `showTripDistance` | `Boolean` | 是否显示行程距离 |
| `bookingNotice` | `String` | 预定须知 |
| `cancelPolicy` | `String` | 退改政策 |
| `warmTips` | `String` | 温馨提示 |
| `customizerId` | `String` | 定制师ID |
| `publishedAt` | `LocalDateTime` | 发布时间 |
| `sortOrder` | `Integer` | 排序序号 |
| `teamExperienceYears` | `Integer` | 团队经验年数 |
| `lineSubtitle` | `String` | 产品线副标题 |
| `createBy` | `String` | 创建人ID |
| `mchId` | `String` | 商户号 |
| `groupRoomId` | `String` | 企微群聊ID(用于会话存档展示群消息) |
| `updateBy` | `String` | 更新人ID |
| `createTime` | `LocalDateTime` | 创建时间 |
| `updateTime` | `LocalDateTime` | 更新时间 |
| `startPrice` | `BigDecimal` | 起步价：未来一年价格日历中最低成人售价 |
| `itineraryDays` | `List<ItineraryDayVO>` | 行程天列表 |
| `pricing` | `ProductPricingVO` | 定价配置 |
| `costItems` | `List<ProductCostItemVO>` | 成本项列表 |
| `customFees` | `List<ProductCustomFeeVO>` | 自定义费用项列表 |
| `suppliesList` | `List<ProductSuppliesVO>` | 物资列表 |
| `staffConfigs` | `List<ProductStaffConfigVO>` | 人员配置列表（定制产品） |
| `families` | `List<ProductFamilyVO>` | 家庭分组列表（定制产品） |
| `benefitsDescription` | `List<BenefitGroupVO>` | 权益说明（静态，所有产品相同） |

**关联字典**

- `product_type`（产品类型，创建时必填）：CORE=核心产品, GROUP=小蒙马拼团, CUSTOM=定制产品, ROUTE=线路产品
- `product_status`（产品状态，返回字段）：DRAFT=草稿, PENDING_REVIEW=待审核, REVIEWED=已审核, REJECTED=已驳回, PUBLISHED=已上架, UNPUBLISHED=已下架, COMPLETED=已完成, ORDERED=已下单
- `product_category`（产品分类）：family=亲子游, honeymoon=蜜月游, photography=旅拍, experience=体验, driving=自驾

---

## 📦 其他数据对象变更

> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应

### 保险服务

#### ✏️ PolicyShareVO

  - ✏️ `pdfBase64`: 说明 "merged PDF as base64" → "合并后的PDF（Base64编码）"
  - ✏️ `personName`: 说明 "insured person name" → "被保人姓名"
  - ✏️ `policyCount`: 说明 "number of policies included" → "包含的保单数量"
  - ✏️ `failedCount`: 说明 "number of policies that failed to download (skipped)" → "下载失败的保单数量（已跳过）"

#### ✏️ SharePolicyRequest

  - ✏️ `orderId`: 说明 "travel order ID" → "旅游订单ID"
  - ✏️ `insuredName`: 说明 "insured person name" → "被保人姓名"
  - ✏️ `insuredIdCardNo`: 说明 "insured person ID card number" → "被保人证件号码"

### 资源服务

#### ✏️ PriceCalendarDayVO

  - ✏️ `status`: 类型 `Integer` → `String`, 说明 "状态：0=不可租 1=可租" → "日历状态（字典 calendar_status：AVAILABLE=可售 SOLD_OUT=已售罄 CLOSED=已关闭）"

#### ✏️ PriceCalendarSetRequest

  - ✏️ `status`: 类型 `Integer` → `String`, 说明 "状态：0=不可租 1=可租" → "日历状态（字典 calendar_status：AVAILABLE=可售 SOLD_OUT=已售罄 CLOSED=已关闭）"

#### ✏️ PriceCalendarStatusRequest

  - ✏️ `status`: 类型 `Integer` → `String`, 说明 "状态：0=不可租 1=可租" → "目标状态（字典 calendar_status：AVAILABLE=可售 SOLD_OUT=已售罄 CLOSED=已关闭）"

<details>
<summary>📁 全部变更文件 (点击展开)</summary>

```
M	hl-insurance-service/src/main/java/com/hulalv/insurance/config/Knife4jConfig.java
M	hl-insurance-service/src/main/java/com/hulalv/insurance/dto/SharePolicyRequest.java
M	hl-insurance-service/src/main/java/com/hulalv/insurance/service/BaoyouApiClient.java
M	hl-insurance-service/src/main/java/com/hulalv/insurance/service/InsuranceProductSyncService.java
M	hl-insurance-service/src/main/java/com/hulalv/insurance/vo/PolicyShareVO.java
M	hl-product-service/src/main/java/com/hulalv/product/config/Knife4jConfig.java
M	hl-product-service/src/main/java/com/hulalv/product/controller/ProductController.java
A	hl-product-service/src/main/java/com/hulalv/product/dto/ProductSaveRequest.java
M	hl-product-service/src/main/java/com/hulalv/product/service/ProductService.java
M	hl-resource-service/src/main/java/com/hulalv/resource/activity/constant/ActivityConstants.java
M	hl-resource-service/src/main/java/com/hulalv/resource/activity/dto/PriceCalendarSetRequest.java
M	hl-resource-service/src/main/java/com/hulalv/resource/activity/dto/PriceCalendarStatusRequest.java
M	hl-resource-service/src/main/java/com/hulalv/resource/activity/entity/ActivityPriceCalendar.java
M	hl-resource-service/src/main/java/com/hulalv/resource/activity/vo/PriceCalendarDayVO.java
M	hl-resource-service/src/main/java/com/hulalv/resource/cost/constant/CostConstants.java
M	hl-resource-service/src/main/java/com/hulalv/resource/cost/entity/CostPriceCalendar.java
M	hl-resource-service/src/main/java/com/hulalv/resource/cost/vo/PriceCalendarDayVO.java
M	hl-resource-service/src/main/java/com/hulalv/resource/hotel/constant/HotelConstants.java
M	hl-resource-service/src/main/java/com/hulalv/resource/hotel/dto/PriceCalendarSetRequest.java
M	hl-resource-service/src/main/java/com/hulalv/resource/hotel/dto/PriceCalendarStatusRequest.java
M	hl-resource-service/src/main/java/com/hulalv/resource/hotel/entity/RoomPriceCalendar.java
M	hl-resource-service/src/main/java/com/hulalv/resource/hotel/vo/PriceCalendarDayVO.java
M	hl-resource-service/src/main/java/com/hulalv/resource/scenic/constant/ScenicConstants.java
M	hl-resource-service/src/main/java/com/hulalv/resource/scenic/dto/PriceCalendarSetRequest.java
M	hl-resource-service/src/main/java/com/hulalv/resource/scenic/dto/PriceCalendarStatusRequest.java
M	hl-resource-service/src/main/java/com/hulalv/resource/scenic/entity/ScenicPriceCalendar.java
M	hl-resource-service/src/main/java/com/hulalv/resource/scenic/service/ScenicPriceCalendarService.java
M	hl-resource-service/src/main/java/com/hulalv/resource/scenic/vo/PriceCalendarDayVO.java
M	hl-resource-service/src/main/java/com/hulalv/resource/service/constant/ServiceConstants.java
M	hl-resource-service/src/main/java/com/hulalv/resource/service/dto/PriceCalendarSetRequest.java
M	hl-resource-service/src/main/java/com/hulalv/resource/service/dto/PriceCalendarStatusRequest.java
M	hl-resource-service/src/main/java/com/hulalv/resource/service/entity/ServicePriceCalendar.java
M	hl-resource-service/src/main/java/com/hulalv/resource/service/vo/PriceCalendarDayVO.java
M	hl-resource-service/src/main/java/com/hulalv/resource/staff/constant/StaffConstants.java
M	hl-resource-service/src/main/java/com/hulalv/resource/staff/dto/PriceCalendarSetRequest.java
M	hl-resource-service/src/main/java/com/hulalv/resource/staff/dto/PriceCalendarStatusRequest.java
M	hl-resource-service/src/main/java/com/hulalv/resource/staff/entity/StaffPriceCalendar.java
M	hl-resource-service/src/main/java/com/hulalv/resource/staff/vo/PriceCalendarDayVO.java
M	hl-resource-service/src/main/java/com/hulalv/resource/vehicle/constant/VehicleConstants.java
M	hl-resource-service/src/main/java/com/hulalv/resource/vehicle/dto/PriceCalendarSetRequest.java
M	hl-resource-service/src/main/java/com/hulalv/resource/vehicle/dto/PriceCalendarStatusRequest.java
M	hl-resource-service/src/main/java/com/hulalv/resource/vehicle/entity/VehiclePriceCalendar.java
M	hl-resource-service/src/main/java/com/hulalv/resource/vehicle/vo/PriceCalendarDayVO.java
A	scripts/api-changelog-sync.py
A	scripts/sync-api-docs.py
```
</details>