# 【修改·管理后台+小程序】保险出单改异步,保险状态新增 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` 态的真实产生需保游切换异步出单产品后触发。
