From e0dcf2e1afaeb721371e691c5fa43d2467abd298 Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Sat, 13 Jun 2026 17:03:08 +0800 Subject: [PATCH] =?UTF-8?q?docs(changelog):=20=E4=BF=9D=E9=99=A9=E8=AE=A2?= =?UTF-8?q?=E5=8D=95=E5=88=97=E8=A1=A8=E5=89=8D=E7=AB=AF=E8=B0=83=E9=94=99?= =?UTF-8?q?=E8=B7=AF=E5=BE=84/orders/list=E5=BA=94=E6=94=B9/list=E2=80=94?= =?UTF-8?q?=E2=80=94id=3Dlist=E7=B1=BB=E5=9E=8B=E9=94=99=E8=AF=AF=E6=A0=B9?= =?UTF-8?q?=E5=9B=A0+=E6=AD=A3=E7=A1=AE=E5=A5=91=E7=BA=A6=20[=E5=89=8D?= =?UTF-8?q?=E7=AB=AF=E9=80=9A=E7=9F=A5]?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Fable 5 --- ...订单列表调错路径orders-list应改list-管理后台.md | 53 +++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 changelogs-v2/2026-06/13_前端修复_保险订单列表调错路径orders-list应改list-管理后台.md diff --git a/changelogs-v2/2026-06/13_前端修复_保险订单列表调错路径orders-list应改list-管理后台.md b/changelogs-v2/2026-06/13_前端修复_保险订单列表调错路径orders-list应改list-管理后台.md new file mode 100644 index 0000000..a0c089d --- /dev/null +++ b/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 " +# → {"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 " +# → {"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`。这两个都是该新页面接线/取数的前端问题。