From 4fdf27bb6e8e6e6034ef2c091ec48edcb7817da2 Mon Sep 17 00:00:00 2001 From: yaosutu <770858045@qq.com> Date: Tue, 16 Jun 2026 10:34:25 +0800 Subject: [PATCH] =?UTF-8?q?feat(changelog):=20=E6=8E=A8=E9=80=81=E4=BF=9D?= =?UTF-8?q?=E9=99=A9=E8=AE=A2=E5=8D=95=E5=88=97=E8=A1=A8=E6=8E=A5=E5=8F=A3?= =?UTF-8?q?=E8=B7=AF=E5=BE=84=E6=94=B9=E5=90=8D=20changelog=EF=BC=88#3682/?= =?UTF-8?q?#3681=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit GET /v3/admin/insurance/orders 改名为 GET /v3/admin/insurance/list 旧路径已删除，调用返回 404，前端需立即切换。 入参出参字段不变，仅路径变更。 --- ...单列表-orders改名为list-修改接口-管理后台.md | 331 ++++++++++++++++++ 1 file changed, 331 insertions(+) create mode 100644 changelogs-v2/2026-06/16_3681_保险订单列表-orders改名为list-修改接口-管理后台.md diff --git a/changelogs-v2/2026-06/16_3681_保险订单列表-orders改名为list-修改接口-管理后台.md b/changelogs-v2/2026-06/16_3681_保险订单列表-orders改名为list-修改接口-管理后台.md new file mode 100644 index 0000000..a3176fe --- /dev/null +++ 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> | + +--- + +## 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 +``` + +响应： + +```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 +``` + +响应： + +```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 +``` + +响应： + +```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） |