hl-api-changelog/changelogs/2026-03/2026-03-23_1607_9b7b524_fix_12.md

# 接口变更记录 — 2026-03-23 16:07

> **提交** `9b7b524` · **作者** wx · **时间** 2026-03-23 16:07:31 +0800
>
> fix: 订单全流程测试修复（12项）

## 变更总览

- **合同服务**
  - AdminContract (+1)
  - 🆕 AdminContractScheme (+7 接口)
- **小程序聚合服务**
  - MpOrder (+1)
- **订单服务**
  - InternalMpOrder (+1)

---

## 合同服务

### AdminContract

> 📖 **接口文档**: [http://192.168.100.236:8095/doc.html](http://192.168.100.236:8095/doc.html) → 标签 **「合同管理」**

### 🆕 `POST` /admin/contract/create-by-scheme — 按方案创建合同（简化）

> 只需传orderId和schemeId，后端自动从订单获取出行人、日期、联系人等数据，结合合同方案配置创建合同。

**响应** `Result<ContractDetailVO>`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `supplementaryClause` | `String` | 补充约定内容 |
| `travelers` | `List<TravelerVO>` | 出行人列表 |
| `statusLogs` | `List<StatusLogVO>` | 状态变更日志 |
| `travelerId` | `Long` | 出行人ID |
| `name` | `String` | 姓名 |
| `idCardType` | `String` | 证件类型 |
| `idCardNo` | `String` | 证件号码 |
| `phone` | `String` | 手机号 |
| `isSigner` | `Boolean` | 是否签署人 |
| `logId` | `Long` | 日志ID |
| `oldStatus` | `String` | 旧状态 |
| `newStatus` | `String` | 新状态 |
| `source` | `String` | 变更来源 |
| `createTime` | `LocalDateTime` | 创建时间 |

### 🆕 新增: AdminContractScheme

> 📖 **接口文档**: [http://192.168.100.236:8095/doc.html](http://192.168.100.236:8095/doc.html) → 标签 **「合同方案管理」**

### 📌 `GET` /admin/contract/scheme/list — 查询启用的合同方案列表

> 供产品配置时下拉选择使用，只返回启用状态的方案

**响应** `Result<List<ContractSchemeVO>>`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `schemeId` | `String` | 方案ID |
| `name` | `String` | 方案名称 |
| `description` | `String` | 方案描述 |
| `contractPlatform` | `String` | 合同平台: 12301/FADADA |
| `contractTemplateCode` | `String` | 合同模板编码（与模板列表的templateCode一致） |
| `templateCode` | `String` | 合同模板编码（别名，与contractTemplateCode相同值，方便前端统一使用templateCode） |
| `contractTemplateName` | `String` | 合同模板名称（回显用） |
| `contractMode` | `String` | 签约模式: STANDARD(电子签约)/SYNC(线下报备) |
| `signatoryMode` | `Integer` | 签署模式: 1=短信签署 2=现场签署 3=线下签署 |
| `agencyCode` | `String` | 旅行社编码 |
| `agencyName` | `String` | 旅行社名称（回显用） |
| `disputeResolution` | `Integer` | 争议解决方式: 1=仲裁 2=诉讼 |
| `supplementaryClause` | `String` | 补充条款 |
| `transactorName` | `String` | 经办人姓名 |
| `transactorPhone` | `String` | 经办人电话 |
| `sortOrder` | `Integer` | 排序 |
| `status` | `String` | 状态: ACTIVE/INACTIVE |
| `createTime` | `LocalDateTime` | 创建时间 |

### 📌 `GET` /admin/contract/scheme/list-all — 查询全部合同方案列表

> 管理页面使用，包含停用的方案

**响应** `Result<List<ContractSchemeVO>>`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `schemeId` | `String` | 方案ID |
| `name` | `String` | 方案名称 |
| `description` | `String` | 方案描述 |
| `contractPlatform` | `String` | 合同平台: 12301/FADADA |
| `contractTemplateCode` | `String` | 合同模板编码（与模板列表的templateCode一致） |
| `templateCode` | `String` | 合同模板编码（别名，与contractTemplateCode相同值，方便前端统一使用templateCode） |
| `contractTemplateName` | `String` | 合同模板名称（回显用） |
| `contractMode` | `String` | 签约模式: STANDARD(电子签约)/SYNC(线下报备) |
| `signatoryMode` | `Integer` | 签署模式: 1=短信签署 2=现场签署 3=线下签署 |
| `agencyCode` | `String` | 旅行社编码 |
| `agencyName` | `String` | 旅行社名称（回显用） |
| `disputeResolution` | `Integer` | 争议解决方式: 1=仲裁 2=诉讼 |
| `supplementaryClause` | `String` | 补充条款 |
| `transactorName` | `String` | 经办人姓名 |
| `transactorPhone` | `String` | 经办人电话 |
| `sortOrder` | `Integer` | 排序 |
| `status` | `String` | 状态: ACTIVE/INACTIVE |
| `createTime` | `LocalDateTime` | 创建时间 |

### 📌 `GET` /admin/contract/scheme/{schemeId} — 获取合同方案详情

**参数**

  - `{schemeId}` (`Long`) — 路径参数

**响应** `Result<ContractSchemeVO>`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `schemeId` | `String` | 方案ID |
| `name` | `String` | 方案名称 |
| `description` | `String` | 方案描述 |
| `contractPlatform` | `String` | 合同平台: 12301/FADADA |
| `contractTemplateCode` | `String` | 合同模板编码（与模板列表的templateCode一致） |
| `templateCode` | `String` | 合同模板编码（别名，与contractTemplateCode相同值，方便前端统一使用templateCode） |
| `contractTemplateName` | `String` | 合同模板名称（回显用） |
| `contractMode` | `String` | 签约模式: STANDARD(电子签约)/SYNC(线下报备) |
| `signatoryMode` | `Integer` | 签署模式: 1=短信签署 2=现场签署 3=线下签署 |
| `agencyCode` | `String` | 旅行社编码 |
| `agencyName` | `String` | 旅行社名称（回显用） |
| `disputeResolution` | `Integer` | 争议解决方式: 1=仲裁 2=诉讼 |
| `supplementaryClause` | `String` | 补充条款 |
| `transactorName` | `String` | 经办人姓名 |
| `transactorPhone` | `String` | 经办人电话 |
| `sortOrder` | `Integer` | 排序 |
| `status` | `String` | 状态: ACTIVE/INACTIVE |
| `createTime` | `LocalDateTime` | 创建时间 |

### 📌 `POST` /admin/contract/scheme — 创建合同方案

**请求体** `ContractSchemeRequest`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `name` | `String` | 方案名称 |
| `description` | `String` | 方案描述 |
| `contractPlatform` | `String` | 合同平台: 12301/FADADA |
| `contractTemplateCode` | `String` | 合同模板编码 |
| `contractMode` | `String` | 签约模式: STANDARD(电子签约)/SYNC(线下报备) |
| `signatoryMode` | `Integer` | 签署模式: 1=短信签署 2=现场签署 3=线下签署 |
| `agencyCode` | `String` | 旅行社编码(可选，不填则根据订单支付商户号自动匹配旅行社) |
| `disputeResolution` | `Integer` | 争议解决方式: 1=仲裁 2=诉讼 |
| `supplementaryClause` | `String` | 补充条款(可选) |
| `transactorName` | `String` | 经办人姓名 |
| `transactorPhone` | `String` | 经办人电话 |
| `sortOrder` | `Integer` | 排序(越小越靠前) |

**响应** `Result<ContractSchemeVO>`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `schemeId` | `String` | 方案ID |
| `name` | `String` | 方案名称 |
| `description` | `String` | 方案描述 |
| `contractPlatform` | `String` | 合同平台: 12301/FADADA |
| `contractTemplateCode` | `String` | 合同模板编码（与模板列表的templateCode一致） |
| `templateCode` | `String` | 合同模板编码（别名，与contractTemplateCode相同值，方便前端统一使用templateCode） |
| `contractTemplateName` | `String` | 合同模板名称（回显用） |
| `contractMode` | `String` | 签约模式: STANDARD(电子签约)/SYNC(线下报备) |
| `signatoryMode` | `Integer` | 签署模式: 1=短信签署 2=现场签署 3=线下签署 |
| `agencyCode` | `String` | 旅行社编码 |
| `agencyName` | `String` | 旅行社名称（回显用） |
| `disputeResolution` | `Integer` | 争议解决方式: 1=仲裁 2=诉讼 |
| `supplementaryClause` | `String` | 补充条款 |
| `transactorName` | `String` | 经办人姓名 |
| `transactorPhone` | `String` | 经办人电话 |
| `sortOrder` | `Integer` | 排序 |
| `status` | `String` | 状态: ACTIVE/INACTIVE |
| `createTime` | `LocalDateTime` | 创建时间 |

### 📌 `PUT` /admin/contract/scheme/{schemeId} — 更新合同方案

**参数**

  - `{schemeId}` (`Long`) — 路径参数

**请求体** `ContractSchemeRequest`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `name` | `String` | 方案名称 |
| `description` | `String` | 方案描述 |
| `contractPlatform` | `String` | 合同平台: 12301/FADADA |
| `contractTemplateCode` | `String` | 合同模板编码 |
| `contractMode` | `String` | 签约模式: STANDARD(电子签约)/SYNC(线下报备) |
| `signatoryMode` | `Integer` | 签署模式: 1=短信签署 2=现场签署 3=线下签署 |
| `agencyCode` | `String` | 旅行社编码(可选，不填则根据订单支付商户号自动匹配旅行社) |
| `disputeResolution` | `Integer` | 争议解决方式: 1=仲裁 2=诉讼 |
| `supplementaryClause` | `String` | 补充条款(可选) |
| `transactorName` | `String` | 经办人姓名 |
| `transactorPhone` | `String` | 经办人电话 |
| `sortOrder` | `Integer` | 排序(越小越靠前) |

**响应** `Result<ContractSchemeVO>`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `schemeId` | `String` | 方案ID |
| `name` | `String` | 方案名称 |
| `description` | `String` | 方案描述 |
| `contractPlatform` | `String` | 合同平台: 12301/FADADA |
| `contractTemplateCode` | `String` | 合同模板编码（与模板列表的templateCode一致） |
| `templateCode` | `String` | 合同模板编码（别名，与contractTemplateCode相同值，方便前端统一使用templateCode） |
| `contractTemplateName` | `String` | 合同模板名称（回显用） |
| `contractMode` | `String` | 签约模式: STANDARD(电子签约)/SYNC(线下报备) |
| `signatoryMode` | `Integer` | 签署模式: 1=短信签署 2=现场签署 3=线下签署 |
| `agencyCode` | `String` | 旅行社编码 |
| `agencyName` | `String` | 旅行社名称（回显用） |
| `disputeResolution` | `Integer` | 争议解决方式: 1=仲裁 2=诉讼 |
| `supplementaryClause` | `String` | 补充条款 |
| `transactorName` | `String` | 经办人姓名 |
| `transactorPhone` | `String` | 经办人电话 |
| `sortOrder` | `Integer` | 排序 |
| `status` | `String` | 状态: ACTIVE/INACTIVE |
| `createTime` | `LocalDateTime` | 创建时间 |

### 📌 `PUT` /admin/contract/scheme/{schemeId}/toggle-status — 切换方案启用/停用状态

**参数**

  - `{schemeId}` (`Long`) — 路径参数

**响应** `Result<ContractSchemeVO>`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `schemeId` | `String` | 方案ID |
| `name` | `String` | 方案名称 |
| `description` | `String` | 方案描述 |
| `contractPlatform` | `String` | 合同平台: 12301/FADADA |
| `contractTemplateCode` | `String` | 合同模板编码（与模板列表的templateCode一致） |
| `templateCode` | `String` | 合同模板编码（别名，与contractTemplateCode相同值，方便前端统一使用templateCode） |
| `contractTemplateName` | `String` | 合同模板名称（回显用） |
| `contractMode` | `String` | 签约模式: STANDARD(电子签约)/SYNC(线下报备) |
| `signatoryMode` | `Integer` | 签署模式: 1=短信签署 2=现场签署 3=线下签署 |
| `agencyCode` | `String` | 旅行社编码 |
| `agencyName` | `String` | 旅行社名称（回显用） |
| `disputeResolution` | `Integer` | 争议解决方式: 1=仲裁 2=诉讼 |
| `supplementaryClause` | `String` | 补充条款 |
| `transactorName` | `String` | 经办人姓名 |
| `transactorPhone` | `String` | 经办人电话 |
| `sortOrder` | `Integer` | 排序 |
| `status` | `String` | 状态: ACTIVE/INACTIVE |
| `createTime` | `LocalDateTime` | 创建时间 |

### 📌 `DELETE` /admin/contract/scheme/{schemeId} — 删除合同方案

**参数**

  - `{schemeId}` (`Long`) — 路径参数

**响应** `Result<Void>`

---

## 小程序聚合服务

### MpOrder

> 📖 **接口文档**: [http://192.168.100.236:8086/doc.html](http://192.168.100.236:8086/doc.html) → 标签 **「C端 - 订单接口」**

### 🆕 `PUT` /mp/order/{orderId}/remark — 添加/修改订单备注

> 用户在订单详情页添加或修改备注。备注对管理端可见。
请求体：{"remark": "备注内容"}

**参数**

  - `{orderId}` (`Long`) — 路径参数

**响应** `Result<Void>`

---

## 订单服务

### InternalMpOrder

> 📖 **接口文档**: [http://192.168.100.236:8084/doc.html](http://192.168.100.236:8084/doc.html) → 标签 **「【内部接口】小程序订单（Feign调用）」**

### 🆕 `PUT` /internal/mp/order/{orderId}/remark — 添加/修改订单备注

> 用户在订单详情页添加或修改备注内容

**参数**

  - `{orderId}` (`Long`) — 路径参数
  - `userId` (`Long`) — 查询参数

**响应** `Result<Void>`

---

## 📦 其他数据对象变更

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

### 小程序聚合服务

#### ✏️ MpOrderDetailVO

  - 🆕 `hotelAssignmentDetails` (`List<Map<String, Object>>`) — 酒店分配详情（按家庭分组，含封面图）
  - ✏️ `hotelAssignments`: 说明 "酒店分配信息JSON" → "酒店分配信息JSON（原始数据）"

### 订单服务

#### ✏️ AdminUpdateOrderRequest

  - 🆕 `customizerId` (`Long`) — 定制师ID（切换定制师）

#### 🆕 HotelAssignmentVO

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `familyIndex` | `Integer` | 家庭序号（从1开始） |
| `familyLabel` | `String` | 家庭标签（如：家庭1、家庭2） |
| `days` | `List<DayAssignment>` | 每天的住宿分配列表 |
| `date` | `String` | 日期（yyyy-MM-dd） |
| `hotelId` | `Long` | 酒店ID |
| `hotelName` | `String` | 酒店名称 |
| `hotelCoverUrl` | `String` | 酒店封面图URL（从产品快照提取，可能为空） |
| `roomTypeId` | `Long` | 房型ID |
| `roomType` | `String` | 房型名称 |
| `roomTypeCoverUrl` | `String` | 房型封面图URL（从产品快照提取，可能为空） |
| `roomCount` | `Integer` | 房间数量 |
| `remark` | `String` | 备注 |

#### ✏️ OrderDetailVO

  - 🆕 `productTypeLabel` (`String`) — 产品类型中文标签（CORE=核心产品, CUSTOM=私人定制, GROUP=小蒙马, ROUTE=路书产品）
  - 🆕 `pendingUpgradeAmount` (`BigDecimal`) — 待确认差价总额（配房/配车升级未确认的差价）
  - 🆕 `paymentModeLabel` (`String`) — 支付模式中文标签（DEPOSIT=定金+尾款, FULL=全款）
  - 🆕 `hotelAssignmentDetails` (`List<HotelAssignmentVO>`) — 酒店分配详情（按家庭分组，含封面图）
  - ✏️ `hotelAssignments`: 说明 "酒店分配信息JSON" → "酒店分配信息JSON（原始数据）"

#### 🆕 SurchargeRequest

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `surchargeName` | `String` | 费用增加项名称 |
| `surchargeAmount` | `BigDecimal` | 费用增加金额 |

#### ✏️ VehicleAssignmentRequest

  - ✏️ `vehicleBrand`: 说明 "品牌" → "品牌（选填，不传则从车型名称中提取）"

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

```
M	hl-contract-service/src/main/java/com/hulalv/contract/config/ContractPlatformProperties.java
M	hl-contract-service/src/main/java/com/hulalv/contract/constant/ContractConstants.java
M	hl-contract-service/src/main/java/com/hulalv/contract/controller/AdminContractController.java
A	hl-contract-service/src/main/java/com/hulalv/contract/controller/AdminContractSchemeController.java
A	hl-contract-service/src/main/java/com/hulalv/contract/dto/ContractSchemeRequest.java
A	hl-contract-service/src/main/java/com/hulalv/contract/entity/ContractScheme.java
M	hl-contract-service/src/main/java/com/hulalv/contract/feign/OrderContractFeignClient.java
A	hl-contract-service/src/main/java/com/hulalv/contract/job/ContractStatusRefreshJob.java
A	hl-contract-service/src/main/java/com/hulalv/contract/mapper/ContractSchemeMapper.java
M	hl-contract-service/src/main/java/com/hulalv/contract/platform/ContractApplyParam.java
M	hl-contract-service/src/main/java/com/hulalv/contract/platform/ContractPlatform.java
M	hl-contract-service/src/main/java/com/hulalv/contract/platform/fadada/FadadaContractPlatform.java
M	hl-contract-service/src/main/java/com/hulalv/contract/platform/tourage/TourageApiClient.java
M	hl-contract-service/src/main/java/com/hulalv/contract/platform/tourage/TourageContractPlatform.java
A	hl-contract-service/src/main/java/com/hulalv/contract/service/ContractSchemeService.java
M	hl-contract-service/src/main/java/com/hulalv/contract/service/ContractService.java
A	hl-contract-service/src/main/java/com/hulalv/contract/vo/ContractSchemeVO.java
M	hl-contract-service/src/test/java/com/hulalv/contract/platform/ContractPlatformFactoryTest.java
M	hl-contract-service/src/test/java/com/hulalv/contract/platform/fadada/FadadaContractPlatformTest.java
M	hl-contract-service/src/test/java/com/hulalv/contract/platform/tourage/TourageContractPlatformTest.java
M	hl-contract-service/src/test/java/com/hulalv/contract/service/ContractServiceTest.java
M	hl-insurance-service/src/main/java/com/hulalv/insurance/service/InsuranceOrderService.java
M	hl-mp-service/src/main/java/com/hulalv/mp/controller/MpOrderController.java
M	hl-mp-service/src/main/java/com/hulalv/mp/feign/MpOrderFeignClient.java
M	hl-mp-service/src/main/java/com/hulalv/mp/feign/MpOrderFeignFallbackFactory.java
M	hl-mp-service/src/main/java/com/hulalv/mp/vo/MpOrderDetailVO.java
M	hl-order-service/src/main/java/com/hulalv/order/constant/OrderConstants.java
M	hl-order-service/src/main/java/com/hulalv/order/controller/AdminOrderController.java
M	hl-order-service/src/main/java/com/hulalv/order/controller/InternalMpOrderController.java
M	hl-order-service/src/main/java/com/hulalv/order/controller/InternalPaymentOrderController.java
M	hl-order-service/src/main/java/com/hulalv/order/dto/AdminUpdateOrderRequest.java
A	hl-order-service/src/main/java/com/hulalv/order/dto/SurchargeRequest.java
M	hl-order-service/src/main/java/com/hulalv/order/dto/VehicleAssignmentRequest.java
A	hl-order-service/src/main/java/com/hulalv/order/entity/OrderSurcharge.java
M	hl-order-service/src/main/java/com/hulalv/order/entity/OrderTimeline.java
M	hl-order-service/src/main/java/com/hulalv/order/entity/OrderTodo.java
M	hl-order-service/src/main/java/com/hulalv/order/entity/OrderTraveler.java
M	hl-order-service/src/main/java/com/hulalv/order/job/DepartureReminderJob.java
A	hl-order-service/src/main/java/com/hulalv/order/mapper/OrderSurchargeMapper.java
M	hl-order-service/src/main/java/com/hulalv/order/service/OrderCascadeService.java
M	hl-order-service/src/main/java/com/hulalv/order/service/OrderItineraryEditService.java
M	hl-order-service/src/main/java/com/hulalv/order/service/OrderPriceDiffService.java
M	hl-order-service/src/main/java/com/hulalv/order/service/OrderService.java
A	hl-order-service/src/main/java/com/hulalv/order/service/OrderSurchargeService.java
M	hl-order-service/src/main/java/com/hulalv/order/service/OrderTodoService.java
A	hl-order-service/src/main/java/com/hulalv/order/vo/HotelAssignmentVO.java
M	hl-order-service/src/main/java/com/hulalv/order/vo/OrderDetailVO.java
A	hl-product-service/src/main/java/com/hulalv/product/feign/InsuranceSchemeFallbackFactory.java
A	hl-product-service/src/main/java/com/hulalv/product/feign/InsuranceSchemeFeignClient.java
```
</details>