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

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