73 lines
3.1 KiB
Markdown
73 lines
3.1 KiB
Markdown
# 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:*；三个查询别名登录即可（前端级联选择器高频调用）。
|
||
|
||
## 表特征
|
||
|
||
```text
|
||
树形双键：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 同理）
|
||
:::
|
||
|
||
## 双向编解码（包级共享函数）
|
||
|
||
```text
|
||
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 已接入：**存库用编码（四列），展示用名称**。
|
||
|
||
## 与用户模块的协作流
|
||
|
||
```text
|
||
写侧：前端名称串 → ResolveCityCodes → 四列编码入库
|
||
（user 表 province/city/district/street_code）
|
||
读侧：Detail/List → ResolveCityNames(编码) → 名称串还原
|
||
（city_info 为空时按编码回填）
|
||
```
|
||
|
||
## 管理建议
|
||
|
||
+ 区划数据以国家统计口径为准，导入前核对 area_code 唯一性
|
||
+ 业务代码消费区划一律走 getCityList 级联（勿全量拉取）
|
||
+ level 枚举新增档位（如街道/社区细分）需同步字典与前端级联深度
|