# Kylin AuditLog

Kylin 审计日志包 — 自动记录模型变更和用户操作，符合等保 2.0 安全审计要求。

## 功能特性

- **自动记录**：模型创建/更新/删除自动生成审计日志
- **变更追踪**：记录字段旧值和新值（`old_values` / `new_values`）
- **用户关联**：自动关联操作用户、IP 地址、User-Agent
- **查询过滤**：按模型、用户、操作类型、时间范围、租户筛选
- **数据清理**：自动清理过期日志（`keep_days`），强制最小保留 180 天
- **不可篡改**：审计日志禁止修改和删除，仅可 `forceDelete()` 清理
- **敏感信息脱敏**：自动过滤身份证号、银行卡号等敏感字段
- **多租户隔离**：租户间审计日志严格隔离

## 安装

```bash
composer require kylin/audit-log
php artisan vendor:publish --tag=kylin-audit-log-config
php artisan vendor:publish --tag=kylin-audit-log-migrations
php artisan migrate
```

## 配置说明

```php
// config/kylin-audit-log.php
return [
    'keep_days' => 365,           // 日志保留天数（>= 180 天）
    'immutable' => true,           // 日志不可篡改
    'multi_tenant' => true,        // 多租户隔离
    'sensitive_fields' => [        // 敏感字段脱敏
        'password', 'password_confirmation',
        'id_card', 'id_number',
        'bank_card', 'bank_account',
        'phone', 'mobile', 'email',
        'token', 'api_key', 'secret',
        'credit_card', 'cvv', 'ssn',
    ],
    'exclude_events' => [],        // 排除的事件类型：['created', 'updated', 'deleted']
    'exclude_models' => [],        // 排除的模型类名
];
```

## 使用示例

### 模型启用审计

```php
use Kylin\AuditLog\Traits\Auditable;

class Article extends Model
{
    use Auditable;

    // 可选：指定要记录的字段
    protected array $auditFields = ['title', 'content', 'status'];

    // 可选：排除字段
    protected array $auditExclude = ['updated_at'];
}
```

### 查询审计日志

```php
use Kylin\AuditLog\Facades\KylinAuditLog;
use Kylin\AuditLog\Models\AuditLog;

// 获取模型的审计记录
$logs = KylinAuditLog::getForModel($article);

// 获取用户的操作记录
$logs = AuditLog::where('user_id', $userId)->latest()->paginate();

// 按时间范围查询
$logs = AuditLog::whereBetween('created_at', [now()->subDays(7), now()])->get();

// 按操作类型查询
$logs = AuditLog::where('event', 'updated')->get();
```

### 清理过期日志

```bash
# 清理超过保留期的日志（强制最小 180 天）
php artisan kylin:audit-log-clean

# 生产环境需加 --force
php artisan kylin:audit-log-clean --force
```

### 审计日志记录字段

每次操作自动记录以下信息：

| 字段 | 说明 |
|------|------|
| `user_id` | 操作用户 ID |
| `event` | 操作类型（created/updated/deleted） |
| `auditable_type` | 模型类名 |
| `auditable_id` | 模型 ID |
| `old_values` | 变更前值（JSON，敏感字段自动脱敏） |
| `new_values` | 变更后值（JSON，敏感字段自动脱敏） |
| `url` | 请求 URL |
| `ip_address` | 客户端 IP |
| `user_agent` | 浏览器 User-Agent |
| `tags` | 自定义标签 |
| `tenant_id` | 租户 ID（多租户模式） |

## 数据库表

| 表名 | 说明 |
|------|------|
| `kc_audit_logs` | 审计日志表（不可篡改，含 tenant_id 索引） |

## 法律合规

详见 [LEGAL.md](./LEGAL.md)，涵盖：
- 等保 2.0 (GB/T 22239-2019) — 安全审计
- 《中华人民共和国网络安全法》(2017.6.1)
- 《中华人民共和国个人信息保护法》(2021.11.1)
- 《中华人民共和国数据安全法》(2021.9.1)
- 《信息安全技术 个人信息安全规范》(GB/T 35273-2020)
- 《网络数据安全管理条例》(2025.1.1)

## 依赖

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

## 许可证

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