wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 Actions 软件包 项目 版本发布 百科 动态
hl-api-changelog/changelogs-v2/2026-06/16_3681_保险订单列表-orders改名为list-修改接口-管理后台.md
yaosutu 4fdf27bb6e feat(changelog): 推送保险订单列表接口路径改名 changelog（#3682/#3681） 
GET /v3/admin/insurance/orders 改名为 GET /v3/admin/insurance/list
旧路径已删除，调用返回 404，前端需立即切换。
入参出参字段不变，仅路径变更。
2026-06-16 10:34:39 +08:00

11 KiB
原始文件 Blame 文件历史

保险订单列表接口路径改名：/orders -> /list

  • 变更类型：修改接口（破坏性路径变更）
  • 端类型：管理后台
  • 日期：2026-06-16
  • 关联 Issue：#3681
  • PR：#3682
  • Commit：36b787692
  • 后端负责人：腰苏图

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>

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 出参字段

外层统一响应包装：

{
  "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>

响应：

{
  "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>

响应：

{
  "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>

响应：

{
  "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
PR #3682 fix(order-v3/保险): 保险订单列表接口 /orders 改名为 /list
Merge Commit dc29cb08f
实现 Commit 36b787692
后端负责人 腰苏图
服务 hl-order-service-v3（端口 8086）