hl-api-changelog/changelogs-v2/2026-06/12_3741_司机性别字典化与校验行为变化-行为变更-管理后台与司机H5.md

【行为变更·管理后台+司机H5】司机性别字典化——硬编码删除,渲染/导入/校验全部跟随数据字典 gender

服务:hl-fleet-service(8087) | 分支:dev-v3 | PR:#3741 | 工单:#3734 已部署测试服并端到端实测通过(2026-06-12):字典加「3=其他」后 ≤60 秒,H5/保存接口即接受 gender=3;删值即恢复拒绝

⚠️ 关键说明

1. 性别的取值从代码写死改为数据字典驱动:后台「数据字典」里 gender 字典(当前 1=男/2=女/0=未知)增删改值后,车管模块的列表渲染、Excel 导入、保存校验在 60 秒内自动跟随,不再需要改代码发版。
2. 非法性别的报错形态变化(前端需留意):原来是参数校验 code=400「性别只能 0=未知/1=男/2=女」,现在是业务码 code=100001「参数非法: 性别编码非法,取值来自字典 gender「男」「女」「未知」,值=X」。hl-ui 若按 code=400 分支处理表单校验提示,请改为同时兼容 100001。
3. H5 提交 gender 传空串:原被 400 拒,现视为未填放行(与不传同效,后台落「未知」缺省)。
4. 字典里删掉一个已被司机使用的值后:详情/列表渲染兜底显示「未知」不报错;但编辑该司机时性别必须改为字典内现有值才能保存(否则 100001)。

1. 各场景行为对照

场景	旧	新
详情 genderLabel 渲染	代码写死 1男/2女/0未知	查字典实时渲染(测试服实测「男」),字典改标签 ≤60s 跟随
Excel 导入「性别」列	仅认 男/女/未知	认字典内任意 ACTIVE 标签(运营加值即放开),非法值仍行级报错
admin 保存 / H5 提交校验	@Pattern 写死 ^[012]$	查字典校验,字典加值后新值自动合法
字典服务(user-service)不可用	不依赖	自动退回内置 1男/2女/0未知 兜底,不报错不阻断(与旧行为完全一致)

2. 端到端实测记录(测试服)

字典加 3=其他(POST /admin/dict/data) → code 200
等 65s(fleet 侧 60s 字典快照过期)
H5 提交 gender=3 → code 200(新值生效)
删字典值 → 恢复后 gender=3 再次被拒 100001
gender=9(字典外) → 100001「取值来自字典 gender「男」「女」「未知」,值=9」

3. 后端内部变更(备查)

1. 删除 GenderDict 硬编码类;新增 GenderDictResolver(60s TTL 快照,Feign 失败退旧快照/内置兜底永不抛)。
2. fleet 第三个出向 Feign:GenderDictFeignClient → user GET /internal/dict/data?dictType=gender(2s/3s 短超时)。
3. DriverSaveReqVO/SubmitNewReqVO 的 gender @Pattern 删除,校验下沉 Service 层。