\App\Services\AdminDataRegionService

地区服务

职责：省/市/区/街道/村五级树（ancestors 祖级路径 0/1/5/）；level 按父级自动推导，调整父级时级联重算全部后代的 ancestors 与 level；金字塔级联启用/停用在此收口。

┌────────────────── 分区导航（按此顺序阅读）──────────────────┐ 分区 1 · 查询（读） tree / stats / cascader / path / search 分区 2 · 写操作 create / update / destroy / updateStatus 分区 3 · 内部辅助 pathOf / resolvePlacement / cascade └────────────────────────────────────────────────────────────┘

Summary

Methods

Properties

Constants

tree()
stats()
cascader()
path()
search()
create()
update()
destroy()
updateStatus()

No public properties found

No constants found

No protected methods found

No protected properties found

N/A

pathOf()
pathMap()
resolvePlacement()
cascade()

No private properties found

N/A

File: Backend-Admin-PHP/app/Services/Admin/DataRegionService.php
Package: Application
Class hierarchy: \App\Services\Admin\DataRegionService
Uses

Methods

tree()

tree(?int  $parentId = null) : array

地区树（按需加载）：缺省只查顶级（省）；传 parentId 查该节点子级。 66 万条五级数据不能全量组树（内存/递归爆），必须懒加载。按 parentId 缓存（顶级 parentId=0），地区变更（region:restore/CRUD）自动失效。

Parameters

?int

$parentId

Returns

array —

stats()

stats() : array

地区统计（各级数量）：供管理页概览卡（全表 GROUP BY 实测 78ms → 缓存，region 表变更自动失效）

Returns

array —

cascader()

cascader(int  $maxLevel = 5, ?int  $parentId = null) : array

地区级联（1-5 级可配）：value/label/children 结构，max_level 控制深度。 parent_id 提供时从该节点开始返回子级（懒加载级联）。

Parameters

int	$maxLevel
?int	$parentId

Returns

array —

path()

path(\App\Models\SysRegion  $region) : array

地区路径（祖先链 + 自身，编辑回显用）：ancestors "0/1/2/" → [{id,name,level}...]。

Parameters

\App\Models\SysRegion

$region

Returns

array —

search()

search(string  $keyword, ?int  $limit = null) : array

地区搜索（任意层级，服务端）：供管理页搜索框定位任意层级地区。

66 万行无 name/pinyin 索引，名称/拼音为子串匹配（seq scan），LIMIT 兜底—— 实测「%海%」取 50 行 ≈ 100ms，管理后台低频可接受； pinyin 存储带空格（"bao hua"），匹配前双方去空格；code 为 12 位数字，走前缀匹配。比较统一 LOWER() 大小写不敏感（pg LIKE 区分大小写）；标准 SQL，测试 sqlite 亦可跑。每行带 path（省→…→自身）供前端定位层级。

Parameters

string	$keyword
?int	$limit

Returns

array —

create()

create(array  $data) : \App\Models\SysRegion

创建地区：解析落位（ancestors/level）后落库（12 位行政编码用 code 当 id，与导入一致）

Parameters

array

$data

Returns

\App\Models\SysRegion —

update()

update(\App\Models\SysRegion  $region, array  $data) : \App\Models\SysRegion

更新地区：父级变更时级联重算后代 ancestors/level，提交后失效地区缓存

Parameters

\App\Models\SysRegion	$region
array	$data

Returns

\App\Models\SysRegion —

destroy()

destroy(\App\Models\SysRegion  $region) : void

删除地区：校验无子地区、无档案引用后删除

Parameters

\App\Models\SysRegion

$region

updateStatus()

updateStatus(\App\Models\SysRegion  $region, int  $status) : int

金字塔级联启用/禁用（自控制器下沉）：勾选某级 = 该地区及其全部子孙地区一起启用/停用（ancestors 前缀批量，与岗位配置 dept_id 子树筛选同语义）。返回受影响行数。

Parameters

\App\Models\SysRegion	$region
int	$status

Returns

int —

pathOf()

pathOf(\App\Models\SysRegion  $region) : array

地区路径（祖先链 + 自身）：ancestors "0/1/2/" → [{id,name,level}...]。 path()/search() 共用；path 末尾为自身。

Parameters

\App\Models\SysRegion

$region

Returns

array —

pathMap()

pathMap(\Illuminate\Support\Collection<int,\App\Models\SysRegion>  $regions) : array

批量地区路径：收集全部结果的祖先 id 一次性查回（消除逐行 pathOf 的 N+1—— 搜索 limit≤100 时由最多 100 次查询收敛为 1 次）。

Parameters

\Illuminate\Support\Collection

$regions

Returns

array —

resolvePlacement()

resolvePlacement(int  $parentId, int|null  $excludeId = null) : array

计算节点落位：[祖级路径, 层级]。父级 level 必须 ≤4，超过五级拒绝。

Parameters

int	$parentId
int\|null	$excludeId	更新时的自身ID，用于拦截「把后代设为父级」

Returns

array —

cascade()

cascade(\App\Models\SysRegion  $region, string  $newAncestors, int  $newLevel, int  $newParentId) : void

级联重算后代：ancestors 旧前缀替换为新前缀，level 随自身层级差平移。批量 UPDATE 单源：AncestorsPath::cascadeUpdate（前缀区间走 idx_region_ancestors）。

Parameters

\App\Models\SysRegion	$region
string	$newAncestors
int	$newLevel
int	$newParentId