wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 Actions 软件包 项目 版本发布 百科 动态
hl-api-changelog/changelogs-v2/2026-06/03_性别字段全系统统一为字典编码-破坏性硬切_PR3381.md

4.6 KiB
原始文件 Blame 文件历史

【破坏性·硬切】性别字段全系统统一为数据字典编码 1=男/2=女/0=未知

  • 端类型：管理后台 + 小程序（跨 5 服务）
  • 变更类型：⚠️ 破坏性契约变更（编码值改变，前端须同步切换）
  • 日期：2026-06-03
  • 来源：前端《性别字段编码统一-后端对接需求.md》
  • Issue：#3380
  • PR：#3381（资源人员先行 #3379）
  • 后端负责人：wx

⚠️ 关键说明（前端必读）

  1. 本篇取代 同日早些的《性别字段编码统一-后端对接答复》中「order v2/v3 出行人、司机、合同暂不要动」的分批建议——wx 决定一次性整体硬切，后端已全部改完并部署测试服。
  2. 最终统一口径：全系统对内/对前端/DB 一律 数据字典 gender 编码 String '1'=男 / '2'=女 / '0'=未知。前端建唯一事实源 gender.js 按此口径，展示走字典 label。
  3. 破坏点：原先返回 MALE/FEMALE/UNKNOWN（order-v3 出行人）、中文 男/女（司机）、male/female（合同入参）的接口，现在一律是 1/2/0。前端解析与提交值必须同步切换，否则性别显示/提交错乱。
  4. 数据字典已补 '0'=未知（dictValue=0, dictLabel=未知）。注：C 端 /dict/all 有缓存，新增项稍后随缓存刷新生效；/admin/dict/data/gender 已可见。

1. 各模块编码变化对照（前端按此切换）

模块 接口/字段 改前 改后（统一）
order-v3 出行人 gender（增/改/查/批量编辑/快照） MALE/FEMALE/UNKNOWN 1/2/0
order-v2 出行人 gender 混存(1/2/MALE/male) 1/2（后端已归一化收口）
合同创建入参 gender male/female 1/2（出站 12301 后端自动转中文「男/女」）
车队司机 gender（增/改/查/H5提交/导入） 中文 男/女 1/2（Excel 仍填中文，后端导入边界自动转码）
资源人员 gender 注释 0/1 错乱 1/2（#3379 已对齐，Integer 类型）
用户资料 gender MALE/FEMALE 1/2/0
小程序出行人 gender 已 1/2 1/2（不变，BFF 透传跟随 order-v3）
数据字典 gender dictValue 1/2 1/2 + 新增 0=未知

2. 第三方边界（前端无感，后端自动 adapter 转换）

以下转换在后端出/入站边界完成，前端统一只看到 1/2/0：

边界 后端转换
12301 合同/团队报告 对内 1/2 ↔ 报文 中文「男/女」/ sex 0男1女
保游保险 对内 1/2 → 保游 1男/0女
身份证解析 自动得 1/2（奇男偶女）
Excel 导入（司机） 中文「男/女」→ 1/2（前端导出模板提示填 1/2 或保持中文均可）
OCR 证件识别 各证件 中文/Male/Female → 1/2，无法识别 0

3. 前端动作清单

  1. 建 src/constants/gender.js：GENDER = { MALE:'1', FEMALE:'2', UNKNOWN:'0' }，GENDER_LABEL_MAP、GENDER_OPTIONS，以字典 gender 为唯一事实源。
  2. 移除各模块原有的本地 option/转换：尤其 ContractCreateDrawer.vue:260 那段 '1'/'2' → male/female 硬转整段删除，合同入参直接传 1/2。
  3. 团队报告 TeamReportTab.vue 的 sex 0/1：后端报文内部仍用 sex，但 admin 接口对前端暴露的出行人性别统一 gender 1/2，按 gender 展示。
  4. 司机 DriverEditModal.vue 性别下拉 value 由中文 男/女 改为 1/2。
  5. 身份证解析回填直接用 1/2（parseGenderFromIdCard 已是该口径）。

4. 验证 / 风险

  • 5 服务测试服已部署（双实例），4 个存量迁移脚本随启动跑通：order_traveler / insured_person（MALE/male→1, FEMALE/female→2）、fleet_driver(_pending)（男/女→1/2）、字典补 0。
  • 437 项单测全绿（order-v3 111 / order-v2 142 / fleet 33 / user 105 / mp 46）。
  • ⚠️ 存量数据迁移上正式环境由 wx 单独确认后执行（本篇仅测试服）。
  • ⚠️ 这是破坏性硬切，前后端需同一发布窗口上线；前端切换前测试服性别相关功能会短暂不一致，属预期。

5. 顺带修复

order-v2 保险被保人 gender 此前从不写入（InsuredPersonVO.gender 恒 null），本次补持久化，保险详情现可正确返回被保人性别。