docs(changelog-v2): 性别字段编码统一-后端对接答复+资源人员性别注释修复(PR #3379)

changelogs-v2/2026-06/03_性别字段编码统一-后端对接答复+资源人员性别注释修复_PR3379.md

@@ -0,0 +1,90 @@
+# 「性别」字段编码统一——后端对接答复（含资源人员性别注释缺陷修复）
+
+- **端类型**：管理后台（跨多服务）
+- **变更类型**：对接口径答复 + 缺陷修复（接口结构不变，仅纠正契约注释与常量）
+- **日期**：2026-06-03
+- **来源**：前端《性别字段编码统一-后端对接需求.md》
+- **PR**：[#3379](https://git.1814.love:8443/wx/HL/pulls/3379)
+- **Commit**：[3c2af3a](https://git.1814.love:8443/wx/HL/commit/3c2af3ac8a75f7202d52527ee35f6a9d13c34b8e)
+- **后端负责人**：wx
+
+---
+
+## 关键说明（请前端先读）
+
+1. **最终统一口径已定**：全系统对内/对前端契约的「性别」统一走**数据字典 `gender` 编码**，即 **`'1'`=男 / `'2'`=女**（字符串），并新增/对齐**未知态**。前端按字典 label 展示即可，**不要再自己映射**。
+2. **本轮不强制前端立即全切**：全量统一是跨 5 服务 + 存量数据迁移的大改造，将另起独立工单分批推进。本篇先给你**确认口径 + 现状真相 + 后续路线**，并已先行修掉一个会导致性别错配的真实缺陷（资源人员）。
+3. **外部对接不受影响**：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'` 的大改造将分批进行，预计涉及：
+
+1. **order-v3 出行人**：现 `MALE/FEMALE/UNKNOWN` → `1/2/0`，需同步改 `TravelerService` 的 `GENDER_ENUMS` 校验集 + 出行人快照三层 VO + 存量数据迁移。
+2. **order-v2 出行人**：透传脏数据先做兼容读归一化，再规范写为 `1/2`；连带团队报告 `sex`、合同 `male/female`、保险的 adapter 收敛到出/入站。
+3. **车队司机**：中文 `男/女` → `1/2`，存量迁移。
+4. **数据字典**：`gender` 视需要补「未知」项（如 `'0'`=未知），供 `UNKNOWN` 态落地。
+
+> 每批改造会单独发 changelog，明确该模块切换窗口与是否需要前端同步发布。**在对应模块改造 changelog 发出前，请前端不要单方面改动该模块的性别提交值。**
+
+---
+
+## 5. 前端当前可执行动作（对应需求文档第四节）
+
+1. **可立即做**：按本篇口径建立 `src/constants/gender.js`，以**字典 `gender`（`'1'`=男 / `'2'`=女）** 为唯一事实源；资源人员性别按「1=男 / 2=女」解析（本轮已修正后端注释）。
+2. **暂不要动**：order v2/v3 出行人、车队司机、合同的提交值——等对应模块统一改造 changelog 发出后再按窗口切换。
+3. 团队报告 `sex`（`0/1`，对接 12301）属外部报文口径，统一改造时后端会在 BFF 层对前端暴露统一 `gender`，届时另行通知。