---
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<InsuranceOrderVO>）

| 字段 | 类型 | 说明 |
|------|------|------|
| `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<InsuranceOrderVO> | **不变** |

## ⑪ 影响评估 / 回滚

- 前端**必须**把列表请求从 `/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")`）
- 负责人：腰苏图