From fd76eea701d47d3062c61505366657ead4367e9f Mon Sep 17 00:00:00 2001 From: lc Date: Wed, 26 Aug 2026 15:29:13 +0800 Subject: [PATCH] =?UTF-8?q?docs(changelog):=20=E4=BA=A4=E4=BB=98=E8=A1=8C?= =?UTF-8?q?=E6=94=BF=E5=8C=BA=E5=88=92=20ID=20=E5=AD=97=E7=AC=A6=E4=B8=B2?= =?UTF-8?q?=E5=A5=91=E7=BA=A6=EF=BC=88#6409=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...区划响应ID固定为字符串-修改接口-管理后台.md | 64 +++++++++++++++++++ 1 file changed, 64 insertions(+) create mode 100644 changelogs-v2/2026-08/26_6409_行政区划响应ID固定为字符串-修改接口-管理后台.md diff --git a/changelogs-v2/2026-08/26_6409_行政区划响应ID固定为字符串-修改接口-管理后台.md b/changelogs-v2/2026-08/26_6409_行政区划响应ID固定为字符串-修改接口-管理后台.md new file mode 100644 index 00000000..98d34ff6 --- /dev/null +++ b/changelogs-v2/2026-08/26_6409_行政区划响应ID固定为字符串-修改接口-管理后台.md @@ -0,0 +1,64 @@ +--- +schema: "hl-changelog/v2" +ticket: "6409" +title: "行政区划响应 ID 固定为字符串" +consumer: "admin" +author: "lc(GIT)" +change_type: "修改接口" +backend_status: "deployed" +gateway_status: "verified" +frontend_status: "not_required" +frontend_owner: "" +frontend_ref: "" +target_release: "" +verified_at: "" +status_note: "PR #6412 已合并 dev-v3；hl-user-service 已以提交 4b31612a 部署 TEST，create、children、path 经真实 Gateway 验证全部 Long ID 固定为 JSON string，空层级保持 null。" +updated_at: "2026-08-26" +base: "dev-v3" +--- + +# 行政区划响应 ID 固定为字符串 + +行政区划创建、单级联动和父链回显接口中的 Long ID 现在始终按 JSON 字符串返回，避免小整数因全局安全整数规则被输出为 JSON number。请求参数、权限、业务校验和错误码不变。 + +## 变更接口 + +| 方法 | 路径 | 响应变化 | +|---|---|---| +| POST | `/admin/region` | 成功响应 `data` 从 JSON number 固定为 string | +| GET | `/admin/region/children` | `parentId`、`defaultId`、`items[].id`、`items[].parentId` 固定为 string；空值保持 `null` | +| GET | `/admin/region/{id}/path` | `selectedId`、`provinceId`、`prefectureId`、`countyId` 及 `path` 节点 ID 固定为 string；缺失层级保持 `null` | + +更新接口 `PUT /admin/region/{id}` 的请求和响应不变。所有请求路径、Query/Path 参数仍按原 Long 语义解析。 + +## 兼容性与错误语义 + +- 这是已发布接口 JSON 类型的契约修正，不新增字段，也不改变字段名称。 +- 行政区划 Redis 缓存可同时反序列化旧 JSON number 与新 JSON string，滚动部署期间兼容。 +- 根层 `parentId`、无默认节点的 `defaultId` 和父链中不存在的层级继续返回 `null`，不会变成字符串 `"null"`。 +- 未认证请求继续返回业务码 `401`；非法正整数参数、缺失节点和非法节点类型继续使用既有错误语义，失败路径零业务写入。 +- 无数据库 migration、配置、Gateway、MQ、缓存键或跨服务契约变更；无需修改前端源码，调用方按既定字符串 ID 契约消费即可。 +- 统一响应可能以 HTTP 200 承载业务失败，客户端必须同时检查 `code`、`success`、`message` 和 `data`。 + +## TEST 验证证据 + +- PR #6412 合并提交为 `8494028aa2dfbb4e39147c09695898d247045d4c`；TEST 目标提交 `4b31612aeba5c0d3ac690cc6af15b66290bd8b48` 包含该合并提交。 +- Deploy Panel API 任务 `b10dd2ed` 成功执行 `/opt/hulalv/scripts/deploy-backend.sh`；User 的 8081、8181 双实例和 Nacos 两个 healthy/enabled 实例通过，任务期 9 个可验证采样均有可用实例，0 个故障采样。 +- 真实 TEST 管理员经 Gateway 验证 create、children、path：创建 ID、联动列表 ID、父链 ID 和对应 Redis 缓存 ID 均为字符串，根节点和缺失层级空值保持 `null`。 +- 未认证请求返回 `401`；非法父节点、缺失节点、空创建和旧非法节点类型均按既有错误返回，并确认失败路径零写入。 +- 成功创建和 CAS 更新后，精确删除本次创建的 1 行；数据库总量恢复且测试命名空间为 0。4 个相关 Redis key 按基线值及绝对过期时间恢复，验收会话已注销；操作审计按系统约定保留。 +- 本地验证：Controller/Cache 定向 22 项通过；User 全量 3644 项通过、0 失败、0 错误，8 项条件跳过；`hl-verify` 与 `git diff --check` 通过。 + +## 撤回 + +1. 从最新 `dev-v3` 创建独立回退分支，执行 `git revert -m 1 --no-edit 8494028aa2dfbb4e39147c09695898d247045d4c`，经评审 PR 合入；不要回退后续无关提交。 +2. 通过 Deploy Panel API 对回退目标执行新鲜预检和显式部署 `hl-user-service`，复核双实例、Nacos、日志和精确提交。 +3. 本修复无数据库、配置或 MQ 变更，不执行 DDL、DML 或消息补偿。缓存新旧表示均可读取，通常无需清理；确需强制恢复旧表示时，仅在停止行政区划刷新后精确处理 `hl:user:region:v1:` 命名空间并由回退版本预热。 +4. 撤回前确认调用方可重新接受 JSON number ID；撤回后经 Gateway 复测 create、children、path、空层级、未认证和失败零写入。 + +## 关联 / 联系人 + +- **Issue**: [#6409](https://git.1814.love:8443/wx/HL/issues/6409) +- **PR**: [#6412](https://git.1814.love:8443/wx/HL/pulls/6412) +- **合并提交**: [8494028aa](https://git.1814.love:8443/wx/HL/commit/8494028aa2dfbb4e39147c09695898d247045d4c) +- **后端负责人**: @lc