changelog-filename-gate / validate (push) Successful in 2s

详情

chore(changelog): 司机保单 policyPdfUrl 在线查看 + 投保缺省绑定全年保险（#5558）

2026-08-05 20:51:45 +08:00

4.8 KiB

原始文件 Blame 文件历史

schema, ticket, title, consumer, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base

schema	ticket	title	consumer	change_type	backend_status	gateway_status	frontend_status	frontend_owner	frontend_ref	target_release	verified_at	status_note	updated_at	base
hl-changelog/v2	5558	司机保单新增 policyPdfUrl（在线查看保单 PDF）+ 投保 bindAnnual 缺省语义变更	admin	修改接口	deployed	verified	pending						2026-08-05	dev-v3

司机险：保单行在线查看保单 PDF + 投保缺省绑定全年保险

服务：hl-fleet-service + hl-order-service-v3 + hl-common PR：#5563 Issue：wx/HL #5558 日期：2026-08-05 影响范围：管理后台司机详情「我的保单」区域、车务保险保单 Tab

变更接口

接口	方法	路径	变更
司机我的保单列表	GET	`/admin/fleet/drivers/<driverId>/insurance/policies`	每条记录新增 `policyPdfUrl`
司机险保单列表（车务保险）	GET	`/admin/fleet/insurance/policies`	每条记录新增 `policyPdfUrl`
司机险保单详情	GET	`/admin/fleet/insurance/policies/<insuranceOrderId>`	响应新增 `policyPdfUrl`
司机险投保	POST	`/admin/fleet/drivers/<driverId>/insurance/purchase`	`bindAnnual` 缺省语义变更

二、响应字段

字段	类型	必填性	值	说明
`policyPdfUrl`	`String`	条件返	保游生成后上传 OSS 的 PDF 直链	保单行「查看保单」按钮数据源；空值=保单 PDF 未生成/无电子保单（MOCK 单、MANUAL 年保单），前端应隐藏查看入口

响应示例（司机我的保单列表）：

{
  "code": 200,
  "data": [
    {
      "insuranceOrderId": "2084941753793552386",
      "policyNo": "11209006600507254235",
      "status": "INSURED",
      "totalPremium": "7.00",
      "policyPdfUrl": "https://hlgl-test.oss-cn-beijing.aliyuncs.com/insurance/policy/2026/08/05/policy_2084941753793552386.pdf"
    }
  ],
  "success": true
}

投保出参（purchase 响应）也携带 policyPdfUrl 字段，但出单受理瞬间 PDF 尚未异步生成，恒为空。

三、入参语义变更（bindAnnual 缺省）

入参	旧语义	新语义
`bindAnnual` 缺省（不传）	false：只出单不动档案	true：直接购买默认全年保险，出单成功后自动绑定司机档案（insurance_type=annual + 保单号/保费/起止回填 + annualSource=baoyou）
`bindAnnual: false`	只出单不动档案	不变：只出单不动档案
`bindAnnual: true`	出单后绑定档案	不变

背景：司机详情页投保不传 bindAnnual，旧语义下保单落库但档案保险状态不同步（有保单显示但档案 insurance_type=none）。

四、兼容性与前端事项

三处响应均为向后兼容的字段扩展，不修改既有字段与分页结构。
bindAnnual 缺省语义变更：前端若存在"只出单不动档案"的调用场景，需显式传 false；司机详情页/保险订单页投保路径无需改动（缺省即绑定档案）。
前端事项：
1. 司机详情「我的保单」列表与车务保险保单 Tab：保单行增加「查看保单」按钮，policyPdfUrl 非空时可点击；浏览器内嵌预览（window.open(policyPdfUrl) 或 iframe），不触发下载。
2. policyPdfUrl 为空时隐藏查看入口。
后端未修改 mmg/hl-ui，前端消费状态保持 pending。

验证证据

DriverInsuranceServiceTest：25 项通过（含 #5558 缺省绑定新语义用例）。
order-v3 保险域全量：229 项通过（三链 policyPdfUrl 断言）。
fleet verify：仅 2 个仓库基线失败（Step2CanonicalSnapshotServiceTest、ReleaseEOccupancyMysql8033RecoveryTest，dev-v3 干净工作区同失败，与本次改动无关）。
测试服部署：hl-fleet-service + hl-order-service-v3 滚动部署成功（20:13/20:14）。
网关验证：三个查询接口 policyPdfUrl 透传通过；真实保游单返回 OSS PDF 直链（Content-Type: application/pdf，浏览器内嵌预览），MOCK 单返回 null。
投保端到端（缺省绑定档案）验证受保游测试环境阻塞：20:15 起 POST /Insurance/Insuran 真实投保请求 Read timed out（30s），curl 探测服务在线但真实投保超时；17:02~17:57 曾成功出单。待保游恢复后补验，预期投保成功 → 档案 insurance_type=annual + 四件套回填。
oasdiff：not_configured，一期项目没有稳定 OAS3 导出与已配置工具，使用源码和 JSON 序列化测试回退。
Spring Cloud Contract：not_configured，使用生产者及消费者 reactor 测试回退。

4.8 KiB 原始文件 Blame 文件历史 Unescape Escape