签入版本

RXThinkCMF_Laravel13_AntdVue/zh/modules/city.md

@@ -1,22 +1,23 @@
 # 6.9 行政区划管理
 
 :::tip 概述
-行政区划管理维护全国省市区街道四级数据，支持按父编码级联查询。继承 BaseLogic（系统共享，不隔离）。
+行政区划管理维护全国省市区街道四级数据，支持按父编码级联查询。`CityService` 继承 `BaseService`（系统共享，不隔离），是导入导出中城市字段正反转换的支撑模块。
 :::
 
 ## 模块特点
 
 | 特性 | 说明 |
 |------|------|
-| 基类 | BaseLogic（系统共享，不隔离） |
-| 层级结构 | id/pid + parent_code 双重层级标识 |
-| 特殊接口 | getCityList 按父编码查询、getParent 获取省份列表 |
-| 详情钩子 | afterDetail 补全父级名称 |
+| 基类 | `BaseService`（系统共享，不隔离） |
+| Trait 组合 | `HasCrudOperations, HasQueryScopes` |
+| 层级结构 | `id/pid`（数字层级）+ `parent_code/area_code`（行政编码层级）双重标识 |
+| 特殊接口 | `getByParentCode` 按父编码查询、`getProvinces` 省份列表、`getParent` 父级信息 |
+| 详情/删除钩子 | `afterDetail` 补全父级名称；`beforeDelete` 业务校验 |
 
 ## 数据库表结构
 
 ```sql
-CREATE TABLE `think_city` (
+CREATE TABLE `laravel_city` (
   `id` int NOT NULL AUTO_INCREMENT COMMENT '主键ID',
   `city_code` varchar(6) NOT NULL COMMENT '城市区号',
   `area_code` varchar(20) NOT NULL COMMENT '行政编码',
@@ -43,85 +44,59 @@ CREATE TABLE `think_city` (
 
 | 方法 | 路径 | 权限码 | 说明 |
 |------|------|--------|------|
-| GET | `/api/city/list` | sys:city:page | 城市列表 |
-| GET | `/api/city/detail/:id` | sys:city:detail | 详情 |
+| 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 | 删除 |
-| GET | `/api/city/getCityList/:parentCode` | - | 按父编码获取子级城市 |
-| GET | `/api/city/getParent` | - | 获取省份列表（level=0） |
-| GET | `/api/city/findByParentCode/:parentCode` | - | 根据父编码查询子级城市 |
+| DELETE | `/api/city/delete/{id}` | sys:city:delete | 删除 |
+| DELETE | `/api/city/batchDelete` | sys:city:batchDelete | 批量删除 |
+| GET | `/api/city/getCityList/{code}` | — | 按父编码获取子级城市（级联） |
+| GET | `/api/city/getParent/{id}` | — | 获取父级信息 |
+| GET | `/api/city/findByParentCode` | — | 按父编码查询子级 |
 
-## 核心代码
+## Service 配置（来自项目实际代码）
 
 ```php
-// app/logic/CityLogic.php
-
-class CityLogic extends BaseLogic
+class CityService extends BaseService
 {
-    /**
-     * 关联的模型类
-     *
-     * @var string
-     */
+    use HasCrudOperations, HasQueryScopes;
+
     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'];
 
+    // 树形结构（pid 层级）
+    protected string $treeParentField = 'pid';
+    protected string $treeLikeField = 'name';
+
     /**
      * 详情查询后处理：补全父级名称
-     *
-     * @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 : '';
+            $parent = City::find($pid);
+            $data['parentName'] = $parent?->name ?? '';
         } else {
             $data['parentName'] = '';
         }
     }
 
-    // 按父级行政编码获取子级城市
-    public function getCityListByParentCode(string $parentCode): array
-    {
-        return City::where('parent_code', $parentCode)
-            ->order('id', 'asc')
-            ->select()
-            ->toArray();
-    }
+    // 按父级行政编码获取子级城市（级联选择数据源）
+    public function getByParentCode(string $parentCode): array { /* ... */ }
 
     // 获取省份列表（level=0）
-    public function getParentList(): array
-    {
-        return City::where('level', 0)
-            ->order('id', 'asc')
-            ->select()
-            ->toArray();
-    }
+    public function getProvinces(): array { /* ... */ }
+
+    // 获取某城市的父级信息
+    public function getParent(int $id): ?array { /* ... */ }
 }
 ```
 
@@ -157,4 +132,8 @@ $cityInfo = City::resolveCityNames(['320000000000', '320100000000', '32010500000
 // 导入时：城市名称反查为编码数组（逐级匹配，避免同名歧义）
 $codes = City::resolveCityCodes('江苏省,南京市,建邺区');
 // 结果: ['320000000000', '320100000000', '320105000000', '']
-```
+```
+
+:::tip 数据来源
+全国行政区划数据已包含在数据库初始化脚本中（`document/mysql/` 导入即有），无需手动录入。见 [2.5 数据库初始化](/zh/quickstart/database-init.html)。
+:::