hl-api-changelog/changelogs-v2/2026-06/11_v3保险投保接口入参契约说明-修改接口-管理后台.md

date, type, module, priority, status, restart_service, 端类型, breaking_change

date	type	module	priority	status	restart_service	端类型	breaking_change
2026-06-11	api-contract-clarify	hl-order-service-v3/insurance	high	code-already-merged	hl-order-service-v3	管理后台	false

v3 保险「投保」接口入参契约说明（管理后台保险全量切 v3 联调补充）

① 接口背景

管理后台保险模块前端已全量指向 v3，投保入参字段名按设计文档（Knife4j / API 文档）硬切。 但 v3 投保接口（/v3/admin/insurance/purchase）此前从未推送过入参契约 changelog（仓库已有的 #3642 只说了出单状态/列表详情出参，未涉及投保入参）。 本文档把 v3 投保两个接口的入参契约完整内联，并明确老字段名是否仍被接收这一前端关心的问题。

⚠️ 本文档不涉及"保险页 404"——404 属网关路由 / 服务注册问题（需后端确认测试服 /v3/admin/insurance/** 是否已路由到 hl-order-service-v3:8086、order-service-v3 是否已启动），不在接口契约范畴。

② 变更清单

#	接口	方法	说明
1	/v3/admin/insurance/purchase	POST	手动投保（指定方案或产品+计划 + 可选被保人）
2	/v3/admin/insurance/purchase-by-scheme	POST	按方案自动投保（仅 orderId + schemeId）

性质：契约澄清，非破坏性。字段名与 v2 一致；路径前缀由 /admin/insurance 变为 /v3/admin/insurance。

③ 接口详情

3.1 手动投保

• 路径：POST /v3/admin/insurance/purchase
• Content-Type：application/json
• 请求体：PurchaseInsuranceRequest
• 返回：Result<List<InsuranceOrderDetailVO>>（创建的保险订单详情列表）

3.2 按方案自动投保

• 路径：POST /v3/admin/insurance/purchase-by-scheme
• 请求体：AutoPurchaseRequest
• 返回：Result<Void>

④ 入参

4.1 PurchaseInsuranceRequest（手动投保）

字段	类型	必填	说明
orderId	Long	✅	业务订单 ID
schemeId	Long	否	保险方案 ID（优先用方案匹配；为空则用 insuranceProductId+planId）
insuranceProductId	Long	方案为空时必填	保险产品 ID
planId	Long	方案为空时必填	保险计划 ID
coverageStartDate	LocalDate	否	保障开始日期，为空时后端按订单 startDate 自动填充
coverageEndDate	LocalDate	否	保障结束日期，为空时后端按订单 endDate 自动填充
insuredPersons	List	否	被保人列表；为空时后端按订单出行人自动填充，传了则以传入为准
remark	String	否	备注

InsuredPersonItem（被保人）

字段	类型	必填	说明
name	String	✅	姓名
idCardType	String	✅	证件类型，枚举见 ⑥；兼容老字段名 idType（@JsonAlias）
idCardNo	String	✅	证件号码（落库自动加密、查询自动解密，前端无感）；兼容老字段名 idNo
birthday	LocalDate	否	出生日期
phone	String	否	手机号

⚠️ v3 被保人入参无 gender（性别）字段：v2 的 InsuredPersonItem 有 gender，v3 没有。前端从 v2 切 v3 若仍传 gender，将被 Jackson 静默忽略（FAIL_ON_UNKNOWN_PROPERTIES=false，不报错）。

4.2 AutoPurchaseRequest（按方案投保）

字段	类型	必填	说明
orderId	Long	✅	旅行订单 ID
schemeId	Long	✅	保险方案 ID

⑤ 出参

/v3/admin/insurance/purchase 返回 List<InsuranceOrderDetailVO>（新建保险订单详情）。 其中 status / statusLabel / policyNo 的异步出单语义（可能为 INSURING/出单中、policyNo 可能为空）见同目录 #3642 保险出单改异步 changelog。

⑥ 枚举 / 数据字典

idCardType 证件类型（以代码注解为准，完整证件字典与 traveler 模块对齐）：

值	含义
ID_CARD	身份证
PASSPORT	护照
HONG_KONG	港澳通行证
TAIWAN	台湾通行证
OTHER	其他

⑦ 错误码

场景	响应
缺 orderId	400 「订单ID不能为空」
被保人缺 idCardType（或老名 idType）	400 「证件类型不能为空」
被保人缺 idCardNo（或老名 idNo）	400 「证件号码不能为空」
方案与产品+计划均为空	业务校验失败（无法定位保险产品）

⑧ 示例

典型（推荐：标准字段名）

POST /v3/admin/insurance/purchase
{
  "orderId": "2026270000000000001",
  "schemeId": "2026279738275856500",
  "insuredPersons": [
    {
      "name": "张三",
      "idCardType": "ID_CARD",
      "idCardNo": "110101199001011234",
      "phone": "13800138000",
      "birthday": "1990-01-01"
    }
  ],
  "remark": "管理后台手动投保"
}

边界（不传被保人 → 后端按订单出行人自动填充）

POST /v3/admin/insurance/purchase
{ "orderId": "2026270000000000001", "schemeId": "2026279738275856500" }

兼容（老字段名 idType/idNo 仍被接收，@JsonAlias 兜底）

{
  "orderId": "2026270000000000001",
  "schemeId": "2026279738275856500",
  "insuredPersons": [
    { "name": "张三", "idType": "ID_CARD", "idNo": "110101199001011234" }
  ]
}

异常（缺证件号 → 400）

请求: { "orderId": "...", "insuredPersons": [ { "name": "张三", "idCardType": "ID_CARD" } ] }
响应: { "code": 400, "message": "证件号码不能为空" }

⑨ 业务边界

• insuredPersons 为空 → 后端按订单出行人自动填充被保人。
• coverageStartDate / coverageEndDate 为空 → 后端按订单 startDate / endDate 填充。
• 同时传 idCardType 和 idType（不推荐）→ Jackson 按后出现的覆盖，建议只传标准名。
• 出单为异步：返回时保险订单可能处于 INSURING、policyNo 暂空，需轮询 / 回调获取最终保单号（详见 #3642）。

⑩ 修改前后对比

维度	v2（/admin/insurance）	v3（/v3/admin/insurance）
路径前缀	/admin/insurance	/v3/admin/insurance
idCardType/idCardNo	✅（兼容 idType/idNo）	✅（兼容 idType/idNo，一致）
被保人 gender	✅ 有	❌ 无
出单	同步	异步（INSURING 状态，见 #3642）

⑪ 影响评估 / 回滚

• 前端切标准字段名 idCardType/idCardNo 安全；继续用老名 idType/idNo 也不会 400（兼容未下线）。
• 唯一需前端动作：停止传 gender（v3 无此入参，传了被忽略；如业务需要被保人性别，由后端从出行人档案带，前端无需关心）。
• 无代码回滚项（本文档为存量契约说明，未改代码）。

⑫ 注意事项

• 「保险页 404」非本文档范畴：属网关路由 / 服务注册问题，请后端在测试服核：① /v3/admin/insurance/** 是否路由到 hl-order-service-v3(8086)；② order-service-v3 是否已启动；③ 小程序侧若经 BFF，MpInsuranceFeignClient 的 name="hl-order-service"（无 v3 后缀）在测试服注册到的是 v2 还是 v3。
• idCardNo 已挂加密 TypeHandler，落库加密、查询解密，日志脱敏，前端无感。

⑬ 关联 / 联系人

• 来源：管理后台保险全量切 v3 联调反馈（前端 sync-log）
• 相关 changelog：#3642 保险出单改异步（出参状态）、changelogs/2026-05/07_fix_insurance_purchase_idcardtype_field_rename.md（v2 同源字段改名背景）
• 代码位置：hl-order-service-v3/.../insurance/dto/PurchaseInsuranceRequest.java、AdminInsuranceController.java:124
• 负责人：腰苏图