# Kylin World

Kylin 全球行政区划数据包 — 国家/省/市/区县四级行政区划，ISO 3166-1/3166-2 标准，含货币、电话区号、经纬度信息。

## 功能特性

- **四级行政区划**：国家/省/市/区县层级数据
- **ISO 标准**：遵循 ISO 3166-1（国家代码）、ISO 3166-2（行政区划）、ISO 4217（货币代码）、ITU-T E.164（电话区号）
- **多语言支持**：中英文国家名称
- **货币信息**：货币代码、符号、名称
- **电话区号**：国际电话区号
- **经纬度**：行政区划地理坐标
- **缓存优化**：查询结果缓存 86400 秒（1 天）
- **数据导入**：`ImportRegionsCommand` 支持从国家统计局数据导入
- **树形结构**：支持获取完整行政区划树

## 安装

```bash
composer require kylin/world
```

## 配置发布

```bash
php artisan vendor:publish --tag=kylin-world-config
php artisan vendor:publish --tag=kylin-world-migrations
php artisan migrate
```

## 数据导入

```bash
# 导入中国行政区划（默认）
php artisan kylin:world:import

# 导入指定国家
php artisan kylin:world:import --country=US
```

## 使用示例

### Facade 方式

```php
use Kylin\World\Facades\KylinWorld;

// 获取所有国家
$countries = KylinWorld::countries();

// 获取指定国家的省份
$provinces = KylinWorld::provinces('CN');

// 获取指定省份的城市
$cities = KylinWorld::cities($provinceId);

// 获取指定城市的区县
$districts = KylinWorld::districts($cityId);

// 获取完整行政区划树
$tree = KylinWorld::regionTree('CN');
```

### 服务注入方式

```php
use Kylin\World\Services\RegionService;

public function __construct(
    private readonly RegionService $regionService
) {}

public function getChinaProvinces(): array
{
    return $this->regionService->getProvinces('CN');
}
```

## 数据库表

| 表名 | 说明 |
|------|------|
| `kylin_regions` | 行政区划表（id/parent_id/name/code/country_code/level/full_name/pinyin/short_name/calling_code/currency_code/currency_symbol/currency_name/longitude/latitude/sort/status） |

### 字段说明

| 字段 | 类型 | 说明 |
|------|------|------|
| `level` | tinyint | 层级: 0=国家 1=省 2=市 3=区县 |
| `code` | varchar(20) | 区域编码（ISO 3166-1/2 或国家统计局编码） |
| `country_code` | varchar(5) | 国家代码（ISO 3166-1 alpha-2） |
| `calling_code` | varchar(10) | 电话区号（ITU-T E.164） |
| `currency_code` | varchar(10) | 货币代码（ISO 4217） |

## 法律合规

详见 [LEGAL.md](./LEGAL.md)，涵盖：
- 《中华人民共和国数据安全法》— 第六条、第二十一条
- 《中华人民共和国网络安全法》— 第四十二条
- 《中华人民共和国个人信息保护法》— 第六条
- 《中华人民共和国测绘法》(2017.7.1) — 第三十四条
- ISO 3166-1/3166-2 国家代码标准
- ISO 4217 货币代码标准
- ITU-T E.164 电话区号标准

## 依赖

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

## 许可证

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