From 378a1bb7035e2eeaaa049e41be28d91ec5702824 Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Mon, 27 Apr 2026 10:22:25 +0800 Subject: [PATCH] =?UTF-8?q?docs:=2027=20=E6=97=85=E5=AE=A2=E8=AF=81?= =?UTF-8?q?=E4=BB=B6=E7=B1=BB=E5=9E=8B=E5=AD=97=E5=85=B8=E5=8C=96=20+=20id?= =?UTF-8?q?CardTypeLabel=20(PR=20#1459)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit CRUD + OCR 链路全部下发 idCardTypeLabel 中文翻译. 顺手修 IdCardType 枚举 HK_MACAO→HK_MACAU 历史 BUG. Co-Authored-By: Claude Opus 4.7 (1M context) --- ...feat_traveler_idcardtype-dict-and-label.md | 78 +++++++++++++++++++ 1 file changed, 78 insertions(+) create mode 100644 changelogs/2026-04/27_feat_traveler_idcardtype-dict-and-label.md diff --git a/changelogs/2026-04/27_feat_traveler_idcardtype-dict-and-label.md b/changelogs/2026-04/27_feat_traveler_idcardtype-dict-and-label.md new file mode 100644 index 0000000..5acf589 --- /dev/null +++ b/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="身份证" +```