From 46eb07b9722cfedbceeefb92ce345cd131210d04 Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Fri, 7 Aug 2026 16:12:19 +0800 Subject: [PATCH] =?UTF-8?q?docs(changelog):=20=E5=87=BA=E8=A1=8C=E4=BA=BA?= =?UTF-8?q?=E6=89=80=E5=B1=9E=E5=9C=B0=E5=90=8E=E7=AB=AF=E8=A7=A3=E6=9E=90?= =?UTF-8?q?=E8=BF=94=E5=9B=9EnativePlace=EF=BC=88#5642=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...地后端解析返回nativePlace-修改接口-管理后台.md | 69 +++++++++++++++++++ 1 file changed, 69 insertions(+) create mode 100644 changelogs-v2/2026-08/07_5642_出行人所属地后端解析返回nativePlace-修改接口-管理后台.md diff --git a/changelogs-v2/2026-08/07_5642_出行人所属地后端解析返回nativePlace-修改接口-管理后台.md b/changelogs-v2/2026-08/07_5642_出行人所属地后端解析返回nativePlace-修改接口-管理后台.md new file mode 100644 index 0000000..8f2f9a8 --- /dev/null +++ b/changelogs-v2/2026-08/07_5642_出行人所属地后端解析返回nativePlace-修改接口-管理后台.md @@ -0,0 +1,69 @@ +--- +schema: "hl-changelog/v2" +ticket: "5642" +title: "出行人所属地后端解析返回 nativePlace（身份证前6位→地区名）" +consumer: "admin" +author: "wx" +change_type: "修改接口" +backend_status: "deployed" +gateway_status: "verified" +frontend_status: "pending" +frontend_owner: "" +frontend_ref: "" +target_release: "" +verified_at: "" +status_note: "后端完成：PR #5650 合并 dev-v3（1e37a1d53）并部署 TEST；网关实测 150784→内蒙古呼伦贝尔市、469001→海南五指山市、110101→北京市，PASSPORT/已撤销历史码 nativePlace 为 null 不报错。" +updated_at: "2026-08-07" +base: "dev-v3" +generated: "2026-08-07T16:15:00+08:00" +--- + +# 出行人所属地后端解析返回 nativePlace（#5642） + +## 背景 + +出行人"所属地"此前由前端从身份证号前 6 位自行解析，显示乱码。改为后端解析返回。口径经协调台确认：按**权威 GB/T 2260**（现行版，省+地级粒度）解析——150784=内蒙古呼伦贝尔市（工单示例"赤峰"系笔误，1504xx 才是赤峰）；不新建 district 表，沿用 `IdCardParser` 静态码表模式（与 `idProvinceName` 同源）。 + +## 变更内容 + +`GET /v3/admin/order/{id}/traveler/list` 等 admin 出行人出参（`TravelerVO`，含 traveler list / 协同单 / 结算退回详情等所有 `toAdminVO` 路径）**新增 `nativePlace` 字段**： + +| 场景 | nativePlace | +|---|---| +| 大陆身份证，命中地级码 | 省短名+地市名，如 `150784…`→`内蒙古呼伦贝尔市`、`320101…`→`江苏南京市` | +| 直辖市（1101/1201/3101/5001/5002） | 市名，如 `110101…`→`北京市` | +| 省直辖县级（4190/4290/4690/6590） | 按 6 位精确映射，如 `469001…`→`海南五指山市`、`659001…`→`新疆石河子市` | +| 非身份证（PASSPORT 等） | `null` | +| 未命中（含已撤销历史码如 3712 莱芜） | `null`（不报错） | + +补充说明： + +- 解析基于解密后的明文 idNo（converter 层既有行为），仅 18 位结构 + 合法生日段才解析；数据源为现行 GB/T 2260 地级行政区码表，不含已撤销历史代码（历史码身份证所属地返回 null）。 +- 既有字段不受影响：`idCardMasked` 仍脱敏、`idProvinceCode/idProvinceName` 逻辑不变。 +- internal VO（明文 Feign 契约）未加该字段，admin 出参仅新增只读字段，无破坏性。 + +## 关联 / 联系人 + +- 工单：https://git.1814.love:8443/wx/HL/issues/5642 +- PR：https://git.1814.love:8443/wx/HL/pulls/5650 +- 后端：wx + +## 变更接口或验证证据 + +### 接口契约 + +- 接口路径/方法/请求体：不变。 +- 响应 `data[].nativePlace` 新增字段（string | null）：所属地（省+地级行政区名）；非身份证或未命中为 `null`。 + +### 验证证据 + +- 定向测试 274 全过：`IdCardParserTest#extractNativePlace_*`（地级码/省直辖县级/非法与未命中 3 例）、`TravelerConverterTest#toAdminVO_*nativePlace*`（2 例），覆盖 TravelerService/TravelerAdminController/OrderDetailService。 +- 全量 `mvn -pl hl-order-service-v3 -am verify`：7610 测试，7F/95E 全部位于 30 个基线已坏的 Mapper/集成 IT 类（Feign loadbalancer Bean 缺失、Flyway IT schema 校验等环境问题），git stash 基线复跑同类同败，无一涉及 traveler/idcard 影响面。 +- 部署 TEST 成功（hl-order-service-v3 双实例 8086/8186 UP）。 +- 网关验证 10/10 PASS（自建 HLTEST 订单 2085637067265449985）：150784→内蒙古呼伦贝尔市、469001→海南五指山市、110101→北京市、PASSPORT→null、371201→null 不报错；脱敏与省级字段回归通过。 + +## 前端/调用方动作 + +- 出行人"所属地"列**直接展示后端返回的 `nativePlace`**，**删除前端自行解析身份证前 6 位的逻辑**（当前乱码来源）。 +- `nativePlace` 为 `null` 时展示空（如 "-"），不要 fallback 到前端解析。 +- 适用接口：所有返回 `TravelerVO` 的 admin 接口（出行人列表等）。