docs(changelog): 保险订单列表前端调错路径/orders/list应改/list——id=list类型错误根因+正确契约 [前端通知]

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

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

@@ -0,0 +1,53 @@
+# 【前端修复·管理后台】保险订单列表页报「参数类型错误: 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`。这两个都是该新页面接线/取数的前端问题。