6.6 KiB
6.6 KiB
「性别」字段编码统一——后端对接答复（含资源人员性别注释缺陷修复）
- 端类型：管理后台（跨多服务）
- 变更类型：对接口径答复 + 缺陷修复（接口结构不变，仅纠正契约注释与常量）
- 日期：2026-06-03
- 来源：前端《性别字段编码统一-后端对接需求.md》
- PR：#3379
- Commit：3c2af3a
- 后端负责人：wx
关键说明（请前端先读）
- 最终统一口径已定：全系统对内/对前端契约的「性别」统一走数据字典
gender编码，即'1'=男 /'2'=女（字符串），并新增/对齐未知态。前端按字典 label 展示即可，不要再自己映射。 - 本轮不强制前端立即全切：全量统一是跨 5 服务 + 存量数据迁移的大改造，将另起独立工单分批推进。本篇先给你确认口径 + 现状真相 + 后续路线，并已先行修掉一个会导致性别错配的真实缺陷（资源人员）。
- 外部对接不受影响：12301 报文要中文「男/女」、保游保险要
0/1、身份证解析得1/2，这些都收敛在后端出/入站 adapter 内，不外泄到对前端契约。
1. 后端真实现状矩阵（实证，比你看到的更复杂）
| 模块 | 字段名 | 类型 | 后端真实编码 | 规范性 |
|---|---|---|---|---|
数据字典 gender |
— | — | '1'=男 / '2'=女（sys_dict_data，user-service 管理，C 端 GET /dict/all） |
标准锚点 |
| order-v2 出行人 | gender |
String | 透传混存：身份证反推写 1/2、mp 传 1/2、DB 注释却写 MALE/FEMALE、前端可能传 male/female |
最脏 |
| order-v2 团队报告 | sex |
Integer | 0=男 / 1=女（对接 12301 报文口径） |
独立 |
| order-v3 出行人 | gender |
String | MALE/FEMALE/UNKNOWN（有枚举校验） |
规范但口径不同 |
| 合同创建入参 | gender |
String | male/female（小写，不持久化，出站转 12301 中文「男/女」） |
独立 |
| 车队司机 | gender |
String | 中文 男/女（VARCHAR(4)） |
待统一 |
| 资源人员 | gender |
Integer | 入参强制 1=男 / 2=女（本轮修正注释，见第 3 节） |
本轮已对齐字典 |
mp MpTravelerRequest |
gender |
String | 1/2 |
— |
身份证解析 IdCardParser |
— | — | 1/2（奇男偶女） |
— |
| 保游保险 API | — | — | 0=女 / 1=男（外部约束） |
外部 |
2. 回答前端 4 个 Open Questions
| # | 你的问题 | 后端答复（事实） |
|---|---|---|
| 1 | 数据字典 gender 当前 code 到底是什么？ |
'1'=男 / '2'=女（sys_dict_data 实证，归 user-service）。既不是 0/1，也不是 MALE/FEMALE。这就是全系统将统一到的锚点。 |
| 2 | 各接口能否统一到同一字段名 + 编码？有无存量迁移成本？ | 对内/对前端契约能统一为字段名 gender、值 '1'/'2'；外部 12301/保游走 adapter。有存量迁移成本：order v2/v3 出行人、车队司机（中文）需归一化 + 历史数据回填，故分批做。 |
| 3 | 是否需要过渡期（后端同时接受新旧编码）？ | 需要。order-v2 出行人是历史脏数据，后端会先做「兼容读归一化 + 规范写」再切，统一改造期间后端将兼容旧编码入参，前端可分模块切换。 |
| 4 | 身份证解析得到的性别按哪套回填？ | 当前 IdCardParser 已返 1/2，正好就是字典口径，前端回填直接用 '1'/'2' 即可。 |
3. 本轮缺陷修复：资源人员性别注释/常量错配（PR #3379）
问题：资源人员 gender 实际运行值由入参校验 @Min(1)@Max(2) 强制为 1=男 / 2=女，服务层透传存储与返回；但接口契约注释写反了：
| 位置 | 修复前 | 修复后 |
|---|---|---|
StaffVO.gender（出参注释） |
0=女 1=男 ❌ |
1=男 2=女（对齐字典与实际） |
StaffConstants（死常量） |
GENDER_FEMALE=0 / GENDER_MALE=1 ❌ |
GENDER_MALE=1 / GENDER_FEMALE=2 |
前端影响：若你之前按 StaffVO 出参注释「0=女 1=男」解析资源人员性别，value=2（女性）会无法映射 → 丢失/错配。现注释已纠正，资源人员性别即「1=男 / 2=女」，与字典一致。
说明：本次为纯契约注释与常量纠正，零运行行为变更（返回值本就是 1/2，未变）。无需前端配合改提交值；仅请按「1=男 / 2=女」解析资源人员性别。
接口（结构不变）：
| 接口 | 方法 | 路径 | 说明 |
|---|---|---|---|
| 资源人员新增 | POST | /admin/staff |
gender 入参 1=男 / 2=女（一直如此，本次仅修注释） |
| 资源人员详情/列表 | GET | /admin/staff/** |
StaffVO.gender 返回 1=男 / 2=女 |
测试服已部署（双实例 health UP），无行为变化故无需 API 回归。
4. 后续统一改造路线（另起独立工单，前端先知悉）
统一到字典口径 '1'/'2' 的大改造将分批进行，预计涉及：
- order-v3 出行人：现
MALE/FEMALE/UNKNOWN→1/2/0，需同步改TravelerService的GENDER_ENUMS校验集 + 出行人快照三层 VO + 存量数据迁移。 - order-v2 出行人：透传脏数据先做兼容读归一化，再规范写为
1/2；连带团队报告sex、合同male/female、保险的 adapter 收敛到出/入站。 - 车队司机：中文
男/女→1/2，存量迁移。 - 数据字典：
gender视需要补「未知」项（如'0'=未知），供UNKNOWN态落地。
每批改造会单独发 changelog，明确该模块切换窗口与是否需要前端同步发布。在对应模块改造 changelog 发出前，请前端不要单方面改动该模块的性别提交值。
5. 前端当前可执行动作（对应需求文档第四节）
- 可立即做：按本篇口径建立
src/constants/gender.js，以字典gender（'1'=男 /'2'=女） 为唯一事实源；资源人员性别按「1=男 / 2=女」解析（本轮已修正后端注释）。 - 暂不要动：order v2/v3 出行人、车队司机、合同的提交值——等对应模块统一改造 changelog 发出后再按窗口切换。
- 团队报告
sex（0/1，对接 12301）属外部报文口径，统一改造时后端会在 BFF 层对前端暴露统一gender，届时另行通知。