hl-api-changelog/changelogs-v2/2026-06/10_3642_保险出单改异步-状态新增INSURING出单中-修改接口-管理后台+小程序.md

【修改·管理后台+小程序】保险出单改异步,保险状态新增 INSURING(出单中),保单号可能延迟回填

存放目录: changelogs-v2/2026-06/ 涉及服务: hl-order-service-v2 / hl-order-service-v3 / hl-gateway PR: #3646(已合并 dev-v3) | Issue: #3642 | 日期: 2026-06-10 影响范围: 管理后台保险列表/订单详情、小程序保险展示的状态字段与保单号字段

⚠️ 关键说明(前端必看 2 点)

保游网保险接口升级到 4.2"见费出单",出单从"同步即时返回保单号"改为部分产品"异步出单"(保司确认收费后再回调出单结果)。对前端展示有两处影响,均为向后兼容的字段取值变化,无字段增删、无结构变化:

1. 保险状态(insuranceStatus / 保险订单 status)新增取值 INSURING(出单中)。原值域 NONE / INSURED / CANCELLED / FAILED,现增加 INSURING。请前端在保险状态字典/映射中补这一项,文案建议"出单中",否则该状态会显示为原始码 INSURING 或落入 default 分支。
2. 保单号(extPolicyNo / policyNo)在异步出单产品下,投保成功瞬间为空,需等保游回调到达后回填。前端遇保单号为空且状态为 INSURING 时,应显示"出单中,保单号生成后展示",不要显示为投保失败。

注:仅"异步出单"产品(保游下单同步响应 MsgCode=80099)会经历 INSURING 窗口;"实时出单"产品(MsgCode=10000)仍直接 INSURED 并立即带保单号,行为不变。保游本月内逐步切换各保司接口,故 INSURING 会在切换后开始出现。

1. 保险状态值域(完整字典)

状态码	含义	说明
NONE	无保险	订单未生成保险(仅订单主表镜像字段出现)
INSURING	出单中(新增)	异步出单受理成功,等保司回调确认出单
INSURED	已投保	出单成功,有保单号
CANCELLED	已退保	—
FAILED	投保失败	出单失败,可重投

管理后台订单主表镜像 insuranceStatus 聚合优先级:INSURED > INSURING > CANCELLED > FAILED > NONE。

2. 受影响接口(取值变化,非结构变化)

端	接口	变化点
管理后台	保险订单列表/详情(/admin/insurance/*、/v3/admin/insurance/*)	status/statusLabel 可能为 INSURING/出单中;policyNo 可能为空
管理后台	订单详情-合同保险 Tab	insuranceStatus 可能为 INSURING;保单号可能空
小程序	保险详情/保单展示(/mp/insurance/*、订单保险块)	status/statusLabel 同上;policyNo 空时 PDF 暂不可下载(显示"出单中")

3. 无需前端改动的部分

• 保游回调接收端点(/insurance/callback/baoyou、/v3/insurance/callback/baoyou)是后端接收保游通知的内部端点,前端不调用。
• 出单成功回调到达后,后端自动回填保单号 + 翻 INSURED + 触发 PDF 上传 + 发投保成功通知,前端按现有逻辑刷新即可看到。

验证

测试服已部署(hl-gateway / hl-order-service-v2 / hl-order-service-v3),回调端点经网关 9443 可达(HTTP 200)。INSURING 态的真实产生需保游切换异步出单产品后触发。