diff --git a/changelogs-v2/2026-06/10_3642_保险出单改异步-状态新增INSURING出单中-修改接口-管理后台+小程序.md b/changelogs-v2/2026-06/10_3642_保险出单改异步-状态新增INSURING出单中-修改接口-管理后台+小程序.md new file mode 100644 index 0000000..28b6c0a --- /dev/null +++ b/changelogs-v2/2026-06/10_3642_保险出单改异步-状态新增INSURING出单中-修改接口-管理后台+小程序.md @@ -0,0 +1,44 @@ +# 【修改·管理后台+小程序】保险出单改异步,保险状态新增 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` 态的真实产生需保游切换异步出单产品后触发。