hl-api-changelog/changelogs-v2/2026-06/11_3678_司机档案PII脱敏与字段补齐导入修复-修改接口-管理后台.md

【修改·管理后台】司机档案:详情脱敏修复、列表新增 7 字段(含赛季计数)、编辑不再必传手机/身份证、批量导入大修(CSV/警告档/局部更新)

存放目录: changelogs-v2/2026-06/ 涉及服务: hl-fleet-service(8087) PR: #3678(已合并 dev-v3,测试服已部署并 API 实测 12 项通过) | 无关联工单 | 日期: 2026-06-11 影响范围: 管理后台司机档案页面(/admin/fleet/drivers/* 6 端点)

⚠️ 关键说明(前端必看 5 点)

1. 详情两处脱敏变化(原来泄明文):license.no(驾照号)与 emergency.phone(紧急联系人手机)现在返回脱敏值(150***********1234/138****9902)。编辑回显直接回传脱敏值即可——后端识别含 * 自动跳过更新保持原值;要真改就传新明文。
2. 编辑接口不用再传 phone/idCard 了(原来 @NotBlank 必填,但前端只有脱敏值,按文档流程必 400):现在编辑可整体省略这两个字段(创建仍必填);传了也会被忽略(创建后不可改,口径不变)。
3. relatedOrders 不再返回假数据:原来吐 3 条硬编码 mock 订单,现在恒返 [] + 新字段 relatedOrdersReady: false——请按 flag 显示「派单模块上线后展示关联订单」占位文案,别再把旧假数据当真渲染。
4. 列表新增 7 个字段/参数:出参 +residentVehiclePlate(权威常驻车,反查车侧)/activeYears(在册年份数组)/pendingInvitedAt/blacklistReason/顶层 seasonCounts(赛季 4 值全局计数,不随筛选变化,5 个 Tab 徽章直接用);入参 +licenseExpireBefore/insuranceAnnualEndBefore 两个到期被动筛。详情同步 +residentVehiclePlate/genderLabel/blacklistReason,且 activeYearsJson(字符串)改名改型为 activeYears(数字数组)。
5. keyword 语义修正:姓名模糊 + 手机仅支持 11 位全号精确(手机是加密列不支持模糊;原文档写「手机模糊」不准确)。

1. 校验行为变化

场景	行为
season 赛季	不再自由可写:按转移白名单校验(在册→待续签/拉黑、待续签→在册/归档、归档→在册),非法跳转返 100001;黑名单→在册(解封)编辑端点直接拦截(走专用解封流程)
insurance.type=annual	policyNo/annualPremium/annualStart/annualEnd 任一缺失返 100001(消息列明缺哪个);none 不限;perTrip 的保险计划选择待保险侧基础设施(暂仍走 perDayRate 手填)
insurance.company	字段已移除(出入参都不再有保险公司字段,明细以保险单附件为准;perDayRate 保留)
附件 mimeType	新增附件必填且白名单 jpeg/png/webp/pdf(违例 601005);编辑保留项(带 id)可省略
参数错误码	文档原写 400001 的场景实际均为 100001(平台 INVALID_PARAM),文档已订正

2. 批量导入(POST /admin/fleet/drivers/import)

• CSV 真支持(原来上传 .csv 直接 500);解析失败/不支持的后缀统一返 100001(原来静默返回「成功 0 行」);
• 更新已有司机(续签)= 15 个导入列的局部更新,空白列保持原值——原来会把该司机附件全软删、标签清空、年保起止清空(已修复,放心重导);
• 新增警告档:出参 +warnedCount/warnings[{row,name,field,msg}](驾照距到期不足 60 天仍导入但提醒);
• 注意:导入新增 保险类型=annual 的司机会因缺保单子字段进 errors(模板无保单列),annual 新司机请走表单录入。

实测响应示例:

{ "code": 200, "data": { "totalRows": 1, "insertedCount": 1, "renewedCount": 0, "errorCount": 0, "errors": [],
  "warnedCount": 1, "warnings": [ { "row": 2, "name": "导入测试乙", "field": "licenseExpire", "msg": "驾照不足 60 天" } ] }, "message": "成功" }

3. 联动行为(无需前端动作)

• 软删司机自动解绑其常驻车:该司机若是某车常驻司机,删除后车辆的 primaryDriverId 自动清空(测试服实测生效);
• 编辑出参为 { "kept", "inserted", "softDeleted", "tagsReplaced" }(文档原写 attachmentKept 等为误,已按代码订正)。

4. 文档

FLEET API → v1.5.54(§3 全节契约订正 + §14.4 错误码注册表 600205 错位修正),文档站:https://web.test.1814.love:9443/hl-docs/order-v3/api/API-SPEC-FLEET-V1.5.html