docs(changelog-v2): 性别字段全系统统一为字典编码破坏性硬切(PR #3381)

changelogs-v2/2026-06/03_性别字段全系统统一为字典编码-破坏性硬切_PR3381.md

@@ -0,0 +1,72 @@
+# 【破坏性·硬切】性别字段全系统统一为数据字典编码 1=男/2=女/0=未知
+
+- **端类型**：管理后台 + 小程序（跨 5 服务）
+- **变更类型**：⚠️ 破坏性契约变更（编码值改变，前端须同步切换）
+- **日期**：2026-06-03
+- **来源**：前端《性别字段编码统一-后端对接需求.md》
+- **Issue**：[#3380](https://git.1814.love:8443/wx/HL/issues/3380)
+- **PR**：[#3381](https://git.1814.love:8443/wx/HL/pulls/3381)（资源人员先行 [#3379](https://git.1814.love:8443/wx/HL/pulls/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），本次补持久化，保险详情现可正确返回被保人性别。