# 【前端修复·管理后台】保险订单列表页报「参数类型错误: id='list'」——前端调错路径 `/orders/list`，应改为 `/list`

> 服务：hl-order-service-v3（保险模块 AdminInsuranceController） | 无 PR（前端调错 URL，后端契约正常无需改） | 测试服网关 9443 实测复现并确认（2026-06-13）
> 背景：wx 打开「保险管理 → 保险订单」页（`192.168.100.160:9527/insurance/orders`），页面顶部红条报 **「参数类型错误: id='list'（需要 Long 类型）」**。经网关实测复现，定位为前端列表接口 URL 写错。

## ⚠️ 关键说明（前端动作）

1. **根因：前端把保险订单列表调成了 `GET /v3/admin/insurance/orders/list`，这个路径后端不存在。**
   - 后端只有 `GET /v3/admin/insurance/orders/{id}`（按 ID 查保险订单详情，`{id}` 是 Long 类型）。
   - 前端那个 `.../orders/list` 请求里的 `list` 被 Spring 当成 `{id}` 去解析成 Long，解析失败 → 全局异常处理器返回「参数类型错误: id='list'（需要 Long 类型）」。
   - 注意：本项目所有接口**恒返 HTTP 200**，业务错误码在响应体 `code` 字段里。所以 Network 面板看到的是 `200`，但 body 是 `{"code":400,"message":"参数类型错误..."}`——别被 200 误导，要看 body。

2. **正确的列表路径 = `GET /v3/admin/insurance/list`（不带 `/orders`）。**
   - 这是 v3 全站 admin 列表的统一惯例 `{模块base}/list`：合同 `/v3/admin/contract/list`、退款政策 `/v3/admin/refund-policy/list`、评价 `/list`、支付 `/list`、保险方案 `/list`……保险订单列表同理就是 `/v3/admin/insurance/list`。
   - 请把保险订单页的列表请求 URL 从 `…/insurance/orders/list` 改成 `…/insurance/list`，**入参/分页参数（page/pageSize/筛选项）完全不变**。

3. 详情/按订单查仍走 `/orders/...`，不要动：列表是 `/list`、详情是 `/orders/{id}`，这两者本身不冲突，冲突只来自前端给列表错误地拼了 `/orders/` 前缀。

## 路径对照表

| 用途 | 现状（错误） | 应改为（正确） |
|---|---|---|
| 保险订单**列表** | `GET /v3/admin/insurance/orders/list?page=1&pageSize=20` ❌ | `GET /v3/admin/insurance/list?page=1&pageSize=20` ✅ |
| 保险订单**详情** | — | `GET /v3/admin/insurance/orders/{id}`（id 为 Long） |
| 按业务订单查保险 | — | `GET /v3/admin/insurance/orders/by-order/{orderId}` |

## 实测（测试服网关 https://api.test.1814.love:9443）

错误路径（复现用户截图的报错）：

```bash
curl -k "https://api.test.1814.love:9443/v3/admin/insurance/orders/list?page=1&pageSize=20" \
  -H "Authorization: Bearer <adminToken>"
# → {"code":400,"message":"参数类型错误: id='list'（需要 Long 类型）","data":null,"success":false}
```

正确路径（返回真实订单数据）：

```bash
curl -k "https://api.test.1814.love:9443/v3/admin/insurance/list?page=1&pageSize=20" \
  -H "Authorization: Bearer <adminToken>"
# → {"code":200,"message":"成功","data":{"records":[
#      {"insuranceOrderId":"2065360048397193217","policyNo":"PICC2026GUARD",
#       "premium":3400.00,"insuredCount":1,"coverageStartDate":"2026-01-01",
#       "coverageEndDate":"2026-12-31","status":"CANCELLED","statusLabel":"已退保", ...}
#    ], "total":..., "page":1, "pageSize":20}}
```

## 结论

后端列表端点正常、契约就是 `/v3/admin/insurance/list`，**无需后端改动**。请前端把保险订单列表页的请求 URL 改为 `/v3/admin/insurance/list` 即可消除红条报错。

> 附：本页此前的「保险产品下拉为空」是另一个前端数据加载问题（后端 `/products/all` 实测返 10 个 ACTIVE 产品），详见同目录 `13_前端核实_保险下单页产品下拉空与司机险混淆-后端正常无需改-管理后台.md`。这两个都是该新页面接线/取数的前端问题。