投保接口支持orderId自动填充出行人和日期

changelogs/2026-03/2026-03-21_insurance_purchase_auto_fill.md

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