# Kylin Core

Kylin 核心基础包 — 统一响应结构、异常处理、错误码体系、安全中间件。

## 功能特性

### 统一响应结构
- `code` + `message` + `data` + `trace_id` 四段式结构
- 兼容 RFC 9457 Problem Details for HTTP APIs
- 支持成功/分页/创建/无内容/错误五种响应类型

### 异常层次体系
- `KylinException` 基类 → `BusinessException` / `ValidationException` / `NotFoundException`
- 全局异常处理器 `ApiExceptionHandler` 策略模式
- 自动映射异常类型到 HTTP 状态码 + 业务错误码
- 生产环境不泄露敏感错误信息

### 错误码体系
- `{包前缀}-{分类}-{编号}` 格式，如 `CORE-SYS-001`
- 语义化、可溯源、跨包唯一
- `KylinErrorCodeInterface` 统一错误码定义规范
- `CoreErrorCode` 枚举提供核心包错误码

### 安全中间件
- `SecurityHeaders`：安全响应头（CSP、HSTS、X-Frame-Options 等）
- `RateLimit`：速率限制（全局/认证/游戏三级限流）

### 请求追踪
- `HasTraceId` Trait 提供 X-Trace-Id 请求链追踪
- 跨服务传递，便于全链路问题定位

## 安装

```bash
composer require kylin/core
```

## 配置发布

```bash
php artisan vendor:publish --tag=kylin-core-config
```

## 使用示例

### 统一响应

```php
use Kylin\Core\Facades\KylinCore;

// 成功响应
return KylinCore::success($data, '操作成功');

// 分页响应
return KylinCore::paginate($paginator);

// 创建成功响应（HTTP 201）
return KylinCore::created($resource, '创建成功');

// 无内容响应（HTTP 204）
return KylinCore::noContent();

// 错误响应
return KylinCore::error('USR-AUTH-001', '认证失败', 401);
```

### 异常抛出

```php
use Kylin\Core\Exceptions\BusinessException;
use Kylin\Core\Exceptions\ValidationException;
use Kylin\Core\Exceptions\NotFoundException;

// 业务异常
throw new BusinessException('用户不存在', 'USR-AUTH-002');

// 验证异常
throw new ValidationException('手机号格式错误', 'USR-VAL-001');

// 资源不存在异常（自动映射 HTTP 404）
throw new NotFoundException('订单不存在', 'EC-ORD-001');
```

### 自定义错误码

```php
use Kylin\Core\Contracts\KylinErrorCodeInterface;

enum UserErrorCode: string implements KylinErrorCodeInterface
{
    case NOT_FOUND = 'USR-AUTH-001';
    case AUTH_FAILED = 'USR-AUTH-002';

    public function code(): string { return $this->value; }
    public function message(): string { return match($this) {
        self::NOT_FOUND => '用户不存在',
        self::AUTH_FAILED => '认证失败',
    }; }
}
```

### 安全响应头中间件

```php
// 在 app/Http/Kernel.php 或 bootstrap/app.php 注册
protected $middleware = [
    \Kylin\Core\Middleware\SecurityHeaders::class,
    \Kylin\Core\Middleware\RateLimit::class,
];
```

### 速率限制配置

```php
// config/kylin-core.php
'rate_limit' => [
    'global' => ['attempts' => 60, 'decay_minutes' => 1],
    'auth'   => ['attempts' => 5,  'decay_minutes' => 1],
    'game'   => ['attempts' => 30, 'decay_minutes' => 1],
],
```

## 安全响应头清单

依据 OWASP Top 10 和等保 2.0 (GB/T 22239) 要求，默认开启：

| 响应头 | 默认值 | 说明 |
|------|------|------|
| `X-Content-Type-Options` | `nosniff` | 防止 MIME 类型嗅探 |
| `X-Frame-Options` | `DENY` | 防止点击劫持 |
| `X-XSS-Protection` | `1; mode=block` | XSS 过滤 |
| `Referrer-Policy` | `strict-origin-when-cross-origin` | Referrer 控制 |
| `Permissions-Policy` | `camera=(), microphone=(), geolocation=()` | 权限策略 |
| `Content-Security-Policy` | 可配置 | 内容安全策略 |
| `Strict-Transport-Security` | `max-age=31536000`（生产环境） | HSTS 强制 HTTPS |

## 错误码规范

错误码采用 `{包前缀}-{分类}-{编号}` 三段式格式：

| 包前缀 | 示例 | 说明 |
|------|------|------|
| `CORE` | `CORE-SYS-001` | 核心包 |
| `USR` | `USR-AUTH-001` | 用户包 |
| `EC` | `EC-ORD-001` | 电商包 |
| `GAME` | `GAME-AUTH-001` | 游戏包 |

分类约定：`SYS`（系统）、`AUTH`（认证）、`VAL`（验证）、`ORD`（订单）、`PAY`（支付）等。

## 法律合规

本包作为所有扩展包的底层依赖，已实现以下合规基础能力：

- **等保 2.0 (GB/T 22239)**：安全响应头、速率限制、请求追踪、全局异常处理
- **《网络安全法》**：防范网络攻击技术措施、网络产品符合国家标准
- **《数据安全法》**：Trace ID 全链路追踪支持数据风险监测
- **《个人信息保护法》**：HSTS 强制 HTTPS、安全响应头防泄露
- **OWASP Top 10**：访问控制、加密失败、注入、安全配置、认证失败防护

详见 [LEGAL.md](LEGAL.md)。

## 依赖

- PHP ^8.5
- Laravel ^13.0

## 许可证

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