docs(changelog): #3642 保险出单改异步-状态新增INSURING-管理后台+小程序

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` 态的真实产生需保游切换异步出单产品后触发。