From 0176a17de75055efa84bf2bea4c9c713b86e9ba3 Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Wed, 3 Jun 2026 13:57:34 +0800 Subject: [PATCH] =?UTF-8?q?docs(changelog-v2):=20=E6=80=A7=E5=88=AB?= =?UTF-8?q?=E5=AD=97=E6=AE=B5=E5=85=A8=E7=B3=BB=E7=BB=9F=E7=BB=9F=E4=B8=80?= =?UTF-8?q?=E4=B8=BA=E5=AD=97=E5=85=B8=E7=BC=96=E7=A0=81=E7=A0=B4=E5=9D=8F?= =?UTF-8?q?=E6=80=A7=E7=A1=AC=E5=88=87(PR=20#3381)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...段全系统统一为字典编码-破坏性硬切_PR3381.md | 72 +++++++++++++++++++ 1 file changed, 72 insertions(+) create mode 100644 changelogs-v2/2026-06/03_性别字段全系统统一为字典编码-破坏性硬切_PR3381.md diff --git a/changelogs-v2/2026-06/03_性别字段全系统统一为字典编码-破坏性硬切_PR3381.md b/changelogs-v2/2026-06/03_性别字段全系统统一为字典编码-破坏性硬切_PR3381.md new file mode 100644 index 0000000..38c317d --- /dev/null +++ b/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），本次补持久化，保险详情现可正确返回被保人性别。