diff --git a/changelogs-v2/2026-06/11_3681_保险订单列表接口orders改名list-修改接口-管理后台.md b/changelogs-v2/2026-06/11_3681_保险订单列表接口orders改名list-修改接口-管理后台.md new file mode 100644 index 0000000..e7b9756 --- /dev/null +++ b/changelogs-v2/2026-06/11_3681_保险订单列表接口orders改名list-修改接口-管理后台.md @@ -0,0 +1,129 @@ +--- +date: 2026-06-11 +type: api-breaking-rename +module: hl-order-service-v3/insurance +priority: high +status: merged-pending-deploy +restart_service: hl-order-service-v3 +端类型: 管理后台 +breaking_change: true +gitea_issue: 3681 +gitea_pr: 3682 +--- + +# ⚠️ 破坏性:保险订单列表接口路径 `/orders` 改名为 `/list` + +## ① 接口背景 + +管理后台保险前端全量切 v3 后,保险页整体 404。排查实测:网关路由通、order-service-v3 健康、Nacos 注册正常;真因是**前端调 `GET /v3/admin/insurance/list`,而后端原路径是 `GET /v3/admin/insurance/orders`**,路径对不上。本次后端把列表接口路径改名为 `/list` 对齐前端。 + +## ② 变更清单 + +| 接口 | 旧路径(已下线) | 新路径 | 方法 | +|------|------------------|--------|------| +| 保险订单列表(分页) | `~~/v3/admin/insurance/orders~~` | `/v3/admin/insurance/list` | GET | + +> **不加别名**:旧 `/orders` 路径**已删除**,再调用返回 404。 +> **未受影响**(仍用 `/orders` 前缀,不要误改): +> - `GET /v3/admin/insurance/orders/{id}`(保险订单详情) +> - `GET /v3/admin/insurance/orders/by-order/{orderId}`(按业务订单查保险列表) + +## ③ 接口详情 + +- **路径**:`GET /v3/admin/insurance/list` +- **作用**:分页查询保险订单列表 +- **入参 / 出参与原 `/orders` 完全一致,仅路径变化** + +## ④ 入参(query,InsuranceQueryRequest) + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `orderId` | Long | 否 | 关联业务订单 ID | +| `policyNo` | String | 否 | 保单号 | +| `status` | String | 否 | 保险状态,枚举见 ⑥ | +| `insuredName` | String | 否 | 被保人姓名 | +| `insuranceProductId` | Long | 否 | 保险产品 ID | +| `pageNo` / `pageSize` | Integer | 否 | 标准分页参数 | + +## ⑤ 出参(PageResult) + +| 字段 | 类型 | 说明 | +|------|------|------| +| `insuranceOrderId` | Long | 保险订单 ID | +| `orderId` | Long | 关联业务订单 ID | +| `planId` | Long | 保险计划 ID | +| `extOrderNo` | String | 保游网订单号 | +| `extPolicyNo` | String | 保单号(保游网保单号) | +| `policyNo` | String | 兼容字段,与 extPolicyNo 同值,**后续废弃,前端请改用 extPolicyNo** | +| `productName` / `planName` | String | 保险产品 / 计划名称 | +| `premium` | BigDecimal | 保费金额(元) | +| `insuredCount` | Integer | 被保人数 | +| `coverageStartDate` / `coverageEndDate` | LocalDate | 保障起止日期 | +| `status` / `statusLabel` | String | 保险状态 / 状态标签 | +| `policyPdfUrl` | String | 保单 PDF 地址(INSURED 状态异步回填,未回填为 null) | +| `createTime` | LocalDateTime | 投保时间 | + +## ⑥ 枚举 / 数据字典 + +`status` 保险状态: + +| 值 | 含义 | +|----|------| +| `PENDING` | 待生效 | +| `EFFECTIVE` | 生效中 | +| `EXPIRED` | 已过期 | +| `CANCELLED` | 已取消 | + +## ⑦ 错误码 + +| 场景 | 响应 | +|------|------| +| 调用已下线的旧路径 `/orders` | **404 Not Found**(路由不存在) | + +## ⑧ 示例 + +### 典型(新路径) + +``` +GET /v3/admin/insurance/list?pageNo=1&pageSize=20&status=EFFECTIVE +→ 200 { "code":200, "data": { "list":[...], "total":..., "pageNo":1, "pageSize":20 } } +``` + +### 异常(调旧路径,已下线) + +``` +GET /v3/admin/insurance/orders?pageNo=1&pageSize=20 +→ 404 (旧路径已删除,必须改用 /list) +``` + +## ⑨ 业务边界 + +- 仅列表接口改名;详情、按订单查两个接口路径不变。 +- 入参出参字段、分页结构与改名前完全相同。 + +## ⑩ 修改前后对比 + +| 维度 | 改名前 | 改名后 | +|------|--------|--------| +| 列表路径 | `GET /v3/admin/insurance/orders` | `GET /v3/admin/insurance/list` | +| 旧路径可用性 | — | **下线,调用 404** | +| 入参 / 出参 | InsuranceQueryRequest / PageResult | **不变** | + +## ⑪ 影响评估 / 回滚 + +- 前端**必须**把列表请求从 `/orders` 改为 `/list`,否则继续 404。 +- 无后端内部调用方(已 grep mp-service / 其它服务零引用),仅前端直调。 +- 回滚:如需回滚,把 Controller `@GetMapping("/list")` 改回 `/orders` 即可(无数据变更)。 + +## ⑫ 注意事项 + +- ⚠️ 别把详情 `/orders/{id}` 和按订单 `/orders/by-order/{orderId}` 也改了——这两个**保持 `/orders` 前缀不变**。 +- 部署后需重启 `hl-order-service-v3`。 +- 待前端确认:若 `/list` 实际想要的是「保险产品列表」而非「保险订单分页」,需另改 `/products`(本次按订单分页处理)。 + +## ⑬ 关联 / 联系人 + +- Issue:https://git.1814.love:8443/wx/HL/issues/3681 +- PR:https://git.1814.love:8443/wx/HL/pulls/3682 +- 代码:`AdminInsuranceController.java`(`@GetMapping("/list")`) +- 负责人:腰苏图