hl-api-changelog/changelogs-v2/2026-06/11_3699_司机一键批量续签换季-新增接口-管理后台.md

【新增接口·管理后台】司机档案——车管一键批量续签(换季)

服务:hl-fleet-service(8087) | 分支:dev-v3 | PR:#3699 | 已部署测试服并实测通过(2026-06-11) 契约出处:FLEET API §3.7 | 前端触发位:司机档案列表页「批量续签」按钮(换季时用)

⚠️ 关键说明

1. 一键换季动作:把指定司机(或全部在册 season=active 司机)批量转入续签流程——active → pending + 为每人生成续签 H5 邀请链接/二维码。链接需车管手动转发给司机(本期无自动推送)。
2. 非在册司机不报错:pending/archived/blacklist 的司机自动跳过,进 skipped[] 给原因,不中断整批。
3. renewSeasonLabel 必填但不落库,仅入审计日志;remark 同理。
4. 防双击:同参数 3 秒内重复提交返「批量续签处理中,请勿重复提交」。

1. 新增端点

POST /admin/fleet/drivers/batch-season-renew

入参(body)

字段	类型	必填	说明
driverIds	string[]	否	目标司机ID列表(雪花字符串);缺省/空数组 = 对全部 season=active 司机全量换季;含不存在的 ID 整批报 100001
renewSeasonLabel	string	是	续签目标赛季标识(如 2027);缺失返 400
remark	string	否	批量动作备注(入审计日志)

请求示例

curl -k -X POST "https://api.test.1814.love:9443/admin/fleet/drivers/batch-season-renew" \
  -H "Authorization: Bearer {token}" -H "Content-Type: application/json" \
  -d '{"driverIds":["2065002428792492033"],"renewSeasonLabel":"2027","remark":"2027 赛季换季"}'

响应示例(测试服实测)

{
  "code": 200,
  "message": "成功",
  "data": {
    "matchedCount": 1,
    "transitionedCount": 1,
    "inviteGeneratedCount": 1,
    "invites": [
      {
        "driverId": "2065002428792492033",
        "driverName": "张师傅",
        "token": "e4dc8e393bc54224aeb97a346611cb58",
        "url": "https://h5.hl-fleet.com/onboard?token=e4dc8e393bc54224aeb97a346611cb58",
        "qrCodeUrl": "data:image/png;base64,iVBORw0KGgo...",
        "expireAt": "2026-06-25T17:25:20"
      }
    ],
    "skipped": []
  }
}

出参字段	说明
matchedCount	匹配司机数
transitionedCount	成功转入续签(active→pending)数
inviteGeneratedCount	生成续签邀请数(同事务恒等于 transitionedCount)
invites[]	「待发列表」:driverId/driverName/token/url(H5 链接,?token= 参数)/qrCodeUrl(二维码 Base64 DataURL,前端可直接 img src 渲染)/expireAt(14 天有效)
skipped[]	跳过明细:driverId + reason(如 season=pending≠active（非在册，跳过）)

非 active 司机被跳过(实测)

{ "matchedCount": 1, "transitionedCount": 0, "inviteGeneratedCount": 0, "invites": [],
  "skipped": [ { "driverId": "2065002428792492033", "reason": "season=pending≠active（非在册，跳过）" } ] }

2. 错误码

code	触发场景
400	renewSeasonLabel 缺失/空白(平台参数校验统一口径)
100001	driverIds 含不存在的司机 ID(消息列出缺失 ID,整批不执行)

3. 联动效果(前端无需额外调用)

• 司机列表 §3.1 的 season 变 pending、pendingInvitedAt 有值(卡片可显示「续签链接已发送·{日期}」);
• 每位司机自动生成一条 mode=renew 的待审核记录(司机打开链接走 §4 续签 3 步流程,与单个生成链接 §4.1 完全同机制)。