docs(changelog-v2): 合同保险Tab创建合同与投保接口对接说明(管理后台)

订单详情合同保险Tab两组操作按钮(选择合同方案+创建合同 / 选择保险方案+投保)
的后端接口对接说明,4个接口自包含契约:
- GET /v3/admin/contract/scheme/list 合同方案下拉
- POST /v3/admin/contract/create-by-scheme 创建合同(按方案)
- GET /v3/admin/insurance/scheme/list 保险方案下拉
- POST /v3/admin/insurance/purchase-by-scheme 投保(按方案)
后端接口早已存在,本文为前端首次对接说明。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

changelogs-v2/2026-06/26_合同保险Tab创建合同与投保接口-新增接口-管理后台.md

@@ -0,0 +1,246 @@
+# 订单详情「合同·保险」Tab —— 创建合同 / 投保 接口对接（管理后台）
+
+- 端类型：管理后台
+- 变更类型：新增接口（前端首次对接；**后端接口早已存在**，本文为对接说明）
+- 关联：订单详情「合同·保险」Tab（懒加载 GET 仅回显，写操作走本文 4 接口）
+- 日期：2026-06-26
+
+---
+
+## ① 接口背景
+
+订单详情「合同·保险」Tab 的懒加载接口 `GET /v3/admin/order/{id}/contract-insurance` 是**只读回显**（返回合同/保险当前状态 + 时间线），**不含**写操作。Tab 页面上的两组操作按钮——「选择合同方案 + 创建合同」「选择保险方案 + 投保」——各由独立写接口支撑。本文给出这 4 个接口的完整契约供前端对接。
+
+> 两个「按方案」接口都是**简化版**：前端只传 `orderId + schemeId`，后端自动从订单取出行人、行程日期、联系人，结合方案配置去创建合同 / 逐段投保。
+
+---
+
+## ② 变更清单
+
+| 序 | 方法 | 路径 | 用途 |
+|---|---|---|---|
+| 1 | GET | `/v3/admin/contract/scheme/list` | 合同方案下拉（启用方案） |
+| 2 | POST | `/v3/admin/contract/create-by-scheme` | 创建合同（按方案） |
+| 3 | GET | `/v3/admin/insurance/scheme/list` | 保险方案下拉（启用方案，可按行程天数筛） |
+| 4 | POST | `/v3/admin/insurance/purchase-by-scheme` | 投保（按方案，逐段投保） |
+
+统一响应 `Result<T>`：`{ code, message, data, success }`，`code=200` 成功。
+
+---
+
+## ③ 接口详情
+
+### 接口 1：合同方案下拉
+```
+GET /v3/admin/contract/scheme/list
+```
+无入参。返回当前**启用（ACTIVE）**的合同方案列表，供「选择合同方案」下拉。
+
+### 接口 2：创建合同（按方案）
+```
+POST /v3/admin/contract/create-by-scheme
+Content-Type: application/json
+```
+点「创建合同」时调。后端按方案 + 订单数据创建合同；若方案为电子签约模式（STANDARD），会触发推送签署链接（短信/微信至客户预留手机号）。
+
+### 接口 3：保险方案下拉
+```
+GET /v3/admin/insurance/scheme/list?totalDays={行程天数}
+```
+返回**启用（ACTIVE）**保险方案，供「选择保险方案」下拉。`totalDays` 可选：传则按行程天数筛匹配方案（全程方案 totalDays=-1 任意天数都命中），不传返回全部启用方案。
+
+### 接口 4：投保（按方案）
+```
+POST /v3/admin/insurance/purchase-by-scheme
+Content-Type: application/json
+```
+点「投保」时调。后端按方案逐段投保（一个方案多段 → 每段建一张保单），自动按订单出行人投保。
+
+---
+
+## ④ 入参
+
+### 接口 1（合同方案下拉）
+无。
+
+### 接口 2（创建合同）—— Body
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| orderId | Long(字符串) | 是 | 订单 ID |
+| schemeId | Long(字符串) | 是 | 合同方案 ID（取自接口 1 的 schemeId） |
+
+### 接口 3（保险方案下拉）—— Query
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| totalDays | Integer | 否 | 行程天数，按天数筛方案；不传返回全部启用 |
+
+### 接口 4（投保）—— Body
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| orderId | Long(字符串) | 是 | 订单 ID |
+| schemeId | Long(字符串) | 是 | 保险方案 ID（取自接口 3 的 schemeId） |
+
+---
+
+## ⑤ 出参
+
+### 接口 1：`Result<List<ContractSchemeVO>>`
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| schemeId | String | 方案 ID（创建合同时回传） |
+| name | String | 方案名称（下拉展示） |
+| description | String | 方案描述 |
+| contractPlatform | String | 合同平台：12301 / LOCAL / TENCENT_ESIGN |
+| vendorCode | String | 平台厂商编码：TENCENT_HULAI=呼籁自有腾讯账号；12301 平台为 NULL |
+| channel | String | 订单来源渠道：MP / ADMIN / CHANNEL；NULL=兜底方案 |
+| templateCode | String | 合同模板编码（contractTemplateCode 别名） |
+| contractTemplateName | String | 合同模板名称 |
+| contractMode | String | 签约模式：STANDARD(电子签约) / SYNC(线下报备) |
+| signatoryMode | Integer | 签署模式：1=短信签署 / 2=现场签署 / 3=线下签署 |
+| agencyCode / agencyName | String | 旅行社编码 / 名称 |
+| supplementaryClause | String | 补充条款 |
+| transactorName / transactorPhone | String | 经办人姓名 / 电话 |
+| sortOrder | Integer | 排序 |
+| status | String | 状态：ACTIVE / INACTIVE |
+| createTime | DateTime | 创建时间 |
+
+### 接口 2：`Result<ContractDetailVO>`（创建成功返回合同详情）
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| contractId | Long(字符串) | 合同 ID |
+| orderId / orderNo | Long(字符串) / String | 订单 ID / 订单编号 |
+| schemeId | Long(字符串) | 合同方案 ID |
+| templateCode / templateName | String | 模板编码 / 名称 |
+| contractNumber | String | 合同编号 |
+| platform | String | 签约平台 |
+| contractType / contractTypeLabel | String | 合同类型 TOUR-旅游合同 / INSURANCE-保险单 + 标签 |
+| mode / modeLabel | String | 签约模式 ONLINE-线上签署 / OFFLINE-线下签署 + 标签 |
+| status / statusLabel | String | 合同状态 + 标签（见⑥） |
+| signUrl / qrCodeUrl / fileUrl | String | 签署 URL / 二维码 URL / 合同文件 URL |
+| agencyCode / travelAgencyName | String | 旅行社编号 / 名称 |
+| destination | String | 目的地 |
+| departureDate / returnDate | Date | 出发 / 返回日期 |
+| totalAmount | BigDecimal(字符串) | 合同总金额 |
+| touristCount | Integer | 出行人数 |
+| contactName / contactPhone | String | 联系人姓名 / 电话（明文，脱敏前端处理） |
+| supplementaryClause | String | 补充约定内容 |
+| travelers | List | 出行人列表（travelerId/name/idCardType/idCardTypeLabel/idCardNo/phone/isSigner） |
+| statusLogs | List | 状态变更日志 |
+| createTime | DateTime | 创建时间 |
+
+### 接口 3：`Result<List<InsuranceSchemeVO>>`
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| schemeId | Long(字符串) | 方案 ID（投保时回传） |
+| schemeName | String | 方案名称（下拉展示，name 为兼容别名同值） |
+| description | String | 方案描述 |
+| isOverseas | Boolean | 是否境外 |
+| totalDays | Integer | 适用行程天数（-1=全程方案，任意天数命中） |
+| sortOrder | Integer | 排序 |
+| status | String | 状态：ACTIVE-启用 / INACTIVE-停用 |
+| insuranceProductId / productName | Long(字符串) / String | 保险产品 ID / 名称 |
+| planId / planName | Long(字符串) / String | 保险计划 ID / 名称 |
+| enabled | Boolean | 是否启用 |
+| segmentCount | Integer | 段数量 |
+| segments | List | 适用行程段列表（见下） |
+| createTime / updateTime | DateTime | 创建 / 更新时间 |
+
+`segments[]`（SegmentItem）：segmentId / segmentName / dayOffsetStart / dayOffsetEnd(-1=最后一天) / minDays / maxDays / productId / productName / planId / planName / sortOrder。
+
+### 接口 4：`Result<Void>`
+投保成功返回 `data=null`、`code=200`。投保结果（保单）通过懒加载 GET 接口的 `insurance.policies[]` 回显。
+
+---
+
+## ⑥ 枚举 / 数据字典
+
+- 合同方案 contractMode：STANDARD 电子签约 / SYNC 线下报备
+- 合同方案 contractPlatform：12301 / LOCAL / TENCENT_ESIGN（对应字典 contract_platform）
+- 合同方案 signatoryMode：1 短信签署 / 2 现场签署 / 3 线下签署
+- 合同 contractType：TOUR 旅游合同 / INSURANCE 保险单
+- 合同 mode：ONLINE 线上签署 / OFFLINE 线下签署
+- 合同 status：GENERATING 生成中 / GENERATED 已生成 / SIGNED 已签 / UPLOADED 已上传回执 / VOIDED 已作废 / RESIGNING 重签中
+- 保险方案 status：ACTIVE 启用 / INACTIVE 停用
+- 方案/产品/计划 status 通用：ACTIVE / INACTIVE
+
+---
+
+## ⑦ 错误码
+
+- 创建合同 / 投保失败抛 `BusinessException`，统一响应 `code≠200 + message`，前端按 message 提示。
+- 下拉查询接口正常返 200。
+
+---
+
+## ⑧ 示例
+
+### 接口 1 响应（合同方案下拉）
+```json
+{ "code": 200, "message": "操作成功", "success": true,
+  "data": [
+    { "schemeId": "2054961027789152258", "name": "标准国内电子签约方案",
+      "contractPlatform": "TENCENT_ESIGN", "contractMode": "STANDARD",
+      "signatoryMode": 1, "status": "ACTIVE" }
+  ] }
+```
+
+### 接口 2 请求（创建合同）
+```json
+{ "orderId": "2070039025715982337", "schemeId": "2054961027789152258" }
+```
+响应 `data` = ContractDetailVO（contractId/status=GENERATED/signUrl 等）。
+
+### 接口 3 响应（保险方案下拉，传 totalDays=5）
+```json
+{ "code": 200, "success": true,
+  "data": [
+    { "schemeId": "2067500963379245057", "schemeName": "境外旅行险·标准版",
+      "totalDays": -1, "status": "ACTIVE", "segmentCount": 1,
+      "segments": [ { "segmentId": "...", "segmentName": "全程", "dayOffsetStart": 0, "dayOffsetEnd": -1 } ] }
+  ] }
+```
+
+### 接口 4 请求（投保）
+```json
+{ "orderId": "2070039025715982337", "schemeId": "2067500963379245057" }
+```
+响应 `{ "code": 200, "data": null, "success": true }`。
+
+---
+
+## ⑨ 业务边界
+
+- 两个下拉只返回 **ACTIVE** 方案；INACTIVE 不出现。
+- 创建合同 / 投保只需 `orderId + schemeId`，其余数据后端从订单自动取。
+- 投保为**逐段投保**：一个方案多段 → 生成多张保单，懒加载 GET 的 `insurance.policies[]` 为数组。
+- 投保是异步出单：接口 4 返回成功表示**受理成功**，最终出单状态以懒加载 GET 的 policies status（INSURING→INSURED）为准。
+- 创建合同若方案为 STANDARD（电子签约），后端会推送签署链接到客户预留手机号。
+
+---
+
+## ⑩ 修改前后对比
+
+不适用（前端首次对接，无旧版本）。
+
+---
+
+## ⑪ 影响评估 / 回滚
+
+- 后端接口早已存在且稳定，前端对接不涉及后端改动，无回滚项。
+- 前端对接顺序建议：进 Tab → 调懒加载 GET 回显 → 无合同/保险时展示下拉 → 选方案 → 创建合同 / 投保 → 重新调懒加载 GET 刷新状态与时间线。
+
+---
+
+## ⑫ 注意事项
+
+- Long ID（schemeId / orderId / contractId 等）与金额均**字符串化**返回（防 JS 精度丢失），请求时同样以字符串传 ID。
+- 创建合同 / 投保为写操作，前端需做按钮防重复点击 + loading。
+- 操作成功后刷新走懒加载 GET `/v3/admin/order/{id}/contract-insurance`（合同 5 步时间线 + 保险 policies 数组，见 2026-06-25 那份终态 changelog）。
+
+---
+
+## ⑬ 关联 / 联系人
+
+- 关联文档：`changelogs-v2/2026-06/25_4390_4403_订单详情合同保险Tab出参终态-修改接口-管理后台.md`（懒加载回显出参终态）
+- 后端负责人：腰苏图
+- 接口已部署测试服，Knife4j 可见（`/v3/admin/contract/**`、`/v3/admin/insurance/**`）。