docs(changelog): 出行人证件类型新增 idTypeName 中文字段 (#3962 #3970)

管理后台 3 接口出参新增 idTypeName（字典 id_card_type 优先、IdCardType 枚举兜底）： - GET /v3/admin/order/{id}/traveler/list - POST /v3/admin/order/{id}/traveler/add - GET /v3/admin/order/{id} 的 overview.customerInfo.travelers[]
2026-06-18 14:14:19 +08:00 · 2026-06-18 14:14:19 +08:00 · 8a0d38493f
--- a/changelogs-v2/2026-06/18_3962_出行人证件类型加idTypeName-修改接口-管理后台.md
+++ b/changelogs-v2/2026-06/18_3962_出行人证件类型加idTypeName-修改接口-管理后台.md
@ -0,0 +1,266 @@
+# 【修改接口·管理后台】✨ 出行人证件类型中文名 idTypeName 新增字段 (#3962)
+
+> **PR**: #3966 + #3971 | **服务**: hl-order-service-v3 | **更新时间**: 2026-06-18
+
+## 1. 接口背景
+
+出行人列表、添加出行人、订单详情概览等接口原先只返回 `idType` 英文枚举值（ID_CARD / PASSPORT / BIRTH_CERT / HK_MACAU / TAIWAN / MILITARY），前端需自行维护映射表才能展示中文。本次新增 `idTypeName` 字段，由后端查数据字典 `id_card_type` 派生中文名后直接下发，前端可零配置展示证件类型标签。原 `idType` 字段保留不变，属纯新增、非破坏性变更。
+
+> 本次治理与上周 #3951（出行人类型 travelerTypeName）完全同构：新建 `IdCardType` 枚举替换后端硬编码，中文名走数据字典 + 枚举兜底。
+
+## 2. 变更清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 订单出行人列表 | GET | /v3/admin/order/{id}/traveler/list | 新增出参字段 | 每个出行人元素新增 `idTypeName` |
+| 2 | 添加出行人 | POST | /v3/admin/order/{id}/traveler/add | 新增出参字段 | 返回的 TravelerVO 新增 `idTypeName` |
+| 3 | 订单详情 | GET | /v3/admin/order/{id} | 新增出参字段 | overview.customerInfo.travelers[] 元素新增 `idTypeName` |
+
+## 3. 接口详情
+
+### 3.1 订单出行人列表
+
+- **使用场景**：订单详情页「出行人」Tab 加载出行人清单时调用。
+- **认证**：需要 JWT（管理员角色）。
+- **幂等性**：是（只读）。
+- **限流**：无。
+
+入参无变化。出参 `List<TravelerVO>` 每个元素新增 `idTypeName` 字段（String）。该 VO 证件号 `idCardMasked` 等为脱敏值。
+
+### 3.2 添加出行人
+
+- **使用场景**：在订单详情页为订单添加一位出行人后，接口直接返回包含完整信息的 TravelerVO。
+- **认证**：需要 JWT（管理员角色）。
+- **幂等性**：否（写入操作）。
+- **限流**：无。
+
+入参无变化。出参 `TravelerVO` 新增 `idTypeName` 字段（String）。
+
+### 3.3 订单详情
+
+- **使用场景**：订单详情页首次加载概览 Tab，获取订单全量信息（含出行人）。
+- **认证**：需要 JWT（管理员角色）。
+- **幂等性**：是（只读）。
+- **限流**：无。
+
+入参无变化。出参 `overview.customerInfo.travelers[]` 数组中每个 `TravelerPlainVO` 元素新增 `idTypeName` 字段（String）。该 VO 证件号 `idCard` 为明文（#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 出参元素）
+
+| 字段 | 类型 | 变更 | 说明 |
+|------|------|------|------|
+| id | String | 不变 | 出行人记录 ID |
+| orderId | String | 不变 | 所属订单 ID |
+| travelerType | String | 不变 | 出行人类型枚举值 |
+| travelerTypeName | String | 不变 | 出行人类型中文名（#3951 已加） |
+| name | String | 不变 | 出行人姓名（占位行为 null） |
+| idType | String | 不变 | 证件类型枚举值，见 §6 |
+| idTypeName | String | **新增** | 证件类型中文名，由数据字典 `id_card_type` 派生 |
+| idCardMasked | String | 不变 | 证件号（脱敏后值） |
+| gender | String | 不变 | 性别字典码（1=男/2=女/0=未知） |
+| nationality | String | 不变 | 国籍 |
+
+### 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 业务例外，前端自行脱敏展示） |
+
+## 6. 枚举 / 数据字典
+
+### 6.1 idType（数据字典：id_card_type）
+
+**所属字段**：`idType`（出参，保留不变）与 `idTypeName`（出参，新增中文名） | **类型**：`String`
+
+| 枚举值 | 中文名（idTypeName） | 说明 |
+|--------|--------------------|------|
+| `ID_CARD` | 身份证 | 中国居民身份证 |
+| `PASSPORT` | 护照 | 中外护照 |
+| `BIRTH_CERT` | 出生证明 | 婴幼儿出生医学证明 |
+| `HK_MACAU` | 港澳通行证 | 港澳居民来往内地通行证 |
+| `TAIWAN` | 台胞证 | 台湾居民来往大陆通行证 |
+| `MILITARY` | 军官证 | 军人证件 |
+
+> 字典降级说明：若数据字典 `id_card_type` 中对应 key 缺失，后端使用 `IdCardType` 枚举内置 label 兜底（即上表中文名）；若证件类型值不在枚举范围内（未知值），`idTypeName` 返回 null。前端对该字段做 null 保护即可。
+
+## 7. 错误码
+
+本次为纯新增字段，无新增错误码。原有错误码不变。
+
+| code | 含义 | 触发场景 |
+|------|------|----------|
+| 581201 | 订单不存在 | orderId 无效 |
+| 401 | 未认证 | 未携带或 JWT 过期 |
+| 403 | 无权限 | 当前角色无此操作权限 |
+
+## 8. 示例（3 组：典型 / 边界 / 异常）
+
+### 8.1 典型成功 — 查询出行人列表（含新字段）
+
+请求：
+```
+GET /v3/admin/order/2067178767255560193/traveler/list
+Authorization: Bearer <token>
+```
+
+响应：
+```json
+{
+  "code": 200,
+  "data": [
+    {
+      "id": "2067178767255560201",
+      "orderId": "2067178767255560193",
+      "travelerType": "ADULT",
+      "travelerTypeName": "成人",
+      "name": "张*明",
+      "idType": "ID_CARD",
+      "idTypeName": "身份证",
+      "idCardMasked": "110***********1234",
+      "gender": "1",
+      "nationality": "中国"
+    }
+  ],
+  "message": "ok",
+  "success": true
+}
+```
+
+### 8.2 边界情况 — 订单详情概览出行人（多证件类型，含护照/出生证明）
+
+请求：
+```
+GET /v3/admin/order/2067178767255560194
+Authorization: Bearer <token>
+```
+
+响应（节选 overview.customerInfo.travelers）：
+```json
+{
+  "code": 200,
+  "data": {
+    "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"
+          }
+        ]
+      }
+    }
+  },
+  "message": "ok",
+  "success": true
+}
+```
+
+### 8.3 异常 — 字典未维护 + 未知证件类型（idTypeName 返回 null）
+
+若某出行人 `idType` 为枚举外的未知值（如历史脏数据 `DRIVER_LICENSE`）且字典未配，`idTypeName` 返回 null：
+```json
+{
+  "code": 200,
+  "data": [
+    {
+      "id": "2067178767255560221",
+      "travelerType": "ADULT",
+      "name": "王*",
+      "idType": "DRIVER_LICENSE",
+      "idTypeName": null
+    }
+  ],
+  "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`，两者语义等价。
+
+## 10. 修改前后对比
+
+### 10.1 字段级对比
+
+| VO | 字段 | 改前 | 改后 |
+|----|------|------|------|
+| TravelerVO | idTypeName | 不存在 | **新增** String，证件类型中文名 |
+| TravelerPlainVO | idTypeName | 不存在 | **新增** String，证件类型中文名 |
+| TravelerVO / TravelerPlainVO | idType | 原样返回英文枚举值 | 保留不变 |
+
+### 10.2 行为级对比
+
+| 行为 | 改前 | 改后 |
+|------|------|------|
+| 证件类型中文展示 | 前端自行维护 ID_CARD→身份证 等映射表 | 后端直接下发 idTypeName，前端可直接渲染 |
+| 数据字典缺失 | 无此逻辑 | 降级用枚举内置 label 兜底（六种），前端无感知 |
+
+## 11. 影响评估 / 回滚
+
+### 11.1 影响评估
+
+- **是否破坏向后兼容**：**否**，纯新增字段，原字段不变、原结构不变。
+- **前端是否必须同步上线**：**否**，旧前端代码不读新字段也不会出错，可按需对接。
+
+### 11.2 回滚方案
+
+- **回滚方式**：revert PR #3971 + #3966 并重新部署 hl-order-service-v3，返回字段恢复为无 idTypeName 的旧结构。
+
+## 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）。
+
+## 13. 关联 / 联系人
+
+### 13.1 链接
+
+- **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)
+
+### 13.2 联系人
+
+- **后端负责人**: @yaosutu