docs(changelog-v2): 续签候选司机列表不渲染=前端bug(字段名id非driverId),后端/page已实测正常

changelogs-v2/2026-06/16_续签候选司机列表不渲染-前端bug-后端已实测正常.md

@@ -0,0 +1,37 @@
+# 【前端 BUG·后端已实测正常】司机自助录入·续签 tab「选择要续签的司机」列表不渲染（无工单）
+
+> 端：前端（mmg）| 涉及后端：hl-fleet-service `/admin/fleet/drivers/page`（无需改动，已实测正常）| 2026-06-16
+
+## 现象
+
+后台「车务管理 → 司机自助录入 → 2026 赛季续签」tab：顶部「选择要续签的司机 · 往年在册但 2026 未续签 **3 人**」计数正常，但下方候选司机**列表区空白**，无法选人 → 「续签专属链接」一直提示「请先从上方选择要续签的司机」。
+
+## 排查结论：后端正常，前端未渲染列表
+
+后端 `/admin/fleet/drivers/page?season=archived` 真 token 实测：
+
+```
+total=3, records=3, seasonCounts={"active":20,"pending":0,"archived":3,"blacklist":1}
+records 三条 archived 存活司机数据齐全（id / name / phone / season / driverStatus …）
+```
+
+- 「3 人」计数 = `seasonCounts.archived`（后端返回，正确）。
+- 候选列表 = `season=archived` 的 records（后端**也正确返回了 3 条**）。
+- 两者**同源同数**，后端无任何漏返。**列表空白是前端没把 records 渲染出来。**
+
+## ⚠️ 高度可疑根因：字段名 `id` 不是 `driverId`
+
+`/page` 返回的列表项**司机主键字段是 `id`**（雪花值序列化为字符串，如 `"2066363927016472577"`），**不是 `driverId`**。
+
+- 若续签候选面板按 `item.driverId` 取值 → 全 undefined → 列表项渲染失败 / key 缺失 / 选中后 `targetDriverId` 为空。
+- **请改用 `item.id`**：渲染列表用 `id`，选中某司机后生成续签链接调 `POST /admin/fleet/h5/tokens`（或 batch-season-renew）时 `targetDriverId = item.id`。
+
+完整列表项字段：`id / name / phone(脱敏) / idCard(脱敏) / gender / years / driverStatus / season / primaryVehiclePlate / residentVehiclePlate / licenseType / licenseExpire / totalOrders / avgRating / insuranceType / tags / activeYears / pendingInvitedAt / blacklistReason / createTime`。
+
+## 建议前端核对项
+
+1. 候选列表请求是否真发出（season=archived）、响应 records 是否被正确读取渲染。
+2. 列表项主键统一用 `id`（不是 `driverId`）。
+3. 顺带：另一项「已发送未回复 N 人」= `season=pending` 计数（当前环境为 0）。
+
+> 后端 `/page` 无需改动，本条纯前端渲染/字段映射问题。