# 【修改接口·管理后台】✨ 出行人证件类型中文名 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`（证件类型）原先只返回英文码，前端需自行维护映射表才能展示中文。本次新增 `idTypeName` 字段，由后端查数据字典 `id_card_type` 派生中文名后直接下发，前端可零配置展示证件类型标签。原 `idType` 字段保留不变，属纯新增、非破坏性变更。

> ⚠️ 证件类型取值**以数据字典 `id_card_type` 为唯一标准**，前端下拉/映射应**拉取字典**，不要硬编码值集。

## 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 证件号为脱敏值。

### 3.2 添加出行人
- **使用场景**：为订单添加一位出行人后返回完整 TravelerVO。
- **认证**：JWT（管理员）。**幂等**：否（写入）。

入参无变化。出参 `TravelerVO` 新增 `idTypeName`（String）。

### 3.3 订单详情
- **使用场景**：订单详情页概览 Tab 首次加载。
- **认证**：JWT（管理员）。**幂等**：是（只读）。

入参无变化。出参 `overview.customerInfo.travelers[]` 每个 `TravelerPlainVO` 元素新增 `idTypeName`（String）。该 VO 证件号为明文（#3509 业务例外，前端自行脱敏展示）。

## 4. 接口入参

| 接口 | 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|------|
| 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 |

三个接口入参均无变化。

## 5. 出参（响应）

### 5.1 TravelerVO（接口 1、2）

| 字段 | 类型 | 变更 | 说明 |
|------|------|------|------|
| id | String | 不变 | 出行人记录 ID |
| travelerType / travelerTypeName | String | 不变 | 出行人类型码 / 中文名 |
| name | String | 不变 | 姓名（占位行为 null） |
| idType | String | 不变 | 证件类型码，取值见数据字典 `id_card_type`，见 §6 |
| idTypeName | String | **新增** | 证件类型中文名，由数据字典 `id_card_type` 派生 |
| idCardMasked | String | 不变 | 证件号（脱敏）|

### 5.2 TravelerPlainVO（接口 3 详情 overview.customerInfo.travelers[]）

| 字段 | 类型 | 变更 | 说明 |
|------|------|------|------|
| name | String | 不变 | 姓名 |
| idType | String | 不变 | 证件类型码，见 §6 |
| idTypeName | String | **新增** | 证件类型中文名，字典派生 |
| idCard | String | 不变 | 证件号（明文，#3509）|

## 6. 枚举 / 数据字典

### 6.1 idType（数据字典：id_card_type，唯一标准）

**所属字段**：`idType`（出参）与 `idTypeName`（出参，新增中文名） | **类型**：`String`

数据字典 `id_card_type` 当前 **4 个标准值**（运维在 sys_dict 维护，以字典为准）：

| 字典值（idType） | 中文名（idTypeName） |
|------|------|
| `ID_CARD` | 身份证 |
| `PASSPORT` | 护照 |
| `HONGKONG_RESIDENT_PASS` | 回乡证 |
| `TAIWAN_PASS` | 台胞证 |

> - **前端下拉/映射请拉取字典 `id_card_type`，不要硬编码上表**（字典可能调整）。
> - **婴幼儿**：已落户婴幼儿有公民身份号码，证件类型用 `ID_CARD`（身份证）+ 填身份证号即可（字典无单独的"出生证明"项）。
> - `idTypeName` 派生规则：字典命中→返回中文；字典未配该值→**返回 idType 原值码**（非 null）。故前端遇到非中文值即说明该 idType 不在字典标准内。

## 7. 错误码

纯新增字段，无新增错误码。

| code | 含义 |
|------|------|
| 581201 | 订单不存在 |
| 401 / 403 | 未认证 / 无权限 |

## 8. 示例（3 组）

### 8.1 典型 — 出行人列表（含新字段）

```json
{
  "code": 200,
  "data": [
    {
      "id": "2067178767255560201",
      "travelerType": "ADULT",
      "travelerTypeName": "成人",
      "name": "张*明",
      "idType": "ID_CARD",
      "idTypeName": "身份证",
      "idCardMasked": "110***********1234"
    }
  ],
  "message": "ok",
  "success": true
}
```

### 8.2 边界 — 订单详情概览（护照 + 回乡证 + 婴幼儿身份证）

```json
{
  "code": 200,
  "data": {
    "overview": {
      "customerInfo": {
        "travelers": [
          { "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" }
        ]
      }
    }
  },
  "success": true
}
```

### 8.3 异常 — idType 不在字典标准内（idTypeName 返回原值码）

若某出行人 `idType` 为字典外的非标准值（如历史脏数据 `BIRTH_CERT`），字典查不到 → `idTypeName` **返回原值码**（不是中文、也不是 null），前端可据此识别脏数据：

```json
{
  "code": 200,
  "data": [
    { "name": "某某", "idType": "BIRTH_CERT", "idTypeName": "BIRTH_CERT" }
  ],
  "success": true
}
```

## 9. 业务边界

- 证件类型取值以数据字典 `id_card_type` 为唯一标准（当前 4 值）；新增/调整证件类型由运维改字典，前端拉字典即时生效。
- `idType` 原字段值不变，前端可继续保留本地逻辑或切换为直接展示 `idTypeName`。
- `idTypeName` 仅在 `idType` 命中字典时为中文；字典外值返回原值码（提示该数据非标准）。
- 婴幼儿用 `ID_CARD`（身份证号）。

## 10. 修改前后对比

| VO | 字段 | 改前 | 改后 |
|----|------|------|------|
| TravelerVO / TravelerPlainVO | idTypeName | 不存在 | **新增** String，证件类型中文名（字典派生）|
| TravelerVO / TravelerPlainVO | idType | 原样返回字典码 | 保留不变 |

## 11. 影响评估 / 回滚

- **破坏向后兼容**：否，纯新增字段。
- **前端必须同步**：否，可按需对接；建议证件类型下拉改为拉字典 `id_card_type`。
- **回滚**：revert PR #3971 + #3966 重新部署 hl-order-service-v3。

## 12. 注意事项

- 前端证件类型下拉/映射**统一拉数据字典 `id_card_type`，不要硬编码值集**（字典当前 4 值：身份证/护照/回乡证/台胞证）。
- 若前端已有本地 `idType→中文` 映射，可清理改用 `idTypeName`。
- 婴幼儿证件类型用身份证（`ID_CARD`）+ 身份证号。

## 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)
- **后续治理**: 证件类型统一以字典为准（移除发散词表）、注释对齐字典（#4012）

### 13.2 联系人

- **后端负责人**: @yaosutu
