hl-api-changelog/changelogs-v2/2026-06/13_前端修复_保险订单列表调错路径orders-list应改list-管理后台.md

【前端修复·管理后台】保险订单列表页报「参数类型错误: 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）

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

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}

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

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。这两个都是该新页面接线/取数的前端问题。