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

【新增接口·管理后台】司机风控拉黑 + 解封两个独立端点——司机卡片可加「拉黑/解封」按钮

服务: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 误删)。