# 投保接口支持自动填充（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）
- 订单必须有出行人且出行人信息完整（姓名+证件号）
- 订单必须有出发日期和行程天数