# 旅客证件类型字段字典化 + 中文 label 装配

**日期**: 2026-04-27
**PR**: #1459 (Closes #1458)
**影响端**: 小程序 mp + 管理端 admin

## 背景

旅客证件类型字段 `idCardType` 全链路统一走字典 `id_card_type`, 前端能直接拿到中文 `idCardTypeLabel` 翻译, 不再需要前端硬编码 enum.

字典 `id_card_type` 6 个 value (与之前一致):
- `ID_CARD` → 身份证
- `PASSPORT` → 护照
- `HK_MACAU_PASS` → 港澳通行证 ⚠️ 注意是 `MACAU` (字母 U), 不是历史误用的 `MACAO` (字母 O)
- `TAIWAN_PASS` → 台湾通行证
- `MILITARY_ID` → 军官证 (CRUD 支持, OCR 不支持)
- `OTHER` → 其他 (CRUD 支持, OCR 不支持)

## 接口变化

### 1. CRUD: `/mp/user/traveler` (列表/详情/新增/修改/删除/设默认)

**响应新增字段** (无侵入增量):

| 字段 | 类型 | 说明 |
|------|------|------|
| `idCardTypeLabel` | String | 证件类型中文标签 (如 "身份证" / "护照" / "港澳通行证") |

**入参校验加强**:
- `POST /mp/user/traveler` / `PUT /mp/user/traveler/{id}` 的 `idCardType` 字段:
  - 必须是字典 6 值之一 (ID_CARD/PASSPORT/HK_MACAU_PASS/TAIWAN_PASS/MILITARY_ID/OTHER)
  - 不命中返 `code=230203`, `message=证件类型无效` (`TRAVELER_ID_CARD_TYPE_INVALID`)
  - **null 或空字符串兜底为 `ID_CARD`** (DB 列默认值, 不直接 reject 防破坏存量小程序版本)

### 2. OCR: `POST /mp/traveler/ocr`

**入参白名单收紧**:
- `idCardType` 必须是 4 值之一: `ID_CARD` / `PASSPORT` / `HK_MACAU_PASS` / `TAIWAN_PASS`
- 传 `MILITARY_ID` 或 `OTHER` 直接返 `TRAVELER_OCR_CARD_TYPE_UNSUPPORTED` (军官证/其他暂不支持 OCR 识别, 需手动录入)
- 之前任何非空值都进入 switch 分流, 现在入口直接拒不支持类型

**响应新增字段**:

| 字段 | 类型 | 说明 |
|------|------|------|
| `idCardTypeLabel` | String | 证件类型中文标签 |

## 历史 BUG 修正 (顺手)

后端 `IdCardType` 枚举之前误写为 `HK_MACAO_PASS` (字母 O), 与字典 + DB 列 COMMENT 的 `HK_MACAU_PASS` (字母 U) 不一致, 任何 `IdCardType.of("HK_MACAU_PASS")` 历史会抛 IllegalArgumentException. 本 PR 统一为 `HK_MACAU_PASS`.

**前端注意**: 如果代码里有硬编码 `HK_MACAO_PASS` 字面量, 必须改成 `HK_MACAU_PASS`. 推荐前端今后用后端下发的 `idCardTypeLabel` 直接显示, 不再硬编码 value→中文 map.

## 前端建议改造

### 立即生效 (无需改动)
- 列表/详情页直接读 `idCardTypeLabel` 显示中文
- OCR 结果页直接读 `idCardTypeLabel` 显示

### 推荐清理
- 删除前端硬编码的 `idCardType` value → 中文 map
- 把 `HK_MACAO_PASS` 字面量全改为 `HK_MACAU_PASS` (字母 O→U)
- 表单证件类型下拉直接走 `/admin/dict/data?dictType=id_card_type` 拉取

## 兼容性

- mp Controller 返 Map 透传不动, `idCardTypeLabel` 通过 transient 字段自动序列化下发, 老版本前端不读这个字段也无影响
- DB 数据干净: 测试服 traveler 51 条 / order_traveler 47 条 / traveler_ocr_log 13 条, 全部 6 字典合法值, **0 条 `HK_MACAO_PASS` 旧拼写**
- null/空入参兜底 ID_CARD, 老版本小程序如果发空字段也不破坏

## 验证 (测试服, 部署后)

```
GET /mp/user/traveler             // 列表 response.list[].idCardTypeLabel 含中文
GET /mp/user/traveler/{id}        // 详情 idCardTypeLabel 含中文
POST /mp/traveler/ocr (idCardType=MILITARY_ID)   // 返 TRAVELER_OCR_CARD_TYPE_UNSUPPORTED
POST /mp/traveler/ocr (idCardType=ID_CARD)       // response 含 idCardTypeLabel="身份证"
```
