98 行
3.0 KiB
Markdown
98 行
3.0 KiB
Markdown
# 投保接口支持自动填充（orderId）
|
||
|
||
**日期**: 2026-03-21
|
||
**服务**: hl-insurance-service
|
||
**类型**: 功能增强
|
||
|
||
---
|
||
|
||
## 功能说明
|
||
|
||
`POST /admin/insurance/purchase` 投保接口现在支持传 `orderId` 自动从订单获取出行人和行程日期，无需手动填写 `startDate`、`endDate`、`insuredPersons`。
|
||
|
||
**之前**：必须手动传 planId + startDate + endDate + insuredPersons（完整被保人列表）
|
||
**现在**：只需传 planId + orderId，其余自动从订单获取
|
||
|
||
---
|
||
|
||
## 接口清单
|
||
|
||
| 方法 | 路径 | 说明 | 变更 |
|
||
|------|------|------|------|
|
||
| POST | /admin/insurance/purchase | 投保下单 | `startDate`/`endDate`/`insuredPersons` 变为可选 |
|
||
|
||
---
|
||
|
||
## 详细定义
|
||
|
||
### POST /admin/insurance/purchase
|
||
|
||
#### 请求参数
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| orderId | Long | 否 | 关联旅行订单ID。**传了则自动从订单获取出行人和日期** |
|
||
| planId | Long | **是** | 保险计划ID |
|
||
| startDate | LocalDate | 否 | 保障开始日期。传orderId时自动取订单出发日期 |
|
||
| endDate | LocalDate | 否 | 保障结束日期。传orderId时自动按出发日期+行程天数计算 |
|
||
| insuredPersons | List | 否 | 被保人列表。传orderId时自动从订单出行人获取 |
|
||
| entityCode | String | 否 | 投保公司主体编码，不填用默认主体 |
|
||
| remark | String | 否 | 备注 |
|
||
|
||
#### 两种调用方式
|
||
|
||
**方式一：通过订单自动填充（推荐）**
|
||
```json
|
||
{
|
||
"orderId": "2034961514288623617",
|
||
"planId": "2026279738275856390"
|
||
}
|
||
```
|
||
系统自动从订单获取：
|
||
- 出行人 → 被保人
|
||
- 出发日期 → 保障开始日期
|
||
- 出发日期 + 行程天数 - 1 → 保障结束日期
|
||
|
||
**方式二：手动传全部参数（仍然支持）**
|
||
```json
|
||
{
|
||
"planId": "2026279738275856390",
|
||
"startDate": "2026-05-01",
|
||
"endDate": "2026-05-05",
|
||
"insuredPersons": [
|
||
{
|
||
"name": "张三",
|
||
"idCardType": "ID_CARD",
|
||
"idCardNo": "110101199001011234",
|
||
"birthday": "1990-01-01",
|
||
"gender": "MALE",
|
||
"phone": "13800138000"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
#### 错误提示
|
||
|
||
| 场景 | 错误信息 |
|
||
|------|----------|
|
||
| 订单无出行人 | "无法获取订单出行人信息，请确认订单已添加出行人" |
|
||
| 出行人缺少姓名或证件号 | "订单无有效出行人（缺少姓名或证件号）" |
|
||
| 订单未设置出发日期 | "订单未设置出发日期，无法自动确定保障开始日期" |
|
||
| 订单未设置行程天数 | "订单未设置行程天数，无法自动确定保障结束日期" |
|
||
|
||
---
|
||
|
||
## 前端使用场景
|
||
|
||
### 保险管理页 - 手动投保
|
||
1. 选择订单 → 获得 orderId
|
||
2. 选择保险计划 → 获得 planId
|
||
3. 调用 `POST /admin/insurance/purchase`，只传 `{ orderId, planId }`
|
||
4. 无需再填写出行人信息和日期
|
||
|
||
### 注意事项
|
||
- 订单必须已确认（CONFIRMED/PENDING_BALANCE/PENDING_DEPARTURE/TRAVELLING）
|
||
- 订单必须有出行人且出行人信息完整（姓名+证件号）
|
||
- 订单必须有出发日期和行程天数
|