docs: 27 旅客证件类型字典化 + idCardTypeLabel (PR #1459)

CRUD + OCR 链路全部下发 idCardTypeLabel 中文翻译.
顺手修 IdCardType 枚举 HK_MACAO→HK_MACAU 历史 BUG.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

changelogs/2026-04/27_feat_traveler_idcardtype-dict-and-label.md

@@ -0,0 +1,78 @@
+# 旅客证件类型字段字典化 + 中文 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="身份证"
+```