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} 路径保持不变。

changelogs-v2/2026-06/11_3681_保险订单列表接口orders改名list-修改接口-管理后台.md

@@ -0,0 +1,129 @@
+---
+date: 2026-06-11
+type: api-breaking-rename
+module: hl-order-service-v3/insurance
+priority: high
+status: merged-pending-deploy
+restart_service: hl-order-service-v3
+端类型: 管理后台
+breaking_change: true
+gitea_issue: 3681
+gitea_pr: 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<InsuranceOrderVO>）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `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<InsuranceOrderVO> | **不变** |
+
+## ⑪ 影响评估 / 回滚
+
+- 前端**必须**把列表请求从 `/orders` 改为 `/list`，否则继续 404。
+- 无后端内部调用方（已 grep mp-service / 其它服务零引用），仅前端直调。
+- 回滚：如需回滚，把 Controller `@GetMapping("/list")` 改回 `/orders` 即可（无数据变更）。
+
+## ⑫ 注意事项
+
+- ⚠️ 别把详情 `/orders/{id}` 和按订单 `/orders/by-order/{orderId}` 也改了——这两个**保持 `/orders` 前缀不变**。
+- 部署后需重启 `hl-order-service-v3`。
+- 待前端确认：若 `/list` 实际想要的是「保险产品列表」而非「保险订单分页」，需另改 `/products`（本次按订单分页处理）。
+
+## ⑬ 关联 / 联系人
+
+- Issue：https://git.1814.love:8443/wx/HL/issues/3681
+- PR：https://git.1814.love:8443/wx/HL/pulls/3682
+- 代码：`AdminInsuranceController.java`（`@GetMapping("/list")`）
+- 负责人：腰苏图