From f77b9740c398c0bbe4fc38ffdefac0846b997083 Mon Sep 17 00:00:00 2001
From: API Changelog Bot <changelog@hulalv.com>
Date: Tue, 16 Jun 2026 14:25:44 +0800
Subject: [PATCH] =?UTF-8?q?docs(changelog-v2):=20=E7=BB=AD=E7=AD=BE?=
 =?UTF-8?q?=E5=80=99=E9=80=89=E5=8F=B8=E6=9C=BA=E5=88=97=E8=A1=A8=E4=B8=8D?=
 =?UTF-8?q?=E6=B8=B2=E6=9F=93=3D=E5=89=8D=E7=AB=AFbug(=E5=AD=97=E6=AE=B5?=
 =?UTF-8?q?=E5=90=8Did=E9=9D=9EdriverId),=E5=90=8E=E7=AB=AF/page=E5=B7=B2?=
 =?UTF-8?q?=E5=AE=9E=E6=B5=8B=E6=AD=A3=E5=B8=B8?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...候选司机列表不渲染-前端bug-后端已实测正常.md | 37 +++++++++++++++++++
 1 file changed, 37 insertions(+)
 create mode 100644 changelogs-v2/2026-06/16_续签候选司机列表不渲染-前端bug-后端已实测正常.md

diff --git a/changelogs-v2/2026-06/16_续签候选司机列表不渲染-前端bug-后端已实测正常.md b/changelogs-v2/2026-06/16_续签候选司机列表不渲染-前端bug-后端已实测正常.md
new file mode 100644
index 0000000..82816d4
--- /dev/null
+++ b/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` 无需改动，本条纯前端渲染/字段映射问题。