签入版本

2026-10-25 17:24:27 +08:00
parent 48911cc08f
commit fdbeae092a
1010 changed files with 30682 additions and 95274 deletions
@@ -1,160 +1,29 @@
-# 6.9 行政区划管理
+# 6.15 行政区划管理

 :::tip 概述
-行政区划管理维护全国省市区街道四级数据，支持按父编码级联查询。继承 BaseLogic（系统共享，不隔离）。
+行政区划（gin_city）维护省市区三级数据，为地址选择、属地统计提供基础数据。树形结构 + 按父级取子级的级联查询。
 :::

-## 模块特点
+## 功能清单

-| 特性 | 说明 |
-|------|------|
-| 基类 | BaseLogic（系统共享，不隔离） |
-| 层级结构 | id/pid + parent_code 双重层级标识 |
-| 特殊接口 | getCityList 按父编码查询、getParent 获取省份列表 |
-| 详情钩子 | afterDetail 补全父级名称 |
+| 接口 | 说明 |
+|---|---|
+| Page / List / Detail | 标准查询 |
+| Add / Update / Delete / BatchDelete | 维护（平台级数据） |
+| ByParent | 按父级 ID 取下级（级联选择器数据源） |
+| GetCityList | 区划列表聚合 |
+| AreaProvince | 省份数据入口 |

-## 数据库表结构
+## 结构特点

-```sql
-CREATE TABLE `think_city` (
-  `id` int NOT NULL AUTO_INCREMENT COMMENT '主键ID',
-  `city_code` varchar(6) NOT NULL COMMENT '城市区号',
-  `area_code` varchar(20) NOT NULL COMMENT '行政编码',
-  `parent_code` varchar(20) DEFAULT NULL COMMENT '上级行政编码',
-  `zip_code` varchar(6) NOT NULL COMMENT '邮政编码',
-  `level` int DEFAULT 0 COMMENT '城市级别：0-省份 1-城市 2-县区 3-街道',
-  `pid` int DEFAULT 0 COMMENT '上级城市ID',
-  `name` varchar(150) NOT NULL COMMENT '城市名称',
-  `short_name` varchar(150) NOT NULL COMMENT '城市简称',
-  `full_name` varchar(150) DEFAULT NULL COMMENT '城市全称',
-  `pinyin` varchar(150) DEFAULT NULL COMMENT '城市拼音',
-  `lng` varchar(150) DEFAULT NULL COMMENT '城市经度',
-  `lat` varchar(150) DEFAULT NULL COMMENT '城市纬度',
-  `create_user` varchar(50) DEFAULT NULL COMMENT '创建人',
-  `create_time` datetime DEFAULT (now()) COMMENT '创建时间',
-  `update_user` varchar(50) DEFAULT NULL COMMENT '更新人',
-  `update_time` datetime DEFAULT (now()) COMMENT '更新时间',
-  `is_delete` int DEFAULT 0 COMMENT '删除标识：0-正常 1-已删除',
-  PRIMARY KEY (`id`)
-) COMMENT = '城市行政区划表';
-```
+- parent_id 三级树（省 → 市 → 区/县）
+- 平台级表（无租户隔离——区划是公共基础数据）
+- 前端配套 ChinaArea / Region 组件消费级联数据

-## API 接口
+## 管理界面

-| 方法 | 路径 | 权限码 | 说明 |
-|------|------|--------|------|
-| GET | `/api/city/list` | sys:city:page | 城市列表 |
-| 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 | 删除 |
-| GET | `/api/city/getCityList/:parentCode` | - | 按父编码获取子级城市 |
-| GET | `/api/city/getParent` | - | 获取省份列表（level=0） |
-| GET | `/api/city/findByParentCode/:parentCode` | - | 根据父编码查询子级城市 |
+`data/city`：树形表格 + 级联维护。

-## 核心代码
+## 相关

-```php
-// app/logic/CityLogic.php
-
-class CityLogic extends BaseLogic
-{
-    /**
-     * 关联的模型类
-     *
-     * @var string
-     */
-    protected string $modelClass = City::class;
-
-    /**
-     * LIKE 模糊匹配字段
-     *
-     * @var array
-     */
-    protected array $pageLikeFields = ['name', 'full_name', 'pinyin'];
-
-    /**
-     * 精确匹配字段
-     *
-     * @var array
-     */
-    protected array $pageEqFields = ['level', 'pid'];
-
-    /**
-     * 默认排序规则
-     *
-     * @var array
-     */
-    protected array $pageOrderBy = ['field' => 'id', 'type' => 'asc'];
-
-    /**
-     * 详情查询后处理：补全父级名称
-     *
-     * @param int   $id   城市 ID
-     * @param array &$data 详情数据（引用传递）
-     * @return void
-     */
-    protected function afterDetail(int $id, array &$data): void
-    {
-        $pid = $data['pid'] ?? 0;
-        if ($pid > 0) {
-            $parent = City::where('id', $pid)->find();
-            $data['parentName'] = $parent ? $parent->name : '';
-        } else {
-            $data['parentName'] = '';
-        }
-    }
-
-    // 按父级行政编码获取子级城市
-    public function getCityListByParentCode(string $parentCode): array
-    {
-        return City::where('parent_code', $parentCode)
-            ->order('id', 'asc')
-            ->select()
-            ->toArray();
-    }
-
-    // 获取省份列表（level=0）
-    public function getParentList(): array
-    {
-        return City::where('level', 0)
-            ->order('id', 'asc')
-            ->select()
-            ->toArray();
-    }
-}
-```
-
-## 前端级联选择
-
-```typescript
-// ui/src/api/data/city.ts
-export function getCityList(parentCode: string) {
-  return http.request({
-    url: '/city/getCityList/' + parentCode,
-    method: 'GET',
-  });
-}
-
-// 省 → 市 → 区 → 街道 级联加载
-// 选择省份后加载城市，选择城市后加载区县...
-```
-
-## 模型辅助方法
-
-City 模型提供两个静态方法，供导入导出使用：
-
-| 方法 | 用途 | 示例 |
-|------|------|------|
-| `resolveCityNames(codes)` | 编码→名称 | `['320000000000','320100000000']` → `'江苏省,南京市'` |
-| `resolveCityCodes(info)` | 名称→编码 | `'江苏省,南京市,建邺区'` → `['320000000000','320100000000','320105000000','']` |
-
-```php
-// 导出时：城市编码拼为名称字符串
-$cityInfo = City::resolveCityNames(['320000000000', '320100000000', '320105000000']);
-// 结果: "江苏省,南京市,建邺区"
-
-// 导入时：城市名称反查为编码数组（逐级匹配，避免同名歧义）
-$codes = City::resolveCityCodes('江苏省,南京市,建邺区');
-// 结果: ['320000000000', '320100000000', '320105000000', '']
-```
+- [9.10 数据录入组件](/zh/frontend/form-components.html)（ChinaArea/Region 组件）