yaosutu 1453fae332 docs(changelog): #3681 保险订单列表 /orders 改名 /list（破坏性·旧路径下线404）

PR #3682 已合并 dev-v3。声明旧 GET /v3/admin/insurance/orders 下线返 404，
新路径 GET /v3/admin/insurance/list；入参出参不变；详情 /orders/{id} 与
按订单 /orders/by-order/{orderId} 路径保持不变。

2026-06-11 11:48:30 +08:00

4.8 KiB

原始文件 Blame 文件历史

date, type, module, priority, status, restart_service, 端类型, breaking_change, gitea_issue, gitea_pr

date	type	module	priority	status	restart_service	端类型	breaking_change	gitea_issue	gitea_pr
2026-06-11	api-breaking-rename	hl-order-service-v3/insurance	high	merged-pending-deploy	hl-order-service-v3	管理后台	true	3681	3682

⚠️ 破坏性：保险订单列表接口路径 `/orders` 改名为 `/list`

① 接口背景

管理后台保险前端全量切 v3 后，保险页整体 404。排查实测：网关路由通、order-service-v3 健康、Nacos 注册正常；真因是前端调 GET /v3/admin/insurance/list，而后端原路径是 GET /v3/admin/insurance/orders，路径对不上。本次后端把列表接口路径改名为 /list 对齐前端。

② 变更清单

接口	旧路径（已下线）	新路径	方法
保险订单列表（分页）	`~~/v3/admin/insurance/orders~~`	`/v3/admin/insurance/list`	GET

不加别名：旧 /orders 路径已删除，再调用返回 404。 未受影响（仍用 /orders 前缀，不要误改）：

GET /v3/admin/insurance/orders/{id}（保险订单详情）

GET /v3/admin/insurance/orders/by-order/{orderId}（按业务订单查保险列表）

③ 接口详情

路径：GET /v3/admin/insurance/list
作用：分页查询保险订单列表
入参 / 出参与原 /orders 完全一致，仅路径变化

④ 入参（query，InsuranceQueryRequest）

字段	类型	必填	说明
`orderId`	Long	否	关联业务订单 ID
`policyNo`	String	否	保单号
`status`	String	否	保险状态，枚举见 ⑥
`insuredName`	String	否	被保人姓名
`insuranceProductId`	Long	否	保险产品 ID
`pageNo` / `pageSize`	Integer	否	标准分页参数

⑤ 出参（PageResult）

字段	类型	说明
`insuranceOrderId`	Long	保险订单 ID
`orderId`	Long	关联业务订单 ID
`planId`	Long	保险计划 ID
`extOrderNo`	String	保游网订单号
`extPolicyNo`	String	保单号（保游网保单号）
`policyNo`	String	兼容字段，与 extPolicyNo 同值，后续废弃，前端请改用 extPolicyNo
`productName` / `planName`	String	保险产品 / 计划名称
`premium`	BigDecimal	保费金额(元)
`insuredCount`	Integer	被保人数
`coverageStartDate` / `coverageEndDate`	LocalDate	保障起止日期
`status` / `statusLabel`	String	保险状态 / 状态标签
`policyPdfUrl`	String	保单 PDF 地址（INSURED 状态异步回填，未回填为 null）
`createTime`	LocalDateTime	投保时间

⑥ 枚举 / 数据字典

status 保险状态：

值	含义
`PENDING`	待生效
`EFFECTIVE`	生效中
`EXPIRED`	已过期
`CANCELLED`	已取消

⑦ 错误码

场景	响应
调用已下线的旧路径 `/orders`	404 Not Found（路由不存在）

⑧ 示例

典型（新路径）

GET /v3/admin/insurance/list?pageNo=1&pageSize=20&status=EFFECTIVE
→ 200 { "code":200, "data": { "list":[...], "total":..., "pageNo":1, "pageSize":20 } }

异常（调旧路径，已下线）

GET /v3/admin/insurance/orders?pageNo=1&pageSize=20
→ 404  （旧路径已删除，必须改用 /list）

⑨ 业务边界

仅列表接口改名；详情、按订单查两个接口路径不变。
入参出参字段、分页结构与改名前完全相同。

⑩ 修改前后对比

维度	改名前	改名后
列表路径	`GET /v3/admin/insurance/orders`	`GET /v3/admin/insurance/list`
旧路径可用性	—	下线，调用 404
入参 / 出参	InsuranceQueryRequest / PageResult	不变

⑪ 影响评估 / 回滚

前端必须把列表请求从 /orders 改为 /list，否则继续 404。
无后端内部调用方（已 grep mp-service / 其它服务零引用），仅前端直调。
回滚：如需回滚，把 Controller @GetMapping("/list") 改回 /orders 即可（无数据变更）。

⑫ 注意事项

⚠️ 别把详情 /orders/{id} 和按订单 /orders/by-order/{orderId} 也改了——这两个保持 /orders 前缀不变。
部署后需重启 hl-order-service-v3。
待前端确认：若 /list 实际想要的是「保险产品列表」而非「保险订单分页」，需另改 /products（本次按订单分页处理）。

⑬ 关联 / 联系人

Issue：wx/HL#3681
PR：wx/HL#3682
代码：AdminInsuranceController.java（@GetMapping("/list")）
负责人：腰苏图

4.8 KiB 原始文件 Blame 文件历史 Unescape Escape

⚠️ 破坏性：保险订单列表接口路径 /orders 改名为 /list