# 合同服务 API 文档

**服务**: `hl-contract-service`
**接口总数**: 18

## 目录

- **合同管理** (12 个接口)
- **补充约定模板管理** (6 个接口)

---

## 合同管理

### `GET` /admin/contract/active-by-order/{orderId}

**获取订单有效合同**

返回订单当前有效的合同（非作废状态的最新合同），用于检查订单是否已有签署中或已签署的合同。

**权限**：需管理员登录。

**关联字典**：
- contract_status：合同状态（显示）

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `orderId` | `integer` |  | 订单ID |

**响应** `统一响应结果«合同信息»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `合同信息` |  | 响应数据 |
|   `agencyCode` | `string` |  | 旅行社编号 |
|   `contactName` | `string` |  | 联系人姓名 |
|   `contactPhone` | `string` |  | 联系人电话 |
|   `contractId` | `long` |  | 合同ID |
|   `contractNumber` | `string` |  | 合同编号 |
|   `contractType` | `string` |  | 合同类型: TOUR-旅游合同, INSURANCE-保险单 |
|   `createTime` | `string` |  | 创建时间 |
|   `departureDate` | `string` |  | 出发日期 |
|   `destination` | `string` |  | 目的地 |
|   `fileUrl` | `string` |  | 合同文件URL |
|   `mode` | `string` |  | 签约模式: STANDARD/SYNC |
|   `orderId` | `long` |  | 订单ID |
|   `platform` | `string` |  | 签约平台 |
|   `qrCodeUrl` | `string` |  | 二维码URL |
|   `returnDate` | `string` |  | 返回日期 |
|   `signUrl` | `string` |  | 签署URL |
|   `status` | `string` |  | 合同状态 |
|   `statusLabel` | `string` |  | 合同状态标签 |
|   `templateCode` | `string` |  | 模板编码 |
|   `templateName` | `string` |  | 模板名称 |
|   `totalAmount` | `number` |  | 合同总金额 |
|   `touristCount` | `int` |  | 出行人数 |
|   `travelAgencyName` | `string` |  | 旅行社名称 |
| `message` | `string` |  | 响应消息 |

---

### `GET` /admin/contract/agencies

**可用旅行社列表**

返回系统配置的旅行社列表，创建合同时选择签约旅行社

**响应** `统一响应结果«List«旅行社信息»»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `旅行社信息[]` |  | 响应数据 |
|   `agencyAddress` | `string` |  | 旅行社地址 |
|   `agencyName` | `string` |  | 旅行社名称 |
|   `businessLicenseNumber` | `string` |  | 营业执照号 |
|   `businessScope` | `string` |  | 经营范围 |
|   `code` | `string` |  | 旅行社编码 |
|   `licenseNumber` | `string` |  | 旅行社许可证号 |
|   `regionId` | `string` |  | 地区ID |
|   `transactorName` | `string` |  | 经办人姓名 |
|   `transactorPhone` | `string` |  | 经办人电话 |
|   `zjParentId` | `int` |  | 属地管理机构ID |
| `message` | `string` |  | 响应消息 |

---

### `GET` /admin/contract/by-order/{orderId}

**按订单查询合同**

查询指定订单下的所有合同记录（含已作废），按创建时间倒序排列。用于订单详情页展示合同历史。

**权限**：需管理员登录。

**关联字典**：
- contract_status：合同状态（列表显示）

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `orderId` | `integer` |  | 订单ID |

**响应** `统一响应结果«List«合同信息»»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `合同信息[]` |  | 响应数据 |
|   `agencyCode` | `string` |  | 旅行社编号 |
|   `contactName` | `string` |  | 联系人姓名 |
|   `contactPhone` | `string` |  | 联系人电话 |
|   `contractId` | `long` |  | 合同ID |
|   `contractNumber` | `string` |  | 合同编号 |
|   `contractType` | `string` |  | 合同类型: TOUR-旅游合同, INSURANCE-保险单 |
|   `createTime` | `string` |  | 创建时间 |
|   `departureDate` | `string` |  | 出发日期 |
|   `destination` | `string` |  | 目的地 |
|   `fileUrl` | `string` |  | 合同文件URL |
|   `mode` | `string` |  | 签约模式: STANDARD/SYNC |
|   `orderId` | `long` |  | 订单ID |
|   `platform` | `string` |  | 签约平台 |
|   `qrCodeUrl` | `string` |  | 二维码URL |
|   `returnDate` | `string` |  | 返回日期 |
|   `signUrl` | `string` |  | 签署URL |
|   `status` | `string` |  | 合同状态 |
|   `statusLabel` | `string` |  | 合同状态标签 |
|   `templateCode` | `string` |  | 模板编码 |
|   `templateName` | `string` |  | 模板名称 |
|   `totalAmount` | `number` |  | 合同总金额 |
|   `touristCount` | `int` |  | 出行人数 |
|   `travelAgencyName` | `string` |  | 旅行社名称 |
| `message` | `string` |  | 响应消息 |

---

### `POST` /admin/contract/create

**创建合同(标准模式)**

标准电子签约流程：创建合同 → 平台生成合同PDF → 发送签署短信给出行人 → 出行人在线签署 → 回调更新状态。状态流转：CREATED → SIGNING → SIGNED

**请求体** `创建合同请求`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `adultCost` | `number` | 是 | 成人费用 |
| `agencyCode` | `string` |  | 旅行社编号（可选，默认使用配置值） |
| `childCost` | `number` |  | 儿童费用 |
| `contactName` | `string` | 是 | 联系人姓名 |
| `contactPhone` | `string` | 是 | 联系人电话 |
| `contractType` | `string` |  | 合同类型: TOUR-旅游合同(默认), INSURANCE-保险单 |
| `days` | `int` |  | 行程天数 |
| `departureCity` | `string` |  | 出发城市 |
| `departureDate` | `string` | 是 | 出发日期 |
| `destination` | `string` | 是 | 目的地 |
| `disputeResolution` | `int` |  | 争议解决方式: 1-仲裁 2-诉讼 |
| `groupId` | `string` |  | 团号 |
| `leastCustomerNumber` | `int` |  | 最低成团人数 |
| `nights` | `int` |  | 住宿晚数 |
| `orderId` | `long` |  | 订单ID |
| `paymentMethod` | `int` |  | 付款方式: 1-现金 2-转账 3-在线 |
| `returnDate` | `string` | 是 | 返回日期 |
| `routeName` | `string` | 是 | 线路名称 |
| `signatoryIdNumber` | `string` | 是 | 签署人证件号码 |
| `signatoryIdType` | `int` |  | 签署人证件类型: 1-身份证 |
| `signatoryMode` | `int` |  | 签署模式: 1-短信 2-现场 3-线下 |
| `signatoryName` | `string` | 是 | 签署人姓名 |
| `signatoryPhone` | `string` | 是 | 签署人电话 |
| `signingPlace` | `string` |  | 签约地点 |
| `supplementaryClause` | `string` |  | 补充约定内容 |
| `templateCode` | `string` | 是 | 模板编码 |
| `totalAmount` | `number` | 是 | 合同总金额 |
| `transactorName` | `string` |  | 经办人姓名 |
| `transactorPhone` | `string` |  | 经办人电话 |
| `travelers` | `合同出行人请求[]` | 是 | 出行人列表 |
|   `age` | `int` |  | 年龄 |
|   `gender` | `string` |  | 性别: male/female |
|   `health` | `string` |  | 健康信息 |
|   `idCardNo` | `string` | 是 | 证件号码 |
|   `idCardType` | `int` |  | 证件类型: 1-身份证 2-护照 |
|   `isChild` | `boolean` |  | 是否儿童 |
|   `isSigner` | `boolean` |  | 是否签署人 |
|   `name` | `string` | 是 | 姓名 |
|   `phone` | `string` |  | 手机号 |
| `vehicleModel` | `string` |  | 车型名称(产品快照) |

**响应** `统一响应结果«合同详情»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `合同详情` |  | 响应数据 |
|   `agencyCode` | `string` |  | 旅行社编号 |
|   `contactName` | `string` |  | 联系人姓名 |
|   `contactPhone` | `string` |  | 联系人电话 |
|   `contractId` | `long` |  | 合同ID |
|   `contractNumber` | `string` |  | 合同编号 |
|   `contractType` | `string` |  | 合同类型: TOUR-旅游合同, INSURANCE-保险单 |
|   `createTime` | `string` |  | 创建时间 |
|   `departureDate` | `string` |  | 出发日期 |
|   `destination` | `string` |  | 目的地 |
|   `fileUrl` | `string` |  | 合同文件URL |
|   `mode` | `string` |  | 签约模式: STANDARD/SYNC |
|   `orderId` | `long` |  | 订单ID |
|   `platform` | `string` |  | 签约平台 |
|   `qrCodeUrl` | `string` |  | 二维码URL |
|   `returnDate` | `string` |  | 返回日期 |
|   `signUrl` | `string` |  | 签署URL |
|   `status` | `string` |  | 合同状态 |
|   `statusLabel` | `string` |  | 合同状态标签 |
|   `statusLogs` | `合同状态变更日志[]` |  | 状态变更日志 |
|     `createTime` | `string` |  | 创建时间 |
|     `logId` | `long` |  | 日志ID |
|     `newStatus` | `string` |  | 新状态 |
|     `oldStatus` | `string` |  | 旧状态 |
|     `source` | `string` |  | 变更来源 |
|   `supplementaryClause` | `string` |  | 补充约定内容 |
|   `templateCode` | `string` |  | 模板编码 |
|   `templateName` | `string` |  | 模板名称 |
|   `totalAmount` | `number` |  | 合同总金额 |
|   `touristCount` | `int` |  | 出行人数 |
|   `travelAgencyName` | `string` |  | 旅行社名称 |
|   `travelers` | `合同出行人信息[]` |  | 出行人列表 |
|     `idCardNo` | `string` |  | 证件号码 |
|     `idCardType` | `string` |  | 证件类型 |
|     `isSigner` | `boolean` |  | 是否签署人 |
|     `name` | `string` |  | 姓名 |
|     `phone` | `string` |  | 手机号 |
|     `travelerId` | `long` |  | 出行人ID |
| `message` | `string` |  | 响应消息 |

---

### `GET` /admin/contract/list

**合同列表**

分页查询合同记录，支持按订单号、合同状态、旅行社筛选

**关联字典**：
- contract_status：合同状态（列表筛选+显示）

**查询参数**

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `orderId` | `integer(int64)` |  | 订单ID | 1001 |
| `page` | `integer(int32)` |  | 页码 | 1 |
| `pageSize` | `integer(int32)` |  | 每页条数 | 20 |
| `platform` | `string` |  | 签约平台 | TOURAGE |
| `status` | `string` |  | 合同状态 | SIGNED |

**响应** `统一响应结果«分页结果«合同信息»»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `分页结果«合同信息»` |  | 响应数据 |
|   `page` | `int` |  | 当前页码 |
|   `pageSize` | `int` |  | 每页条数 |
|   `records` | `合同信息[]` |  | 数据列表 |
|     `agencyCode` | `string` |  | 旅行社编号 |
|     `contactName` | `string` |  | 联系人姓名 |
|     `contactPhone` | `string` |  | 联系人电话 |
|     `contractId` | `long` |  | 合同ID |
|     `contractNumber` | `string` |  | 合同编号 |
|     `contractType` | `string` |  | 合同类型: TOUR-旅游合同, INSURANCE-保险单 |
|     `createTime` | `string` |  | 创建时间 |
|     `departureDate` | `string` |  | 出发日期 |
|     `destination` | `string` |  | 目的地 |
|     `fileUrl` | `string` |  | 合同文件URL |
|     `mode` | `string` |  | 签约模式: STANDARD/SYNC |
|     `orderId` | `long` |  | 订单ID |
|     `platform` | `string` |  | 签约平台 |
|     `qrCodeUrl` | `string` |  | 二维码URL |
|     `returnDate` | `string` |  | 返回日期 |
|     `signUrl` | `string` |  | 签署URL |
|     `status` | `string` |  | 合同状态 |
|     `statusLabel` | `string` |  | 合同状态标签 |
|     `templateCode` | `string` |  | 模板编码 |
|     `templateName` | `string` |  | 模板名称 |
|     `totalAmount` | `number` |  | 合同总金额 |
|     `touristCount` | `int` |  | 出行人数 |
|     `travelAgencyName` | `string` |  | 旅行社名称 |
|   `total` | `int` |  | 总记录数 |
| `message` | `string` |  | 响应消息 |

---

### `POST` /admin/contract/report

**报备合同(同步模式)**

线下签约模式：创建合同记录 → 管理员上传已签署的PDF → 同步到12301报备平台。状态流转：CREATED → UPLOADED → REPORTED

**请求体** `报备合同请求（同步模式）`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `adultCost` | `number` | 是 | 成人费用 |
| `agencyCode` | `string` |  | 旅行社编号 |
| `childCost` | `number` |  | 儿童费用 |
| `contactName` | `string` | 是 | 联系人姓名 |
| `contactPhone` | `string` | 是 | 联系人电话 |
| `contractType` | `string` |  | 合同类型: TOUR-旅游合同(默认), INSURANCE-保险单 |
| `days` | `int` |  | 行程天数 |
| `departureCity` | `string` |  | 出发城市 |
| `departureDate` | `string` | 是 | 出发日期 |
| `destination` | `string` | 是 | 目的地 |
| `disputeResolution` | `int` |  | 争议解决方式: 1-仲裁 2-诉讼 |
| `groupId` | `string` |  | 团号 |
| `leastCustomerNumber` | `int` |  | 最低成团人数 |
| `nights` | `int` |  | 住宿晚数 |
| `orderId` | `long` |  | 订单ID |
| `paymentMethod` | `int` |  | 付款方式: 1-现金 2-转账 3-在线 |
| `returnDate` | `string` | 是 | 返回日期 |
| `routeName` | `string` | 是 | 线路名称 |
| `signatoryIdNumber` | `string` | 是 | 签署人证件号码 |
| `signatoryIdType` | `int` |  | 签署人证件类型: 1-身份证 |
| `signatoryMode` | `int` |  | 签署模式（同步模式默认2-现场） |
| `signatoryName` | `string` | 是 | 签署人姓名 |
| `signatoryPhone` | `string` | 是 | 签署人电话 |
| `signingPlace` | `string` |  | 签约地点 |
| `supplementaryClause` | `string` |  | 补充约定内容 |
| `templateCode` | `string` | 是 | 模板编码 |
| `totalAmount` | `number` | 是 | 合同总金额 |
| `transactorName` | `string` |  | 经办人姓名 |
| `transactorPhone` | `string` |  | 经办人电话 |
| `travelers` | `合同出行人请求[]` | 是 | 出行人列表 |
|   `age` | `int` |  | 年龄 |
|   `gender` | `string` |  | 性别: male/female |
|   `health` | `string` |  | 健康信息 |
|   `idCardNo` | `string` | 是 | 证件号码 |
|   `idCardType` | `int` |  | 证件类型: 1-身份证 2-护照 |
|   `isChild` | `boolean` |  | 是否儿童 |
|   `isSigner` | `boolean` |  | 是否签署人 |
|   `name` | `string` | 是 | 姓名 |
|   `phone` | `string` |  | 手机号 |

**响应** `统一响应结果«合同详情»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `合同详情` |  | 响应数据 |
|   `agencyCode` | `string` |  | 旅行社编号 |
|   `contactName` | `string` |  | 联系人姓名 |
|   `contactPhone` | `string` |  | 联系人电话 |
|   `contractId` | `long` |  | 合同ID |
|   `contractNumber` | `string` |  | 合同编号 |
|   `contractType` | `string` |  | 合同类型: TOUR-旅游合同, INSURANCE-保险单 |
|   `createTime` | `string` |  | 创建时间 |
|   `departureDate` | `string` |  | 出发日期 |
|   `destination` | `string` |  | 目的地 |
|   `fileUrl` | `string` |  | 合同文件URL |
|   `mode` | `string` |  | 签约模式: STANDARD/SYNC |
|   `orderId` | `long` |  | 订单ID |
|   `platform` | `string` |  | 签约平台 |
|   `qrCodeUrl` | `string` |  | 二维码URL |
|   `returnDate` | `string` |  | 返回日期 |
|   `signUrl` | `string` |  | 签署URL |
|   `status` | `string` |  | 合同状态 |
|   `statusLabel` | `string` |  | 合同状态标签 |
|   `statusLogs` | `合同状态变更日志[]` |  | 状态变更日志 |
|     `createTime` | `string` |  | 创建时间 |
|     `logId` | `long` |  | 日志ID |
|     `newStatus` | `string` |  | 新状态 |
|     `oldStatus` | `string` |  | 旧状态 |
|     `source` | `string` |  | 变更来源 |
|   `supplementaryClause` | `string` |  | 补充约定内容 |
|   `templateCode` | `string` |  | 模板编码 |
|   `templateName` | `string` |  | 模板名称 |
|   `totalAmount` | `number` |  | 合同总金额 |
|   `touristCount` | `int` |  | 出行人数 |
|   `travelAgencyName` | `string` |  | 旅行社名称 |
|   `travelers` | `合同出行人信息[]` |  | 出行人列表 |
|     `idCardNo` | `string` |  | 证件号码 |
|     `idCardType` | `string` |  | 证件类型 |
|     `isSigner` | `boolean` |  | 是否签署人 |
|     `name` | `string` |  | 姓名 |
|     `phone` | `string` |  | 手机号 |
|     `travelerId` | `long` |  | 出行人ID |
| `message` | `string` |  | 响应消息 |

---

### `GET` /admin/contract/templates

**合同模板列表**

返回合同平台可用的合同模板列表，创建合同时选择模板

**响应** `统一响应结果«List«合同模板信息»»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `合同模板信息[]` |  | 响应数据 |
|   `createTime` | `string` |  | 创建时间 |
|   `description` | `string` |  | 模板描述 |
|   `mode` | `string` |  | 签约模式: STANDARD/SYNC |
|   `platform` | `string` |  | 签约平台 |
|   `status` | `string` |  | 模板状态 |
|   `templateCode` | `string` |  | 模板编码 |
|   `templateId` | `long` |  | 模板ID |
|   `templateName` | `string` |  | 模板名称 |
| `message` | `string` |  | 响应消息 |

---

### `GET` /admin/contract/{id}

**合同详情**

**关联字典**：
- contract_status：合同状态（显示）

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `integer` |  | 合同ID |

**响应** `统一响应结果«合同详情»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `合同详情` |  | 响应数据 |
|   `agencyCode` | `string` |  | 旅行社编号 |
|   `contactName` | `string` |  | 联系人姓名 |
|   `contactPhone` | `string` |  | 联系人电话 |
|   `contractId` | `long` |  | 合同ID |
|   `contractNumber` | `string` |  | 合同编号 |
|   `contractType` | `string` |  | 合同类型: TOUR-旅游合同, INSURANCE-保险单 |
|   `createTime` | `string` |  | 创建时间 |
|   `departureDate` | `string` |  | 出发日期 |
|   `destination` | `string` |  | 目的地 |
|   `fileUrl` | `string` |  | 合同文件URL |
|   `mode` | `string` |  | 签约模式: STANDARD/SYNC |
|   `orderId` | `long` |  | 订单ID |
|   `platform` | `string` |  | 签约平台 |
|   `qrCodeUrl` | `string` |  | 二维码URL |
|   `returnDate` | `string` |  | 返回日期 |
|   `signUrl` | `string` |  | 签署URL |
|   `status` | `string` |  | 合同状态 |
|   `statusLabel` | `string` |  | 合同状态标签 |
|   `statusLogs` | `合同状态变更日志[]` |  | 状态变更日志 |
|     `createTime` | `string` |  | 创建时间 |
|     `logId` | `long` |  | 日志ID |
|     `newStatus` | `string` |  | 新状态 |
|     `oldStatus` | `string` |  | 旧状态 |
|     `source` | `string` |  | 变更来源 |
|   `supplementaryClause` | `string` |  | 补充约定内容 |
|   `templateCode` | `string` |  | 模板编码 |
|   `templateName` | `string` |  | 模板名称 |
|   `totalAmount` | `number` |  | 合同总金额 |
|   `touristCount` | `int` |  | 出行人数 |
|   `travelAgencyName` | `string` |  | 旅行社名称 |
|   `travelers` | `合同出行人信息[]` |  | 出行人列表 |
|     `idCardNo` | `string` |  | 证件号码 |
|     `idCardType` | `string` |  | 证件类型 |
|     `isSigner` | `boolean` |  | 是否签署人 |
|     `name` | `string` |  | 姓名 |
|     `phone` | `string` |  | 手机号 |
|     `travelerId` | `long` |  | 出行人ID |
| `message` | `string` |  | 响应消息 |

---

### `POST` /admin/contract/{id}/invalidate

**作废合同**

将合同标记为作废状态（不可恢复）。作废后该合同不再有效，可重新为订单创建新合同

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `integer` |  | 合同ID |

**响应** `统一响应结果«合同信息»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `合同信息` |  | 响应数据 |
|   `agencyCode` | `string` |  | 旅行社编号 |
|   `contactName` | `string` |  | 联系人姓名 |
|   `contactPhone` | `string` |  | 联系人电话 |
|   `contractId` | `long` |  | 合同ID |
|   `contractNumber` | `string` |  | 合同编号 |
|   `contractType` | `string` |  | 合同类型: TOUR-旅游合同, INSURANCE-保险单 |
|   `createTime` | `string` |  | 创建时间 |
|   `departureDate` | `string` |  | 出发日期 |
|   `destination` | `string` |  | 目的地 |
|   `fileUrl` | `string` |  | 合同文件URL |
|   `mode` | `string` |  | 签约模式: STANDARD/SYNC |
|   `orderId` | `long` |  | 订单ID |
|   `platform` | `string` |  | 签约平台 |
|   `qrCodeUrl` | `string` |  | 二维码URL |
|   `returnDate` | `string` |  | 返回日期 |
|   `signUrl` | `string` |  | 签署URL |
|   `status` | `string` |  | 合同状态 |
|   `statusLabel` | `string` |  | 合同状态标签 |
|   `templateCode` | `string` |  | 模板编码 |
|   `templateName` | `string` |  | 模板名称 |
|   `totalAmount` | `number` |  | 合同总金额 |
|   `touristCount` | `int` |  | 出行人数 |
|   `travelAgencyName` | `string` |  | 旅行社名称 |
| `message` | `string` |  | 响应消息 |

---

### `POST` /admin/contract/{id}/resend-sms

**重发签署短信**

重新发送签署短信给出行人，用于签署短信过期或未收到的场景。仅SIGNING状态的合同可操作

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `integer` |  | 合同ID |

**响应** `统一响应结果«boolean»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `boolean` |  | 响应数据 |
| `message` | `string` |  | 响应消息 |

---

### `GET` /admin/contract/{id}/status

**刷新合同状态(从平台同步)**

主动查询合同平台的最新签署状态并同步到本地，适用于回调未到达的场景

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `integer` |  | 合同ID |

**响应** `统一响应结果«合同信息»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `合同信息` |  | 响应数据 |
|   `agencyCode` | `string` |  | 旅行社编号 |
|   `contactName` | `string` |  | 联系人姓名 |
|   `contactPhone` | `string` |  | 联系人电话 |
|   `contractId` | `long` |  | 合同ID |
|   `contractNumber` | `string` |  | 合同编号 |
|   `contractType` | `string` |  | 合同类型: TOUR-旅游合同, INSURANCE-保险单 |
|   `createTime` | `string` |  | 创建时间 |
|   `departureDate` | `string` |  | 出发日期 |
|   `destination` | `string` |  | 目的地 |
|   `fileUrl` | `string` |  | 合同文件URL |
|   `mode` | `string` |  | 签约模式: STANDARD/SYNC |
|   `orderId` | `long` |  | 订单ID |
|   `platform` | `string` |  | 签约平台 |
|   `qrCodeUrl` | `string` |  | 二维码URL |
|   `returnDate` | `string` |  | 返回日期 |
|   `signUrl` | `string` |  | 签署URL |
|   `status` | `string` |  | 合同状态 |
|   `statusLabel` | `string` |  | 合同状态标签 |
|   `templateCode` | `string` |  | 模板编码 |
|   `templateName` | `string` |  | 模板名称 |
|   `totalAmount` | `number` |  | 合同总金额 |
|   `touristCount` | `int` |  | 出行人数 |
|   `travelAgencyName` | `string` |  | 旅行社名称 |
| `message` | `string` |  | 响应消息 |

---

### `POST` /admin/contract/{id}/upload-pdf

**上传已签署PDF(同步模式)**

同步模式专用：上传线下签署完成的合同PDF文件，上传后合同状态变为UPLOADED，可进一步报备

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `integer` |  | 合同ID |

**响应** `统一响应结果«合同信息»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `合同信息` |  | 响应数据 |
|   `agencyCode` | `string` |  | 旅行社编号 |
|   `contactName` | `string` |  | 联系人姓名 |
|   `contactPhone` | `string` |  | 联系人电话 |
|   `contractId` | `long` |  | 合同ID |
|   `contractNumber` | `string` |  | 合同编号 |
|   `contractType` | `string` |  | 合同类型: TOUR-旅游合同, INSURANCE-保险单 |
|   `createTime` | `string` |  | 创建时间 |
|   `departureDate` | `string` |  | 出发日期 |
|   `destination` | `string` |  | 目的地 |
|   `fileUrl` | `string` |  | 合同文件URL |
|   `mode` | `string` |  | 签约模式: STANDARD/SYNC |
|   `orderId` | `long` |  | 订单ID |
|   `platform` | `string` |  | 签约平台 |
|   `qrCodeUrl` | `string` |  | 二维码URL |
|   `returnDate` | `string` |  | 返回日期 |
|   `signUrl` | `string` |  | 签署URL |
|   `status` | `string` |  | 合同状态 |
|   `statusLabel` | `string` |  | 合同状态标签 |
|   `templateCode` | `string` |  | 模板编码 |
|   `templateName` | `string` |  | 模板名称 |
|   `totalAmount` | `number` |  | 合同总金额 |
|   `touristCount` | `int` |  | 出行人数 |
|   `travelAgencyName` | `string` |  | 旅行社名称 |
| `message` | `string` |  | 响应消息 |

---

## 补充约定模板管理

### `POST` /admin/contract/clause-template

**创建补充约定模板**

创建合同补充约定的模板，支持变量占位符。创建后默认启用

**请求体** `补充约定模板请求`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `content` | `string` | 是 | 模板内容 |
| `name` | `string` | 是 | 模板名称 |
| `sortOrder` | `int` |  | 排序（升序） |

**响应** `统一响应结果«补充约定模板»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `补充约定模板` |  | 响应数据 |
|   `content` | `string` |  | 模板内容 |
|   `createTime` | `string` |  | 创建时间 |
|   `name` | `string` |  | 模板名称 |
|   `sortOrder` | `int` |  | 排序 |
|   `status` | `string` |  | 状态: ACTIVE/INACTIVE |
|   `templateId` | `long` |  | 模板ID |
| `message` | `string` |  | 响应消息 |

---

### `GET` /admin/contract/clause-template/list

**获取启用的补充约定模板列表（创建合同用）**

返回所有启用状态的补充约定模板，创建合同时选择需要附加的补充约定条款。

**权限**：需管理员登录。

**响应** `统一响应结果«List«补充约定模板»»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `补充约定模板[]` |  | 响应数据 |
|   `content` | `string` |  | 模板内容 |
|   `createTime` | `string` |  | 创建时间 |
|   `name` | `string` |  | 模板名称 |
|   `sortOrder` | `int` |  | 排序 |
|   `status` | `string` |  | 状态: ACTIVE/INACTIVE |
|   `templateId` | `long` |  | 模板ID |
| `message` | `string` |  | 响应消息 |

---

### `GET` /admin/contract/clause-template/list-all

**获取全部补充约定模板（管理页用）**

**关联字典**：
- common_status：通用状态（列表显示，ACTIVE=启用/INACTIVE=停用）

**响应** `统一响应结果«List«补充约定模板»»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `补充约定模板[]` |  | 响应数据 |
|   `content` | `string` |  | 模板内容 |
|   `createTime` | `string` |  | 创建时间 |
|   `name` | `string` |  | 模板名称 |
|   `sortOrder` | `int` |  | 排序 |
|   `status` | `string` |  | 状态: ACTIVE/INACTIVE |
|   `templateId` | `long` |  | 模板ID |
| `message` | `string` |  | 响应消息 |

---

### `PUT` /admin/contract/clause-template/{id}

**更新补充约定模板**

更新模板的标题和内容。已被合同引用的模板更新不影响已创建的合同（合同记录的是快照内容）。

**权限**：需管理员登录。

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `integer` |  | 模板ID |

**请求体** `补充约定模板请求`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `content` | `string` | 是 | 模板内容 |
| `name` | `string` | 是 | 模板名称 |
| `sortOrder` | `int` |  | 排序（升序） |

**响应** `统一响应结果«补充约定模板»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `补充约定模板` |  | 响应数据 |
|   `content` | `string` |  | 模板内容 |
|   `createTime` | `string` |  | 创建时间 |
|   `name` | `string` |  | 模板名称 |
|   `sortOrder` | `int` |  | 排序 |
|   `status` | `string` |  | 状态: ACTIVE/INACTIVE |
|   `templateId` | `long` |  | 模板ID |
| `message` | `string` |  | 响应消息 |

---

### `DELETE` /admin/contract/clause-template/{id}

**删除补充约定模板**

软删除模板。已被合同引用的模板仍可删除，不影响已创建的合同

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `integer` |  | 模板ID |

**响应** `统一响应结果«Void»`

---

### `PUT` /admin/contract/clause-template/{id}/toggle-status

**切换模板启用/停用状态**

**关联字典**：
- common_status：通用状态（状态切换，ACTIVE=启用/INACTIVE=停用）

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `integer` |  | 模板ID |

**响应** `统一响应结果«补充约定模板»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `补充约定模板` |  | 响应数据 |
|   `content` | `string` |  | 模板内容 |
|   `createTime` | `string` |  | 创建时间 |
|   `name` | `string` |  | 模板名称 |
|   `sortOrder` | `int` |  | 排序 |
|   `status` | `string` |  | 状态: ACTIVE/INACTIVE |
|   `templateId` | `long` |  | 模板ID |
| `message` | `string` |  | 响应消息 |

---