feat(changelog): 推送保险订单列表接口路径改名 changelog（#3682/#3681）

GET /v3/admin/insurance/orders 改名为 GET /v3/admin/insurance/list 旧路径已删除，调用返回 404，前端需立即切换。入参出参字段不变，仅路径变更。
2026-06-16 10:34:25 +08:00 · 2026-06-16 10:34:25 +08:00 · 4fdf27bb6e
--- a/changelogs-v2/2026-06/16_3681_保险订单列表-orders改名为list-修改接口-管理后台.md
+++ b/changelogs-v2/2026-06/16_3681_保险订单列表-orders改名为list-修改接口-管理后台.md
@ -0,0 +1,331 @@
+# 保险订单列表接口路径改名：/orders -> /list
+
+- **变更类型**：修改接口（破坏性路径变更）
+- **端类型**：管理后台
+- **日期**：2026-06-16
+- **关联 Issue**：[#3681](https://git.1814.love:8443/wx/HL/issues/3681)
+- **PR**：[#3682](https://git.1814.love:8443/wx/HL/pulls/3682)
+- **Commit**：[36b787692](https://git.1814.love:8443/wx/HL/commit/36b7876922caf9843b4c4911aa94a237a5fd9573)
+- **后端负责人**：腰苏图
+
+---
+
+## 1 接口背景
+
+前端保险模块全量切 v3 联调时，保险列表页整体 404。排查确认网关路由通、服务健康、Nacos 注册正常，真因是前端调用 GET /v3/admin/insurance/list，而后端原路径为 GET /v3/admin/insurance/orders，名称对不上。
+
+本次将后端路径改为与前端对齐，不保留旧路径别名，旧路径 /orders 即时下线（再调返回 404）。
+
+注意：/orders/{id}（详情）、/orders/by-order/{orderId}（按订单查）两个接口路径不变，本次仅修改列表接口。
+
+---
+
+## 2 变更清单
+
+| # | 变更项 | 原来 | 现在 |
+|---|--------|------|------|
+| 1 | 接口路径 | GET /v3/admin/insurance/orders | GET /v3/admin/insurance/list |
+| 2 | 旧路径状态 | 可用 | **已删除，调用返回 404** |
+| 3 | 入参字段 | 无变化 | 无变化 |
+| 4 | 出参字段 | 无变化 | 无变化 |
+
+---
+
+## 3 接口详情
+
+| 项目 | 内容 |
+|------|------|
+| **方法 + 路径** | GET /v3/admin/insurance/list |
+| **接口名** | 保险订单列表 |
+| **认证** | 需要管理员 JWT Token（Header: Authorization: Bearer token） |
+| **幂等性** | 查询接口，天然幂等 |
+| **限流** | 无特殊限流，走网关全局限流 |
+| **Content-Type** | Query String（无请求体） |
+| **响应类型** | Result<PageResult<InsuranceOrderVO>> |
+
+---
+
+## 4 接口入参
+
+### 4.1 Query 参数（全部可选，继承分页基类）
+
+| 字段名 | 类型 | 必填 | 说明 | 示例 |
+|--------|------|------|------|------|
+| page | Integer | 否 | 页码，最小 1，默认 1 | 1 |
+| pageSize | Integer | 否 | 每页条数，最小 1，最大 100，默认 20 | 20 |
+| orderId | Long | 否 | 关联订单 ID | 1234567890 |
+| policyNo | String | 否 | 保单号 | POL202605010001 |
+| status | String | 否 | 保险状态，枚举值见第 6 节 | INSURED |
+| insuredName | String | 否 | 被保人姓名（模糊匹配） | 张三 |
+| insuranceProductId | Long | 否 | 保险产品 ID | 200 |
+
+### 4.2 请求体
+
+无（GET 接口，全部参数走 Query String）
+
+---
+
+## 5 出参字段
+
+外层统一响应包装：
+
+```json
+{
+  "code": 200,
+  "msg": "success",
+  "data": {
+    "list": [ InsuranceOrderVO ],
+    "total": 100,
+    "page": 1,
+    "pageSize": 20
+  }
+}
+```
+
+InsuranceOrderVO 字段明细：
+
+| 字段名 | 类型 | 说明 |
+|--------|------|------|
+| insuranceOrderId | Long | 保险订单 ID |
+| orderId | Long | 关联业务订单 ID |
+| planId | Long | 保险计划 ID（指向 insurance_plan 表） |
+| extOrderNo | String | 保游网订单号 |
+| extPolicyNo | String | 保单号（保游网保单号），推荐使用此字段 |
+| policyNo | String | 保单号（兼容字段，与 extPolicyNo 同值，后续版本将废弃，请改用 extPolicyNo） |
+| productName | String | 保险产品名称 |
+| planName | String | 保险计划名称 |
+| policyHolderName | String | 投保人（投保主体公司名）；列表页「投保人」列读此字段 |
+| premium | BigDecimal | 保费金额（元） |
+| totalPremium | BigDecimal | 保费金额（元），与 premium 同值，与详情 VO 字段名对齐 |
+| insuredCount | Integer | 被保人数 |
+| coverageStartDate | String（LocalDate） | 保障开始日期，格式 yyyy-MM-dd |
+| coverageEndDate | String（LocalDate） | 保障结束日期，格式 yyyy-MM-dd |
+| startDate | String（LocalDate） | 保障开始日期，与 coverageStartDate 同值，与详情 VO 字段名对齐 |
+| endDate | String（LocalDate） | 保障结束日期，与 coverageEndDate 同值，与详情 VO 字段名对齐 |
+| status | String | 保险状态枚举，见第 6 节 |
+| statusLabel | String | 状态中文标签（如「已承保」） |
+| policyPdfUrl | String / null | 保单 PDF 地址；INSURED 状态下异步回填，未回填或 OSS 未配置时为 null |
+| source | String | 订单来源，见第 6 节 |
+| bizType | String | 保单归属业务类型，见第 6 节 |
+| bizId | String | 归属业务 ID（ORDER=订单 ID，DRIVER=司机 ID；雪花 ID 序列化为字符串防精度丢失） |
+| createTime | String（LocalDateTime） | 投保时间，格式 yyyy-MM-dd HH:mm:ss |
+
+---
+
+## 6 枚举 / 数据字典
+
+### 保险状态（status）
+
+| 枚举值 | 中文标签 | 说明 |
+|--------|----------|------|
+| PENDING | 待投保 | 已创建，尚未发起投保 |
+| INSURING | 投保中 | 已提交保游网，等待出单 |
+| INSURED | 已投保 | 出单成功，保障生效 |
+| CANCELLED | 已取消 | 已退保 |
+| FAILED | 投保失败 | 投保流程异常 |
+
+备注：入参 InsuranceQueryRequest.status 注解说明是 PENDING=待出单，出参 InsuranceOrderVO.status 注解说明是 PENDING=待投保，含义一致，「待出单」与「待投保」均指同一状态。
+
+### 订单来源（source）
+
+| 枚举值 | 说明 |
+|--------|------|
+| BAOYOU | 保游网出单 |
+| MANUAL | 手工录入（司机年保档案联动） |
+
+### 保单归属业务类型（bizType）
+
+| 枚举值 | 说明 |
+|--------|------|
+| ORDER | 订单险（bizId = 订单 ID） |
+| DRIVER | 司机险（bizId = 司机 ID） |
+
+---
+
+## 7 错误码
+
+| HTTP 状态码 | code | 说明 | 触发场景 |
+|-------------|------|------|---------|
+| 200 | 200 | 成功 | 正常查询 |
+| 400 | 400 | 参数校验失败 | page < 1 或 pageSize > 100 |
+| **404** | **404** | **接口不存在** | **调用旧路径 GET /v3/admin/insurance/orders（已删除）** |
+| 401 | 401 | 未认证 | JWT Token 缺失或过期 |
+
+---
+
+## 8 示例
+
+### 8.1 典型成功示例
+
+请求：
+
+```
+GET /v3/admin/insurance/list?page=1&pageSize=10&status=INSURED
+Authorization: Bearer <admin-token>
+```
+
+响应：
+
+```json
+{
+  "code": 200,
+  "msg": "success",
+  "data": {
+    "list": [
+      {
+        "insuranceOrderId": "1934567890123456789",
+        "orderId": "1934567890000000001",
+        "planId": 10,
+        "extOrderNo": "BY2026060100001",
+        "extPolicyNo": "POL202606010001",
+        "policyNo": "POL202606010001",
+        "productName": "呼籁旅行意外险",
+        "planName": "标准计划",
+        "policyHolderName": "呼籁旅行有限公司",
+        "premium": 120.00,
+        "totalPremium": 120.00,
+        "insuredCount": 2,
+        "coverageStartDate": "2026-07-01",
+        "coverageEndDate": "2026-07-05",
+        "startDate": "2026-07-01",
+        "endDate": "2026-07-05",
+        "status": "INSURED",
+        "statusLabel": "已承保",
+        "policyPdfUrl": "https://oss.example.com/policy/POL202606010001.pdf",
+        "source": "BAOYOU",
+        "bizType": "ORDER",
+        "bizId": "1934567890000000001",
+        "createTime": "2026-06-01 10:30:00"
+      }
+    ],
+    "total": 1,
+    "page": 1,
+    "pageSize": 10
+  }
+}
+```
+
+### 8.2 边界情况示例（无匹配数据）
+
+请求：
+
+```
+GET /v3/admin/insurance/list?page=1&pageSize=20&insuredName=不存在的人
+Authorization: Bearer <admin-token>
+```
+
+响应：
+
+```json
+{
+  "code": 200,
+  "msg": "success",
+  "data": {
+    "list": [],
+    "total": 0,
+    "page": 1,
+    "pageSize": 20
+  }
+}
+```
+
+### 8.3 业务失败示例——调旧路径返回 404
+
+请求（旧路径，已下线）：
+
+```
+GET /v3/admin/insurance/orders?page=1&pageSize=20
+Authorization: Bearer <admin-token>
+```
+
+响应：
+
+```json
+{
+  "code": 404,
+  "msg": "No handler found for GET /v3/admin/insurance/orders",
+  "data": null
+}
+```
+
+请务必将所有调用从 /orders 切换到 /list，旧路径无法回退，调用即 404。
+
+---
+
+## 9 业务边界
+
+适用场景：
+- 管理后台保险列表页分页查询
+- 可按订单 ID、保单号、状态、被保人姓名、保险产品 ID 任意组合筛选
+- 不传任何筛选条件时返回全量分页
+
+不适用场景：
+- 按订单 ID 获取该订单下所有保险单列表：使用 GET /v3/admin/insurance/orders/by-order/{orderId}（路径未变）
+- 获取单条保险订单详情：使用 GET /v3/admin/insurance/orders/{id}（路径未变）
+
+特殊边界：
+- policyPdfUrl 在 INSURED 状态下异步回填，刚出单时可能为 null，前端需兼容 null 展示
+- policyNo 为兼容字段，与 extPolicyNo 同值，后续将废弃，建议新代码统一改用 extPolicyNo
+- premium 与 totalPremium 同值，与详情 VO 字段名对齐而保留双字段；coverageStartDate/startDate、coverageEndDate/endDate 同理
+- bizId 为雪花 ID 序列化字符串（非 number），前端不要转 number（精度丢失）
+
+---
+
+## 10 修改前后对比
+
+### 路径级对比
+
+| 对比项 | 原来 | 现在 |
+|--------|------|------|
+| 列表接口路径 | GET /v3/admin/insurance/orders | GET /v3/admin/insurance/list |
+| 旧路径是否可用 | 可用 | 不可用，返回 404 |
+| 入参字段 | InsuranceQueryRequest | InsuranceQueryRequest（不变） |
+| 出参字段 | InsuranceOrderVO | InsuranceOrderVO（不变） |
+| 其他接口 | 不变 | 不变（详情、按订单查均未动） |
+
+### 未改动接口（确认路径不变）
+
+| 接口 | 路径 | 状态 |
+|------|------|------|
+| 保险订单详情 | GET /v3/admin/insurance/orders/{id} | 路径不变 |
+| 按订单查保险列表 | GET /v3/admin/insurance/orders/by-order/{orderId} | 路径不变 |
+
+---
+
+## 11 影响评估 / 回滚
+
+破坏兼容性：是。旧路径 GET /v3/admin/insurance/orders 调用即 404，无降级。
+
+前端需要同步：是。将所有调用保险订单列表的请求 URL 从 /v3/admin/insurance/orders 改为 /v3/admin/insurance/list。
+
+影响范围：
+- 仅影响保险列表页的数据加载请求
+- 详情页、按订单查保险等其他请求不受影响
+
+回滚方案：
+- 本次改动极小（仅 @GetMapping 注解值变更），如有问题可快速 revert PR #3682 重新部署
+- 回滚后前端应切回旧路径 /v3/admin/insurance/orders
+- 后端回滚与前端切换需同步进行，否则一端改完另一端未跟上仍会 404
+
+---
+
+## 12 注意事项
+
+1. 立即切换路径：旧路径 GET /v3/admin/insurance/orders 已在 PR #3682 合并时同步删除，不存在过渡期，请尽快切换。
+2. 仅列表路径变化：/orders/{id}（详情）和 /orders/by-order/{orderId}（按订单查）路径未变，不需要修改。
+3. 字段无变化：入参 InsuranceQueryRequest 和出参 InsuranceOrderVO 的所有字段均未改动，切换路径后无需修改字段映射。
+4. 双名字段：VO 中 policyNo/extPolicyNo、premium/totalPremium、coverageStartDate/startDate、coverageEndDate/endDate 均为同值双字段，新代码推荐使用后者（extPolicyNo、totalPremium、startDate、endDate），旧名称后续将废弃。
+5. bizId 是字符串：雪花 ID 防精度丢失，不要用 JS Number 解析。
+
+---
+
+## 13 关联 / 联系人
+
+| 项目 | 链接 / 内容 |
+|------|------------|
+| Issue | [#3681 保险订单列表接口 /orders 改名为 /list](https://git.1814.love:8443/wx/HL/issues/3681) |
+| PR | [#3682 fix(order-v3/保险): 保险订单列表接口 /orders 改名为 /list](https://git.1814.love:8443/wx/HL/pulls/3682) |
+| Merge Commit | [dc29cb08f](https://git.1814.love:8443/wx/HL/commit/dc29cb08fb6e127f7df375b174528046cdfe2efe) |
+| 实现 Commit | [36b787692](https://git.1814.love:8443/wx/HL/commit/36b7876922caf9843b4c4911aa94a237a5fd9573) |
+| 后端负责人 | 腰苏图 |
+| 服务 | hl-order-service-v3（端口 8086） |