# 保险订单列表接口路径改名：/orders -> /list

- **变更类型**：修改接口（破坏性路径变更）
- **端类型**：管理后台
- **日期**：2026-06-16
- **关联 Issue**：[#3681](https://git.1814.love:8443/wx/HL/issues/3681)
- **PR**：[#3682](https://git.1814.love:8443/wx/HL/pulls/3682)
- **Commit**：[36b787692](https://git.1814.love:8443/wx/HL/commit/36b7876922caf9843b4c4911aa94a237a5fd9573)
- **后端负责人**：腰苏图

---

## 1 接口背景

前端保险模块全量切 v3 联调时，保险列表页整体 404。排查确认网关路由通、服务健康、Nacos 注册正常，真因是前端调用 GET /v3/admin/insurance/list，而后端原路径为 GET /v3/admin/insurance/orders，名称对不上。

本次将后端路径改为与前端对齐，不保留旧路径别名，旧路径 /orders 即时下线（再调返回 404）。

注意：/orders/{id}（详情）、/orders/by-order/{orderId}（按订单查）两个接口路径不变，本次仅修改列表接口。

---

## 2 变更清单

| # | 变更项 | 原来 | 现在 |
|---|--------|------|------|
| 1 | 接口路径 | GET /v3/admin/insurance/orders | GET /v3/admin/insurance/list |
| 2 | 旧路径状态 | 可用 | **已删除，调用返回 404** |
| 3 | 入参字段 | 无变化 | 无变化 |
| 4 | 出参字段 | 无变化 | 无变化 |

---

## 3 接口详情

| 项目 | 内容 |
|------|------|
| **方法 + 路径** | GET /v3/admin/insurance/list |
| **接口名** | 保险订单列表 |
| **认证** | 需要管理员 JWT Token（Header: Authorization: Bearer token） |
| **幂等性** | 查询接口，天然幂等 |
| **限流** | 无特殊限流，走网关全局限流 |
| **Content-Type** | Query String（无请求体） |
| **响应类型** | Result<PageResult<InsuranceOrderVO>> |

---

## 4 接口入参

### 4.1 Query 参数（全部可选，继承分页基类）

| 字段名 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|
| page | Integer | 否 | 页码，最小 1，默认 1 | 1 |
| pageSize | Integer | 否 | 每页条数，最小 1，最大 100，默认 20 | 20 |
| orderId | Long | 否 | 关联订单 ID | 1234567890 |
| policyNo | String | 否 | 保单号 | POL202605010001 |
| status | String | 否 | 保险状态，枚举值见第 6 节 | INSURED |
| insuredName | String | 否 | 被保人姓名（模糊匹配） | 张三 |
| insuranceProductId | Long | 否 | 保险产品 ID | 200 |

### 4.2 请求体

无（GET 接口，全部参数走 Query String）

---

## 5 出参字段

外层统一响应包装：

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "list": [ InsuranceOrderVO ],
    "total": 100,
    "page": 1,
    "pageSize": 20
  }
}
```

InsuranceOrderVO 字段明细：

| 字段名 | 类型 | 说明 |
|--------|------|------|
| insuranceOrderId | Long | 保险订单 ID |
| orderId | Long | 关联业务订单 ID |
| planId | Long | 保险计划 ID（指向 insurance_plan 表） |
| extOrderNo | String | 保游网订单号 |
| extPolicyNo | String | 保单号（保游网保单号），推荐使用此字段 |
| policyNo | String | 保单号（兼容字段，与 extPolicyNo 同值，后续版本将废弃，请改用 extPolicyNo） |
| productName | String | 保险产品名称 |
| planName | String | 保险计划名称 |
| policyHolderName | String | 投保人（投保主体公司名）；列表页「投保人」列读此字段 |
| premium | BigDecimal | 保费金额（元） |
| totalPremium | BigDecimal | 保费金额（元），与 premium 同值，与详情 VO 字段名对齐 |
| insuredCount | Integer | 被保人数 |
| coverageStartDate | String（LocalDate） | 保障开始日期，格式 yyyy-MM-dd |
| coverageEndDate | String（LocalDate） | 保障结束日期，格式 yyyy-MM-dd |
| startDate | String（LocalDate） | 保障开始日期，与 coverageStartDate 同值，与详情 VO 字段名对齐 |
| endDate | String（LocalDate） | 保障结束日期，与 coverageEndDate 同值，与详情 VO 字段名对齐 |
| status | String | 保险状态枚举，见第 6 节 |
| statusLabel | String | 状态中文标签（如「已承保」） |
| policyPdfUrl | String / null | 保单 PDF 地址；INSURED 状态下异步回填，未回填或 OSS 未配置时为 null |
| source | String | 订单来源，见第 6 节 |
| bizType | String | 保单归属业务类型，见第 6 节 |
| bizId | String | 归属业务 ID（ORDER=订单 ID，DRIVER=司机 ID；雪花 ID 序列化为字符串防精度丢失） |
| createTime | String（LocalDateTime） | 投保时间，格式 yyyy-MM-dd HH:mm:ss |

---

## 6 枚举 / 数据字典

### 保险状态（status）

| 枚举值 | 中文标签 | 说明 |
|--------|----------|------|
| PENDING | 待投保 | 已创建，尚未发起投保 |
| INSURING | 投保中 | 已提交保游网，等待出单 |
| INSURED | 已投保 | 出单成功，保障生效 |
| CANCELLED | 已取消 | 已退保 |
| FAILED | 投保失败 | 投保流程异常 |

备注：入参 InsuranceQueryRequest.status 注解说明是 PENDING=待出单，出参 InsuranceOrderVO.status 注解说明是 PENDING=待投保，含义一致，「待出单」与「待投保」均指同一状态。

### 订单来源（source）

| 枚举值 | 说明 |
|--------|------|
| BAOYOU | 保游网出单 |
| MANUAL | 手工录入（司机年保档案联动） |

### 保单归属业务类型（bizType）

| 枚举值 | 说明 |
|--------|------|
| ORDER | 订单险（bizId = 订单 ID） |
| DRIVER | 司机险（bizId = 司机 ID） |

---

## 7 错误码

| HTTP 状态码 | code | 说明 | 触发场景 |
|-------------|------|------|---------|
| 200 | 200 | 成功 | 正常查询 |
| 400 | 400 | 参数校验失败 | page < 1 或 pageSize > 100 |
| **404** | **404** | **接口不存在** | **调用旧路径 GET /v3/admin/insurance/orders（已删除）** |
| 401 | 401 | 未认证 | JWT Token 缺失或过期 |

---

## 8 示例

### 8.1 典型成功示例

请求：

```
GET /v3/admin/insurance/list?page=1&pageSize=10&status=INSURED
Authorization: Bearer <admin-token>
```

响应：

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "list": [
      {
        "insuranceOrderId": "1934567890123456789",
        "orderId": "1934567890000000001",
        "planId": 10,
        "extOrderNo": "BY2026060100001",
        "extPolicyNo": "POL202606010001",
        "policyNo": "POL202606010001",
        "productName": "呼籁旅行意外险",
        "planName": "标准计划",
        "policyHolderName": "呼籁旅行有限公司",
        "premium": 120.00,
        "totalPremium": 120.00,
        "insuredCount": 2,
        "coverageStartDate": "2026-07-01",
        "coverageEndDate": "2026-07-05",
        "startDate": "2026-07-01",
        "endDate": "2026-07-05",
        "status": "INSURED",
        "statusLabel": "已承保",
        "policyPdfUrl": "https://oss.example.com/policy/POL202606010001.pdf",
        "source": "BAOYOU",
        "bizType": "ORDER",
        "bizId": "1934567890000000001",
        "createTime": "2026-06-01 10:30:00"
      }
    ],
    "total": 1,
    "page": 1,
    "pageSize": 10
  }
}
```

### 8.2 边界情况示例（无匹配数据）

请求：

```
GET /v3/admin/insurance/list?page=1&pageSize=20&insuredName=不存在的人
Authorization: Bearer <admin-token>
```

响应：

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "list": [],
    "total": 0,
    "page": 1,
    "pageSize": 20
  }
}
```

### 8.3 业务失败示例——调旧路径返回 404

请求（旧路径，已下线）：

```
GET /v3/admin/insurance/orders?page=1&pageSize=20
Authorization: Bearer <admin-token>
```

响应：

```json
{
  "code": 404,
  "msg": "No handler found for GET /v3/admin/insurance/orders",
  "data": null
}
```

请务必将所有调用从 /orders 切换到 /list，旧路径无法回退，调用即 404。

---

## 9 业务边界

适用场景：
- 管理后台保险列表页分页查询
- 可按订单 ID、保单号、状态、被保人姓名、保险产品 ID 任意组合筛选
- 不传任何筛选条件时返回全量分页

不适用场景：
- 按订单 ID 获取该订单下所有保险单列表：使用 GET /v3/admin/insurance/orders/by-order/{orderId}（路径未变）
- 获取单条保险订单详情：使用 GET /v3/admin/insurance/orders/{id}（路径未变）

特殊边界：
- policyPdfUrl 在 INSURED 状态下异步回填，刚出单时可能为 null，前端需兼容 null 展示
- policyNo 为兼容字段，与 extPolicyNo 同值，后续将废弃，建议新代码统一改用 extPolicyNo
- premium 与 totalPremium 同值，与详情 VO 字段名对齐而保留双字段；coverageStartDate/startDate、coverageEndDate/endDate 同理
- bizId 为雪花 ID 序列化字符串（非 number），前端不要转 number（精度丢失）

---

## 10 修改前后对比

### 路径级对比

| 对比项 | 原来 | 现在 |
|--------|------|------|
| 列表接口路径 | GET /v3/admin/insurance/orders | GET /v3/admin/insurance/list |
| 旧路径是否可用 | 可用 | 不可用，返回 404 |
| 入参字段 | InsuranceQueryRequest | InsuranceQueryRequest（不变） |
| 出参字段 | InsuranceOrderVO | InsuranceOrderVO（不变） |
| 其他接口 | 不变 | 不变（详情、按订单查均未动） |

### 未改动接口（确认路径不变）

| 接口 | 路径 | 状态 |
|------|------|------|
| 保险订单详情 | GET /v3/admin/insurance/orders/{id} | 路径不变 |
| 按订单查保险列表 | GET /v3/admin/insurance/orders/by-order/{orderId} | 路径不变 |

---

## 11 影响评估 / 回滚

破坏兼容性：是。旧路径 GET /v3/admin/insurance/orders 调用即 404，无降级。

前端需要同步：是。将所有调用保险订单列表的请求 URL 从 /v3/admin/insurance/orders 改为 /v3/admin/insurance/list。

影响范围：
- 仅影响保险列表页的数据加载请求
- 详情页、按订单查保险等其他请求不受影响

回滚方案：
- 本次改动极小（仅 @GetMapping 注解值变更），如有问题可快速 revert PR #3682 重新部署
- 回滚后前端应切回旧路径 /v3/admin/insurance/orders
- 后端回滚与前端切换需同步进行，否则一端改完另一端未跟上仍会 404

---

## 12 注意事项

1. 立即切换路径：旧路径 GET /v3/admin/insurance/orders 已在 PR #3682 合并时同步删除，不存在过渡期，请尽快切换。
2. 仅列表路径变化：/orders/{id}（详情）和 /orders/by-order/{orderId}（按订单查）路径未变，不需要修改。
3. 字段无变化：入参 InsuranceQueryRequest 和出参 InsuranceOrderVO 的所有字段均未改动，切换路径后无需修改字段映射。
4. 双名字段：VO 中 policyNo/extPolicyNo、premium/totalPremium、coverageStartDate/startDate、coverageEndDate/endDate 均为同值双字段，新代码推荐使用后者（extPolicyNo、totalPremium、startDate、endDate），旧名称后续将废弃。
5. bizId 是字符串：雪花 ID 防精度丢失，不要用 JS Number 解析。

---

## 13 关联 / 联系人

| 项目 | 链接 / 内容 |
|------|------------|
| Issue | [#3681 保险订单列表接口 /orders 改名为 /list](https://git.1814.love:8443/wx/HL/issues/3681) |
| PR | [#3682 fix(order-v3/保险): 保险订单列表接口 /orders 改名为 /list](https://git.1814.love:8443/wx/HL/pulls/3682) |
| Merge Commit | [dc29cb08f](https://git.1814.love:8443/wx/HL/commit/dc29cb08fb6e127f7df375b174528046cdfe2efe) |
| 实现 Commit | [36b787692](https://git.1814.love:8443/wx/HL/commit/36b7876922caf9843b4c4911aa94a237a5fd9573) |
| 后端负责人 | 腰苏图 |
| 服务 | hl-order-service-v3（端口 8086） |