6.9 行政区划管理

:::tip 概述行政区划模块（goframe_city，平台级大表）管理全国省/市/区/街道/社区数据：树形双键（pid + parent_code）、级联懒加载查询、双向编解码包级函数（user/index 模块复用）。78 万+ 行，查询必须走索引路径。 :::

接口清单

方法	路由	权限	说明
GET	/api/city/page	sys:city:page	分页
GET	/api/city/list	sys:city:list	列表
GET	/api/city/detail/:id	sys:city:detail	详情
POST	/api/city/add	sys:city:add	新增
PUT	/api/city/update	sys:city:update	修改
DELETE	/api/city/delete/:id	sys:city:delete	软删
DELETE	/api/city/batchDelete	sys:city:batchDelete	批量删除
GET	/api/city/getCityList/:parentCode	登录即可	下级城市（级联懒加载）
GET	/api/area/getParent	登录即可	省份列表（别名路由）
GET	/api/area/findByParentCode	登录即可	按父编码查城市（别名）

七件套权限 sys:city:*；三个查询别名登录即可（前端级联选择器高频调用）。

表特征

树形双键：pid（父 ID）+ parent_code（父编码）——级联查询走 parent_code 索引
area_code   区划编码（唯一业务键，编解码主键）
level       0-省份 1-城市 2-县区 3-街道 4-社区（注释枚举）
lng/lat/pinyin   经纬度与拼音（检索辅助）
平台级表（无租户）：全国统一数据

大表性能纪律（78 万+ 行）

::: warning 大表注意

勿全表 List——查询走 area_code / parent_code / pid 索引路径
级联懒加载 getCityList/:parentCode 只取单级子集
导入/迁移注意批大小（与整库迁移器 batch-size 同理） :::

双向编解码（包级共享函数）

ResolveCityNames(ctx, codes []string, separator) string
  area_code IN(...) 批查 → 按入参顺序拼名称串（空编码跳过）
  用途：详情/列表把存储的四级编码还原为"江苏省,南京市,建邺区"

ResolveCityCodes(ctx, cityInfo string) [4]string
  名称串按逗号拆 4 级，逐级 parent 约束消歧：
    省：pid=0 AND name=?
    市：parent_code=省area_code AND name=?
    → 区 → 街道（逐级依赖上级结果；任一级失败后续留空）
  例："江苏省,南京市,建邺区" → [320000000000, 320100000000, 320105000000, ""]

因全部 logic 同包，user/index 直接调用无需 import。user 模块 Add/Update/Import/Detail 已接入：存库用编码（四列），展示用名称。

与用户模块的协作流

写侧：前端名称串 → ResolveCityCodes → 四列编码入库
      （user 表 province/city/district/street_code）
读侧：Detail/List → ResolveCityNames(编码) → 名称串还原
      （city_info 为空时按编码回填）

管理建议

区划数据以国家统计口径为准，导入前核对 area_code 唯一性
业务代码消费区划一律走 getCityList 级联（勿全量拉取）
level 枚举新增档位（如街道/社区细分）需同步字典与前端级联深度

3.1 KiB Raw Blame History Unescape Escape