docs(changelog): 司机待审核列表过滤+拉黑解封端点+全年保险下拉关联+保险下单页核实 (#3791/#3792/#3793)

changelogs-v2/2026-06/13_3791_待审核列表过滤未提交空壳和作废链接-行为变更-管理后台.md

@@ -0,0 +1,21 @@
+# 【行为变更·管理后台】司机待审核列表只回真正提交的记录——过滤未提交空壳 + 已作废链接
+
+> 服务:hl-fleet-service(8087/8187) | 分支:dev-v3 | PR:#3791 | 已部署测试服并 API 实测通过(2026-06-13)
+> 背景:wx 反馈「待审核页数据全空」——卡片姓名/身份证/提交时间/照片全空。根因=列表把「司机点了 H5 链接但还没填写提交」的占位空壳、以及已作废链接也捞进了审核队列。
+
+## ⚠️ 关键说明(前端动作)
+
+1. **`GET /admin/fleet/drivers/pending` 行为变更(无需改前端代码,数据自动变干净)**:列表现在只返回**真正提交过且链接未作废**的记录,与「我的链接」派生态 `SUBMITTED` 同口径。两条恒生效基线过滤:
+   - `submitted_at IS NOT NULL`——排除「生成链接但司机未填写提交」的占位空壳(生成链接那一刻就落了一行 pending+未提交的占位行)
+   - `void_status='NORMAL'`——排除已作废链接(作废与审核正交,死链不进审核队列)
+2. **现象解释**:测试服修复前待审核 tab 有 8 张全空卡片(全是未提交空壳),修复后为 0 条(当前确实没有真正提交待审的司机);已驳回 tab 从 6 条(含 1 条异常空壳)变 5 条真实记录。**待审核 tab 看起来"变空"是正确的**——空壳本就不该出现。
+3. **「申请详情页」后端已就绪**:审核详情端点 `GET /admin/fleet/drivers/pending/{pendingId}`(PR#3785 已落)返回证件原图 URL / 驾照正副页 / 紧急联系人 / 自带车实拍照 / 备注(PII 脱敏),不存在返 600402。**审核卡片的「查看详情」抽屉可以接这个端点**看全量明细。
+
+## 实测(测试服)
+
+修复前: 待审核 8 条全 submittedAt=null 空壳 / 全部状态 15 条含空壳。
+修复后: 待审核 0 条 / 全部状态 6 条(approved 1+rejected 5)全部 submittedAt 非空 / 已驳回 5 条真实记录(姓名+提交时间齐全)。
+
+## 影响面
+
+仅列表查询行为变更,approve/reject/详情端点不受影响;零接口签名变化、零 DDL、零路由。

changelogs-v2/2026-06/13_3792_司机拉黑解封独立端点-新增接口-管理后台.md

@@ -0,0 +1,30 @@
+# 【新增接口·管理后台】司机风控拉黑 + 解封两个独立端点——司机卡片可加「拉黑/解封」按钮
+
+> 服务:hl-fleet-service(8087/8187) | 分支:dev-v3 | PR:#3792 | 已部署测试服并 API 往返实测通过(2026-06-13)
+> 背景:wx 反馈「司机卡片没有拉黑按钮」。原先拉黑只能走通用编辑端点(PUT 设 season=blacklist),且全量 VO 前端不回传 attachments/tags 会误删、解封更是无任何端点。wx 拍板补独立端点。(车辆拉黑 wx 已撤回·看原型,本次只做司机)
+
+## ⚠️ 关键说明(前端动作)
+
+1. 🆕 **拉黑** `POST /admin/fleet/drivers/{driverId}/blacklist`
+   - 入参 body:`{"blacklistReason": "客诉原因..."}`(原因**可选**,≤256;不传后端落空串)
+   - 出参:`{"code":200,"message":"成功"}`
+   - 规则:active/pending/archived 司机均可拉黑;已是黑名单返 **600202**;司机不存在返 **600205**
+   - **司机卡片加「拉黑」按钮**(弹框让操作人填可选原因)调本端点。后端只定向写 season+拉黑原因+拉黑时间三列,**不碰附件/标签**(不再有误删风险)——比之前走编辑端点 PUT 的方案安全,请改用本端点。
+2. 🆕 **解封** `POST /admin/fleet/drivers/{driverId}/unban`
+   - 入参:无 body(仅路径参数)
+   - 出参:`{"code":200,"message":"成功"}`
+   - 规则:当前必须是黑名单(否则返 **600208**「司机当前不是黑名单状态,无需解封」);解封后 season 回 **active** + 清空拉黑原因/时间
+   - **黑名单 tab 的司机加「解封」按钮**调本端点。
+3. **拉黑/解封会联动车辆**:拉黑→该司机常驻个人车自动停用(service_status=DISABLED);解封→恢复 ACTIVE。
+
+## ⚠️ 已知缺口(知会)
+
+解封的「主管级权限」门禁**暂未加**(hl-fleet 当前无 RBAC 框架、hl-user 未配 fleet 角色),当前任何登录管理员都能解封,待 hl-user 配 supervisor 角色后接入。前端解封按钮可正常对接,权限收紧是后端后续动作。
+
+## 实测(测试服往返)
+
+拉黑(中文原因)→200+season=blacklist+原因落库 / 解封→200+season=active+原因清空 / 非黑名单再解封→600208 / 不存在司机→600205 / 重复拉黑→600202。
+
+## 影响面
+
+错误码新增 600208;网关 `/admin/fleet/**` 通配已覆盖;零 DDL。原 PR#3785 提到的「编辑端点 blacklistReason 入参」仍保留,但**拉黑按钮请改用本专用端点**(避免全量 VO 误删)。

changelogs-v2/2026-06/13_3793_全年保险保单号改下拉关联保游网保单-行为变更-管理后台.md

@@ -0,0 +1,23 @@
+# 【行为变更·管理后台】编辑司机·全年保险「保单号」从手填改为下拉关联该司机已出的保游网保单
+
+> 服务:hl-fleet-service(8087/8187) | 分支:dev-v3 | PR:#3793 | 已部署测试服(下拉数据源端点 200 实测可达,完整投保流待前端联调)(2026-06-13)
+> 背景:wx 反馈编辑司机弹窗「保险配置·全年保险」的保单号是手填输入框,应改为从该司机已出的保游网保单里下拉选择关联。wx 拍板:改下拉关联,保留手填兜底。
+
+## ⚠️ 关键说明(前端动作)
+
+1. **编辑弹窗「保单号」输入框 → 下拉/搜索选择器**:
+   - 下拉数据源 = `GET /admin/fleet/drivers/{driverId}/insurance/policies`(司机「我的保单」,已有端点);**仅 status=INSURED(已承保)/INSURING(在途出单中)可选**。
+   - 选中某保单后,把该保单的 `insuranceOrderId` 放进保存入参 `insurance.insuranceOrderId` 提交。
+   - 选中后**保单号/年保费/保障起止改为只读回显**(由后端按保单真值回填),前端不再手敲这四项。
+2. **保存入参 `DriverInsuranceVO.insuranceOrderId` 已放开**(原「入参忽略」):
+   - `insurance.type=annual` 且传 `insuranceOrderId` → 后端按司机维度反查该保单,回填保单号/保费/起止 + 落 `annualSource=baoyou` + 关联 `insurance_order_id`。
+   - 横向越权守卫:传入的保单不属于该司机 / 状态不可关联 → 返 **600209**「关联的保游网保单不存在、不属于该司机或状态不可关联」。前端正常从该司机下拉选不会触发。
+3. **手填路径保留兜底**(二选一,insuranceOrderId 优先):不传 `insuranceOrderId`、仅手填 `policyNo`+保费+起止时,仍走原手填路径(`annualSource=manual`,行为零变化),用于线下买的、保游网没有的保单。
+
+## 实测(测试服)
+
+下拉数据源端点 `/insurance/policies` code=200 可达;反查回填 + 600209 越权路径由单测覆盖(DriverServiceTest+4 / DriverAnnualPolicyLookupImplTest 5,fleet 全套 714 绿);完整「选保单→回填→保存」端到端需前端接入后联调。
+
+## 影响面
+
+错误码新增 600209;**零新增 Feign/DTO/order-v3 端点/Flyway/网关路由**(复用现有按司机查保单 Feign);后端架构用 driver 子域端口 + insurance 子域实现解环。

changelogs-v2/2026-06/13_前端核实_保险下单页产品下拉空与司机险混淆-后端正常无需改-管理后台.md

@@ -0,0 +1,18 @@
+# 【前端核实·管理后台】保险下单页「保险产品下拉空」是前端未加载——后端已返 10 个 ACTIVE 产品;此页与司机险是两套(同名异物)
+
+> 服务:hl-order-service-v3(保险模块) | 无 PR(后端核实,无需改) | 测试服 API 实测(2026-06-13)
+> 背景:wx 看「保险管理→保险订单→投保下单」弹窗,问「保险下单页面咋没改呢」,且产品下拉为空。经排查为两个独立认知点,后端无 bug。
+
+## ⚠️ 关键说明
+
+1. **「保险下单页面没改」= 同名异物混淆,此页本就不该跟着司机险改**:
+   - 这个「保险订单 / 投保下单」页走的是 **游客订单险**(order-v3 `AdminInsuranceController` `/v3/admin/insurance/purchase`,`PurchaseInsuranceRequest`,productId+planId 模型)。
+   - 而最近改的「司机险走保游网」(PR#3700:perTrip→insurancePlanId 必填、删 perDayRate 等)改的是 **fleet 司机档案页**的保险,是**另一套独立模型**。
+   - 两者「保险计划/insurancePlanId」**同名异物**(API 文档 v1.5.64 已做术语消歧)。所以投保下单页没跟着改是正确的。
+2. **「保险产品下拉空」是前端问题,后端正常**:
+   - 测试服实测 `GET /v3/admin/insurance/products/all` 返 **code=200 + 10 个 status=ACTIVE 产品**(如「山河令(太保山东新)」)。后端产品列表端点工作正常、有数据。
+   - 截图里下拉空,是**前端未加载/未渲染**该端点数据。请前端检查投保下单弹窗的产品下拉是否正确调 `/v3/admin/insurance/products/all`、计划下拉调 `/v3/admin/insurance/products/{productId}/plans`。
+
+## 结论
+
+投保下单页端点/契约/产品计划下拉数据源后端全部正常,**无需后端改动**。产品下拉空请前端排查数据加载。