hl-api-changelog/changelogs-v2/2026-06/21_车管证件到期看板-board-expiry接口上线-纯查询聚合-管理后台.md

【接口新增·管理后台】车管「证件到期看板」上线（GET /admin/fleet/board/expiry）

服务：hl-fleet-service ｜ 分支：dev-v3 ｜ PR：#4160 ｜ 工单：#4159 已部署测试服 + 9443 真 token API 实测全通过（基础调用 + kinds/buckets/keyword 筛选 + counts 全量不随筛选变，含真实数据，2026-06-21）

⚠️ 关键说明

1. 用途：车管控制台「证件到期 / 到期提醒中心」聚合页（原型 page_expiry）数据源——一次查询聚合四类证件到期，按剩余天数分桶，供 KPI 卡 + 列表渲染。纯查询、零写、无业务错误码。
2. 路径 GET /admin/fleet/board/expiry，需 admin 登录（网关 /admin/fleet/** 已覆盖，无新增路由）。
3. 四类到期 kind：inspect（车辆年检）/ vehInsure（车辆保险）/ license（司机驾照）/ driverInsure（司机年度保险，仅年保司机有）。
4. 司机赛季 gate：司机两类（license / driverInsure）仅纳入在岗司机（season=active/pending），已离队 / 黑名单司机排除；车辆两类无此限制（软删车自然排除）。

1. 入参（query · 均可选）

参数	类型	说明
kinds	string[]	类型多选 inspect/vehInsure/license/driverInsure，任一命中即返；空=四类全返
buckets	string[]	桶多选 expired/urgent/soon/watch/ok，任一命中即返；空=全部桶。建议默认取 expired+urgent+soon+watch（不含 ok），需正常项再传 ok
keyword	string	模糊搜车牌 / 司机姓名（匹配 title 或 sub，大小写不敏感）

多选参数传法：?kinds=license&kinds=driverInsure 或 ?buckets=expired&buckets=urgent。

2. 出参

• data.counts：各桶计数 {expired, urgent, soon, watch, ok, total}，全量·不随 kinds/buckets/keyword 筛选变化（供 KPI 卡固定展示，total=各桶之和=四类到期项总数）。
• data.list：筛选后明细数组，排序固定=桶优先级 expired→urgent→soon→watch→ok 升序、组内 daysLeft 升序（最紧急 / 过期最久在最前）。无数据 counts 全 0、list 返空数组。

list 项字段：

字段	说明
id	列表 key，{targetId}::{kind}（如 蒙A-20221::vehInsure）
kind	到期类型（见上 4 值）
target	实体域：vehicle / driver
targetId	车=车牌 plate / 司机=driverId
title	车=车牌 / 司机=姓名
sub	车=车型 · 车队；司机驾照=脱敏手机 · 准驾车型 驾照；司机年险=脱敏手机 · ¥年保费/年（手机脱敏）
expiryField	到期字段名（inspect_due / insure_due / license_expire / insurance_annual_end）
expiryDate	到期日 YYYY-MM-DD
daysLeft	剩余天数（负=已过期 N 天）
bucket	所属桶（见下分桶口径）

3. 分桶口径

daysLeft = 到期日 − 今天：expired(<0 已过期) / urgent(0-30) / soon(31-60) / watch(61-90) / ok(>90)。颜色 / 桶标签由前端渲染，后端只给 bucket + daysLeft。

4. 真实请求 / 响应（测试服实测节选）

curl -k "https://api.test.1814.love:9443/admin/fleet/board/expiry" \
  -H "Authorization: Bearer <admin token>"

{
  "code": 200,
  "message": "成功",
  "data": {
    "counts": {"expired": 3, "urgent": 4, "soon": 1, "watch": 1, "ok": 48, "total": 57},
    "list": [
      {"id":"2067084362829979650::license","kind":"license","target":"driver",
       "targetId":"2067084362829979650","title":"王信","sub":"185****2756 · C1 驾照",
       "expiryField":"license_expire","expiryDate":"2022-02-05","daysLeft":-1597,"bucket":"expired"},
      {"id":"2065272148229865473::driverInsure","kind":"driverInsure","target":"driver",
       "targetId":"2065272148229865473","title":"恩克","sub":"135****5010 · ¥2/年",
       "expiryField":"insurance_annual_end","expiryDate":"2026-06-20","daysLeft":-1,"bucket":"expired"}
    ]
  }
}

筛选示例（counts 恒为全量 57，仅 list 变化）：

# 仅驾照类
curl -k ".../admin/fleet/board/expiry?kinds=license" -H "Authorization: Bearer <token>"
# 仅已过期桶（list=3，=counts.expired）
curl -k ".../admin/fleet/board/expiry?buckets=expired" -H "Authorization: Bearer <token>"
# 关键词搜司机姓名（中文需 URL 编码）
curl -k ".../admin/fleet/board/expiry?keyword=%E7%8E%8B" -H "Authorization: Bearer <token>"

前端动作（车管控制台）

1. 「证件到期 / 到期提醒中心」页对接本接口：KPI 卡读 data.counts（5 桶固定计数），列表读 data.list（已排好序，前端按 bucket 上色即可）。
2. 顶部筛选：类型多选传 kinds、紧急度多选传 buckets、搜索框传 keyword；counts 是全量固定值不随筛选变，别用 list 长度反推 KPI。
3. 列表项颜色 / 「已过期 N 天」「N 天后到期」文案前端按 bucket + daysLeft 渲染。