diff --git a/changelogs-v2/2026-06/18_3962_出行人证件类型加idTypeName-修改接口-管理后台.md b/changelogs-v2/2026-06/18_3962_出行人证件类型加idTypeName-修改接口-管理后台.md index be4d855..153e748 100644 --- a/changelogs-v2/2026-06/18_3962_出行人证件类型加idTypeName-修改接口-管理后台.md +++ b/changelogs-v2/2026-06/18_3962_出行人证件类型加idTypeName-修改接口-管理后台.md @@ -1,12 +1,13 @@ # 【修改接口·管理后台】✨ 出行人证件类型中文名 idTypeName 新增字段 (#3962) > **PR**: #3966 + #3971 | **服务**: hl-order-service-v3 | **更新时间**: 2026-06-18 +> 📌 2026-06-18 更正：证件类型**统一以数据字典 `id_card_type` 为唯一标准**（4 值），原稿误列的旧词表（BIRTH_CERT/HK_MACAU/TAIWAN/MILITARY）已废弃，请前端以本版为准。 ## 1. 接口背景 -出行人列表、添加出行人、订单详情概览等接口原先只返回 `idType` 英文枚举值（ID_CARD / PASSPORT / BIRTH_CERT / HK_MACAU / TAIWAN / MILITARY），前端需自行维护映射表才能展示中文。本次新增 `idTypeName` 字段，由后端查数据字典 `id_card_type` 派生中文名后直接下发，前端可零配置展示证件类型标签。原 `idType` 字段保留不变，属纯新增、非破坏性变更。 +出行人列表、添加出行人、订单详情概览等接口的 `idType`（证件类型）原先只返回英文码，前端需自行维护映射表才能展示中文。本次新增 `idTypeName` 字段，由后端查数据字典 `id_card_type` 派生中文名后直接下发，前端可零配置展示证件类型标签。原 `idType` 字段保留不变，属纯新增、非破坏性变更。 -> 本次治理与上周 #3951（出行人类型 travelerTypeName）完全同构：新建 `IdCardType` 枚举替换后端硬编码，中文名走数据字典 + 枚举兜底。 +> ⚠️ 证件类型取值**以数据字典 `id_card_type` 为唯一标准**，前端下拉/映射应**拉取字典**，不要硬编码值集。 ## 2. 变更清单 @@ -19,128 +20,99 @@ ## 3. 接口详情 ### 3.1 订单出行人列表 +- **使用场景**：订单详情页「出行人」Tab 加载出行人清单。 +- **认证**：JWT（管理员）。**幂等**：是（只读）。 -- **使用场景**：订单详情页「出行人」Tab 加载出行人清单时调用。 -- **认证**：需要 JWT（管理员角色）。 -- **幂等性**：是（只读）。 -- **限流**：无。 - -入参无变化。出参 `List` 每个元素新增 `idTypeName` 字段（String）。该 VO 证件号 `idCardMasked` 等为脱敏值。 +入参无变化。出参 `List` 每个元素新增 `idTypeName`（String）。该 VO 证件号为脱敏值。 ### 3.2 添加出行人 +- **使用场景**：为订单添加一位出行人后返回完整 TravelerVO。 +- **认证**：JWT（管理员）。**幂等**：否（写入）。 -- **使用场景**：在订单详情页为订单添加一位出行人后，接口直接返回包含完整信息的 TravelerVO。 -- **认证**：需要 JWT（管理员角色）。 -- **幂等性**：否（写入操作）。 -- **限流**：无。 - -入参无变化。出参 `TravelerVO` 新增 `idTypeName` 字段（String）。 +入参无变化。出参 `TravelerVO` 新增 `idTypeName`（String）。 ### 3.3 订单详情 +- **使用场景**：订单详情页概览 Tab 首次加载。 +- **认证**：JWT（管理员）。**幂等**：是（只读）。 -- **使用场景**：订单详情页首次加载概览 Tab，获取订单全量信息（含出行人）。 -- **认证**：需要 JWT（管理员角色）。 -- **幂等性**：是（只读）。 -- **限流**：无。 - -入参无变化。出参 `overview.customerInfo.travelers[]` 数组中每个 `TravelerPlainVO` 元素新增 `idTypeName` 字段（String）。该 VO 证件号 `idCard` 为明文（#3509 业务例外，前端自行脱敏展示）。 +入参无变化。出参 `overview.customerInfo.travelers[]` 每个 `TravelerPlainVO` 元素新增 `idTypeName`（String）。该 VO 证件号为明文（#3509 业务例外，前端自行脱敏展示）。 ## 4. 接口入参 -### 4.1 路径参数 / Query 参数 - | 接口 | 字段 | 类型 | 必填 | 说明 | |------|------|------|------|------| | GET /v3/admin/order/{id}/traveler/list | id | String（Long） | 是 | 路径参数，订单 ID | | POST /v3/admin/order/{id}/traveler/add | id | String（Long） | 是 | 路径参数，订单 ID | | GET /v3/admin/order/{id} | id | String（Long） | 是 | 路径参数，订单 ID | -### 4.2 请求体字段 - -三个接口入参均无变化。POST /v3/admin/order/{id}/traveler/add 的请求体字段与原契约相同，本次未改动。 +三个接口入参均无变化。 ## 5. 出参（响应） -### 5.1 TravelerVO 字段（接口 1、2 出参元素） +### 5.1 TravelerVO（接口 1、2） | 字段 | 类型 | 变更 | 说明 | |------|------|------|------| | id | String | 不变 | 出行人记录 ID | -| orderId | String | 不变 | 所属订单 ID | -| travelerType | String | 不变 | 出行人类型枚举值 | -| travelerTypeName | String | 不变 | 出行人类型中文名（#3951 已加） | -| name | String | 不变 | 出行人姓名（占位行为 null） | -| idType | String | 不变 | 证件类型枚举值，见 §6 | +| travelerType / travelerTypeName | String | 不变 | 出行人类型码 / 中文名 | +| name | String | 不变 | 姓名（占位行为 null） | +| idType | String | 不变 | 证件类型码，取值见数据字典 `id_card_type`，见 §6 | | idTypeName | String | **新增** | 证件类型中文名，由数据字典 `id_card_type` 派生 | -| idCardMasked | String | 不变 | 证件号（脱敏后值） | -| gender | String | 不变 | 性别字典码（1=男/2=女/0=未知） | -| nationality | String | 不变 | 国籍 | +| idCardMasked | String | 不变 | 证件号（脱敏）| -### 5.2 TravelerPlainVO 字段（接口 3 订单详情 overview.customerInfo.travelers[] 元素） +### 5.2 TravelerPlainVO（接口 3 详情 overview.customerInfo.travelers[]） | 字段 | 类型 | 变更 | 说明 | |------|------|------|------| -| id | String | 不变 | 出行人记录 ID | -| travelerType | String | 不变 | 出行人类型枚举值 | -| travelerTypeName | String | 不变 | 出行人类型中文名（#3951 已加） | -| name | String | 不变 | 出行人姓名（占位行为 null） | -| idType | String | 不变 | 证件类型枚举值，见 §6 | -| idTypeName | String | **新增** | 证件类型中文名，由数据字典 `id_card_type` 派生 | -| idCard | String | 不变 | 证件号（明文，#3509 业务例外，前端自行脱敏展示） | +| name | String | 不变 | 姓名 | +| idType | String | 不变 | 证件类型码，见 §6 | +| idTypeName | String | **新增** | 证件类型中文名，字典派生 | +| idCard | String | 不变 | 证件号（明文，#3509）| ## 6. 枚举 / 数据字典 -### 6.1 idType（数据字典：id_card_type） +### 6.1 idType（数据字典：id_card_type，唯一标准） -**所属字段**：`idType`（出参，保留不变）与 `idTypeName`（出参，新增中文名） | **类型**：`String` +**所属字段**：`idType`（出参）与 `idTypeName`（出参，新增中文名） | **类型**：`String` -| 枚举值 | 中文名（idTypeName） | 说明 | -|--------|--------------------|------| -| `ID_CARD` | 身份证 | 中国居民身份证 | -| `PASSPORT` | 护照 | 中外护照 | -| `BIRTH_CERT` | 出生证明 | 婴幼儿出生医学证明 | -| `HK_MACAU` | 港澳通行证 | 港澳居民来往内地通行证 | -| `TAIWAN` | 台胞证 | 台湾居民来往大陆通行证 | -| `MILITARY` | 军官证 | 军人证件 | +数据字典 `id_card_type` 当前 **4 个标准值**（运维在 sys_dict 维护，以字典为准）： -> 字典降级说明：若数据字典 `id_card_type` 中对应 key 缺失，后端使用 `IdCardType` 枚举内置 label 兜底（即上表中文名）；若证件类型值不在枚举范围内（未知值），`idTypeName` 返回 null。前端对该字段做 null 保护即可。 +| 字典值（idType） | 中文名（idTypeName） | +|------|------| +| `ID_CARD` | 身份证 | +| `PASSPORT` | 护照 | +| `HONGKONG_RESIDENT_PASS` | 回乡证 | +| `TAIWAN_PASS` | 台胞证 | + +> - **前端下拉/映射请拉取字典 `id_card_type`，不要硬编码上表**（字典可能调整）。 +> - **婴幼儿**：已落户婴幼儿有公民身份号码，证件类型用 `ID_CARD`（身份证）+ 填身份证号即可（字典无单独的"出生证明"项）。 +> - `idTypeName` 派生规则：字典命中→返回中文；字典未配该值→**返回 idType 原值码**（非 null）。故前端遇到非中文值即说明该 idType 不在字典标准内。 ## 7. 错误码 -本次为纯新增字段，无新增错误码。原有错误码不变。 +纯新增字段，无新增错误码。 -| code | 含义 | 触发场景 | -|------|------|----------| -| 581201 | 订单不存在 | orderId 无效 | -| 401 | 未认证 | 未携带或 JWT 过期 | -| 403 | 无权限 | 当前角色无此操作权限 | +| code | 含义 | +|------|------| +| 581201 | 订单不存在 | +| 401 / 403 | 未认证 / 无权限 | -## 8. 示例（3 组：典型 / 边界 / 异常） +## 8. 示例（3 组） -### 8.1 典型成功 — 查询出行人列表（含新字段） +### 8.1 典型 — 出行人列表（含新字段） -请求： -``` -GET /v3/admin/order/2067178767255560193/traveler/list -Authorization: Bearer -``` - -响应： ```json { "code": 200, "data": [ { "id": "2067178767255560201", - "orderId": "2067178767255560193", "travelerType": "ADULT", "travelerTypeName": "成人", "name": "张*明", "idType": "ID_CARD", "idTypeName": "身份证", - "idCardMasked": "110***********1234", - "gender": "1", - "nationality": "中国" + "idCardMasked": "110***********1234" } ], "message": "ok", @@ -148,15 +120,8 @@ Authorization: Bearer } ``` -### 8.2 边界情况 — 订单详情概览出行人（多证件类型，含护照/出生证明） +### 8.2 边界 — 订单详情概览（护照 + 回乡证 + 婴幼儿身份证） -请求： -``` -GET /v3/admin/order/2067178767255560194 -Authorization: Bearer -``` - -响应（节选 overview.customerInfo.travelers）： ```json { "code": 200, @@ -164,94 +129,56 @@ Authorization: Bearer "overview": { "customerInfo": { "travelers": [ - { - "id": "2067178767255560211", - "travelerType": "ADULT", - "travelerTypeName": "成人", - "name": "李强", - "idType": "PASSPORT", - "idTypeName": "护照", - "idCard": "E12345678" - }, - { - "id": "2067178767255560212", - "travelerType": "BABY", - "travelerTypeName": "幼童", - "name": "李小宝", - "idType": "BIRTH_CERT", - "idTypeName": "出生证明", - "idCard": "P110101202401011234" - } + { "travelerType": "ADULT", "travelerTypeName": "成人", "name": "李强", "idType": "PASSPORT", "idTypeName": "护照", "idCard": "E12345678" }, + { "travelerType": "ADULT", "travelerTypeName": "成人", "name": "王芳", "idType": "HONGKONG_RESIDENT_PASS", "idTypeName": "回乡证", "idCard": "H1234567" }, + { "travelerType": "BABY", "travelerTypeName": "幼童", "name": "李小宝", "idType": "ID_CARD", "idTypeName": "身份证", "idCard": "110101202401011234" } ] } } }, - "message": "ok", "success": true } ``` -### 8.3 异常 — 字典未维护 + 未知证件类型（idTypeName 返回 null） +### 8.3 异常 — idType 不在字典标准内（idTypeName 返回原值码） + +若某出行人 `idType` 为字典外的非标准值（如历史脏数据 `BIRTH_CERT`），字典查不到 → `idTypeName` **返回原值码**（不是中文、也不是 null），前端可据此识别脏数据： -若某出行人 `idType` 为枚举外的未知值（如历史脏数据 `DRIVER_LICENSE`）且字典未配，`idTypeName` 返回 null： ```json { "code": 200, "data": [ - { - "id": "2067178767255560221", - "travelerType": "ADULT", - "name": "王*", - "idType": "DRIVER_LICENSE", - "idTypeName": null - } + { "name": "某某", "idType": "BIRTH_CERT", "idTypeName": "BIRTH_CERT" } ], - "message": "ok", "success": true } ``` ## 9. 业务边界 -- 适用：订单处于任何状态均可查询出行人（只读接口）。 -- 适用：证件类型覆盖 ID_CARD / PASSPORT / BIRTH_CERT / HK_MACAU / TAIWAN / MILITARY 六种，每种均有对应中文名。 -- 特殊边界：数据字典 `id_card_type` 缺失某枚举值时，`idTypeName` 降级返回枚举内置中文名（六种均有兜底，不会 null）。 -- 特殊边界：`idType` 为枚举外未知值（脏数据）时，`idTypeName` 返回 null，前端需做 null 保护。 -- 特殊边界：`idType` 原字段值不变，前端若已有本地映射逻辑，可继续保留或切换为直接展示 `idTypeName`，两者语义等价。 +- 证件类型取值以数据字典 `id_card_type` 为唯一标准（当前 4 值）；新增/调整证件类型由运维改字典，前端拉字典即时生效。 +- `idType` 原字段值不变，前端可继续保留本地逻辑或切换为直接展示 `idTypeName`。 +- `idTypeName` 仅在 `idType` 命中字典时为中文；字典外值返回原值码（提示该数据非标准）。 +- 婴幼儿用 `ID_CARD`（身份证号）。 ## 10. 修改前后对比 -### 10.1 字段级对比 - | VO | 字段 | 改前 | 改后 | |----|------|------|------| -| TravelerVO | idTypeName | 不存在 | **新增** String，证件类型中文名 | -| TravelerPlainVO | idTypeName | 不存在 | **新增** String，证件类型中文名 | -| TravelerVO / TravelerPlainVO | idType | 原样返回英文枚举值 | 保留不变 | - -### 10.2 行为级对比 - -| 行为 | 改前 | 改后 | -|------|------|------| -| 证件类型中文展示 | 前端自行维护 ID_CARD→身份证 等映射表 | 后端直接下发 idTypeName，前端可直接渲染 | -| 数据字典缺失 | 无此逻辑 | 降级用枚举内置 label 兜底（六种），前端无感知 | +| TravelerVO / TravelerPlainVO | idTypeName | 不存在 | **新增** String，证件类型中文名（字典派生）| +| TravelerVO / TravelerPlainVO | idType | 原样返回字典码 | 保留不变 | ## 11. 影响评估 / 回滚 -### 11.1 影响评估 - -- **是否破坏向后兼容**：**否**，纯新增字段，原字段不变、原结构不变。 -- **前端是否必须同步上线**：**否**，旧前端代码不读新字段也不会出错，可按需对接。 - -### 11.2 回滚方案 - -- **回滚方式**：revert PR #3971 + #3966 并重新部署 hl-order-service-v3，返回字段恢复为无 idTypeName 的旧结构。 +- **破坏向后兼容**：否，纯新增字段。 +- **前端必须同步**：否，可按需对接；建议证件类型下拉改为拉字典 `id_card_type`。 +- **回滚**：revert PR #3971 + #3966 重新部署 hl-order-service-v3。 ## 12. 注意事项 -- 前端 workaround 清理点：若前端已有本地 `idType → 中文` 映射对象/函数，上线后可切换为直接读取 `idTypeName`，原映射逻辑可清理。 -- `idTypeName` 由后端数据字典 `id_card_type` 派生，字典修改后立即生效（无需前端发版），当前兜底口径为：ID_CARD=身份证 / PASSPORT=护照 / BIRTH_CERT=出生证明 / HK_MACAU=港澳通行证 / TAIWAN=台胞证 / MILITARY=军官证。 -- 本次为两个 PR 合并交付：#3966（TravelerVO，接口 1/2）+ #3971（TravelerPlainVO，接口 3）。 +- 前端证件类型下拉/映射**统一拉数据字典 `id_card_type`，不要硬编码值集**（字典当前 4 值：身份证/护照/回乡证/台胞证）。 +- 若前端已有本地 `idType→中文` 映射，可清理改用 `idTypeName`。 +- 婴幼儿证件类型用身份证（`ID_CARD`）+ 身份证号。 ## 13. 关联 / 联系人 @@ -259,7 +186,7 @@ Authorization: Bearer - **Issue**: [#3962](https://git.1814.love:8443/wx/HL/issues/3962)（主治理）、[#3970](https://git.1814.love:8443/wx/HL/issues/3970)（概览补遗） - **PR**: [#3966](https://git.1814.love:8443/wx/HL/pulls/3966)、[#3971](https://git.1814.love:8443/wx/HL/pulls/3971) -- **Merge commit**: [f04c3223a](https://git.1814.love:8443/wx/HL/commit/f04c3223a)、[d6eb1176a](https://git.1814.love:8443/wx/HL/commit/d6eb1176a) +- **后续治理**: 证件类型统一以字典为准（移除发散词表）、注释对齐字典（#4012） ### 13.2 联系人