changelog: 司机档案对齐修复 PII脱敏/字段补齐/导入大修 (PR #3678)

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

@@ -0,0 +1,47 @@
+# 【修改·管理后台】司机档案:详情脱敏修复、列表新增 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 新司机请走表单录入。
+
+**实测响应示例**:
+
+```json
+{ "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