fix(changelog): 补齐行政区划三级联动接口文档与模板门禁（#6422） #78

2026-08-26T16:24:05+08:00

lc 评论于

2026-08-26 16:24:05 +08:00

协作者

背景

#6350 行政区划主数据与三级联动已经部署 TEST，但主 Changelog 没有严格按 CHANGELOG_TEMPLATE.md 做到每个接口自含完整联调契约。

关联追踪：wx/HL#6422（Refs wx/HL#6422）。

改动

按模板重写 #6350 主 Changelog，完整覆盖 GET children、GET path、POST create、PUT update。
每个接口补齐使用场景、入参、出参、完整请求/响应、空数据或降级、错误响应及业务边界。
补齐三级联动/编辑回显顺序、全部 VO 字段、210801–210819 错误码、枚举、影响评估和 TEST 证据。
强化 check:frontmatter：接口清单与详情一一对应；接口小节缺失模板块、写接口缺数据库行为、修改/删除缺对比/影响时失败。
同步模板、贡献规则、后端推送指南与 pre-push 提示。

API / 错误码影响

NONE。本 PR 只修改 hl-api-changelog 文档、校验器和测试，不修改或部署 HL 后端/前端源码，不新增或改变接口与错误码。

验证

npm test：52/52 通过。
npm run check:filenames -- --base origin/main --head HEAD：通过。
npm run check:frontmatter -- --base origin/main --head HEAD：1 个变更 Changelog 通过。
npm run check:path-aliases：通过。
git diff --check origin/main...HEAD：通过。
源码契约核对：4 个 METHOD/path、5 个 VO 的全部字段、210801–210819 全部可在文档中定位。
回归复现：旧 main 版本返回 E_API_TEMPLATE；新版返回 0 错误。

TEST 与清理

本 PR 无后端制品变化，TEST 重部署和业务数据清理不适用。#6350 既有精确提交 b62054035a139e3c689179ef75e2d052d08dde52 的 Gateway、数据库、Redis 和会话清理证据保持有效。

风险

接口类存量文件今后一旦修改，也必须升级到当前模板标准；这是本工单要求的有意收紧。仓库当前 CI 是 detector，是否作为服务端 required check 仍取决于 main 分支保护配置。

撤回

从最新 hl-api-changelog/main 创建回退分支，revert 本 PR 合并提交并经独立 PR 合入，随后复跑 52 项测试和 filename/frontmatter/path-alias 检查。无需回退数据库、配置、Redis、MQ、Gateway 或任何后端制品；撤回后前端暂以当前 Controller/VO 契约为准，直至重新提交通过模板门禁的自包含文档。

## 背景 #6350 行政区划主数据与三级联动已经部署 TEST，但主 Changelog 没有严格按 `CHANGELOG_TEMPLATE.md` 做到每个接口自含完整联调契约。关联追踪：[wx/HL#6422](https://git.1814.love:8443/wx/HL/issues/6422)（Refs wx/HL#6422）。 ## 改动 - 按模板重写 #6350 主 Changelog，完整覆盖 GET children、GET path、POST create、PUT update。 - 每个接口补齐使用场景、入参、出参、完整请求/响应、空数据或降级、错误响应及业务边界。 - 补齐三级联动/编辑回显顺序、全部 VO 字段、210801–210819 错误码、枚举、影响评估和 TEST 证据。 - 强化 `check:frontmatter`：接口清单与详情一一对应；接口小节缺失模板块、写接口缺数据库行为、修改/删除缺对比/影响时失败。 - 同步模板、贡献规则、后端推送指南与 pre-push 提示。 ## API / 错误码影响 `NONE`。本 PR 只修改 `hl-api-changelog` 文档、校验器和测试，不修改或部署 HL 后端/前端源码，不新增或改变接口与错误码。 ## 验证 - `npm test`：52/52 通过。 - `npm run check:filenames -- --base origin/main --head HEAD`：通过。 - `npm run check:frontmatter -- --base origin/main --head HEAD`：1 个变更 Changelog 通过。 - `npm run check:path-aliases`：通过。 - `git diff --check origin/main...HEAD`：通过。 - 源码契约核对：4 个 METHOD/path、5 个 VO 的全部字段、210801–210819 全部可在文档中定位。 - 回归复现：旧 main 版本返回 `E_API_TEMPLATE`；新版返回 0 错误。 ## TEST 与清理本 PR 无后端制品变化，TEST 重部署和业务数据清理不适用。#6350 既有精确提交 `b62054035a139e3c689179ef75e2d052d08dde52` 的 Gateway、数据库、Redis 和会话清理证据保持有效。 ## 风险接口类存量文件今后一旦修改，也必须升级到当前模板标准；这是本工单要求的有意收紧。仓库当前 CI 是 detector，是否作为服务端 required check 仍取决于 main 分支保护配置。 ## 撤回从最新 `hl-api-changelog/main` 创建回退分支，revert 本 PR 合并提交并经独立 PR 合入，随后复跑 52 项测试和 filename/frontmatter/path-alias 检查。无需回退数据库、配置、Redis、MQ、Gateway 或任何后端制品；撤回后前端暂以当前 Controller/VO 契约为准，直至重新提交通过模板门禁的自包含文档。

lc 于 2026-08-26 16:24:05 +08:00 推送 1 个提交

补齐行政区划三级联动接口文档与模板门禁（#6422）

changelog-filename-gate / validate (pull_request) Successful in 2s

详情

3d6f6245a0

lc 于 2026-08-26 16:24:50 +08:00 合并提交 49f8b6d0a0 到 main

lc 于

2026-08-26 16:24:51 +08:00

在代码提交中引用该工单

Merge pull request 'fix(changelog): 补齐行政区划三级联动接口文档与模板门禁（#6422）' (#78) from fix/6422-region-changelog-contract into main

登录并参与到对话中。

1 名参与者

通知

截止日期

未设置截止日期。

依赖工单

未设置依赖工单。

引用：wx/hl-api-changelog#78