wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 Actions 软件包 项目 版本发布 百科 动态

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

浏览代码 
GET /v3/admin/insurance/orders 改名为 GET /v3/admin/insurance/list
旧路径已删除，调用返回 404，前端需立即切换。
入参出参字段不变，仅路径变更。
这个提交包含在：
yaosutu 2026-06-16 10:34:25 +08:00
父节点 fb9de38a5f
当前提交 4fdf27bb6e
共有 1 个文件被更改，包括 331 次插入 和 0 次删除
显示统计 下载 Patch 文件 下载 Diff 文件 展开所有文件 折叠所有文件

331
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） |