# Kylin Region

Kylin 省市区街道四级行政区划数据包 — 基于国家统计局行政区划数据，遵循 GB/T 2260 标准。

## 功能特性

- **四级联动**：省 → 市 → 区/县 → 街道/镇/乡
- **数据来源**：国家统计局最新行政区划
- **缓存优化**：省份/树形 24 小时缓存，搜索 1 小时缓存
- **API 接口**：前端级联选择器数据源
- **树形结构**：支持完整树形查询
- **搜索功能**：按名称模糊搜索
- **代码查询**：按行政区划代码或名称精确查询
- **导入命令**：支持从 JSON 文件批量导入数据

## 安装

```bash
composer require kylin/region
```

## 数据导入

```bash
# 导入省市区街道数据
php artisan kylin:region-import
```

## 使用示例

### Facade

```php
use Kylin\Region\Facades\KylinRegion;

// 获取所有省份
$provinces = KylinRegion::provinces();
// 等价于
$provinces = KylinRegion::getProvinces();

// 获取省下的城市（按行政区划代码）
$cities = KylinRegion::cities(110000); // 北京市

// 获取市下的区县
$districts = KylinRegion::districts(110100); // 北京市市辖区

// 获取指定父级下的子地区（按 ID）
$children = KylinRegion::getChildren(1);

// 根据名称搜索
$results = KylinRegion::search('海淀');

// 根据行政区划代码查询
$region = KylinRegion::byCode(110105); // 朝阳区

// 根据名称精确查询
$region = KylinRegion::byName('海淀区', 3); // level=3 表示区县

// 获取完整树形结构
$tree = KylinRegion::getTree();

// 清除缓存
KylinRegion::clearCache();
```

### API 路由

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /api/kylin/regions/provinces | 省份列表 |
| GET | /api/kylin/regions/{parentId}/children | 子级地区 |
| GET | /api/kylin/regions/tree | 完整树形结构 |

## 数据库表

| 表名 | 说明 |
|------|------|
| `kylin_regions` | 行政区划表（id/code/name/parent_id/level/sort） |

## 合规要点

| 合规项 | 实现方式 | 法律依据 |
|------|------|------|
| 数据来源合规 | 国家统计局官方数据 | 《数据安全法》第六条 |
| 个人信息保护 | 不含个人信息 | 《个人信息保护法》第六条 |
| 编码规范 | 6 位行政区划代码 | GB/T 2260-2007 |
| 数据缓存 | 24 小时 TTL | 《网络安全法》第二十一条 |
| 数据完整性 | 不篡改原始数据 | 《数据安全法》第二十七条 |

## 法律合规

详见 [LEGAL.md](./LEGAL.md)，涵盖：
- 《中华人民共和国数据安全法》(2021.9.1)
- 《中华人民共和国网络安全法》(2017.6.1)
- 《中华人民共和国个人信息保护法》(2021.11.1)
- 《中华人民共和国测绘法》(2017.7.1)
- 《地图管理条例》(2016.1.1)
- GB/T 2260-2007《中华人民共和国行政区划代码》
- GB/T 10114-2003《县以下行政区划代码编制规则》

## 依赖

- PHP ^8.5
- Laravel ^13.0
- kylin/core

## 许可证

私有软件，未经授权禁止使用。
