# Kylin WordFilter - 敏感词过滤

麒麟游戏服务平台敏感词过滤组件，基于 Trie 树 + DFA 算法实现高效敏感词匹配。

## 功能特性

- **Trie 树 + DFA 算法**：高效敏感词匹配，时间复杂度 O(n)
- **多种过滤模式**：替换（replace）、拦截（block）、警告（warn）
- **变体检测**：谐音、拆字、拼音、缩写四种变体检测
- **文本标准化**：全角转半角、繁体转简体、去除零宽字符
- **增量同步**：基于版本号的增量词库同步
- **分类管理**：符合 TC260-003 标准的 31 类风险分类（17 高风险 + 14 中风险）
- **批量过滤**：支持批量文本过滤
- **缓存优化**：Trie 树缓存、版本信息缓存

## 安装

```bash
composer require kylin/word-filter
```

## 配置发布

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

## 配置项

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `version` | `1.0.0` | 词库版本号 |
| `cache_ttl` | `3600` | 缓存 TTL（秒） |
| `filter_mode` | `replace` | 过滤模式：replace/block/warn |
| `replace_char` | `*` | 替换字符 |
| `variant_detection.homophone` | `true` | 谐音检测开关 |
| `variant_detection.split` | `true` | 拆字检测开关 |
| `variant_detection.pinyin` | `true` | 拼音检测开关 |
| `variant_detection.abbreviation` | `true` | 缩写检测开关 |
| `sync_interval` | `300` | 同步间隔（秒） |
| `batch_max_size` | `100` | 批量过滤最大条数 |

## API 接口

### 获取词库版本

```
GET /kylin/word-filter/version
```

### 增量同步词库

```
GET /kylin/word-filter/sync?from_version=1.0.0
```

### 文本过滤

```
POST /kylin/word-filter/filter
Content-Type: application/json

{
    "text": "待过滤文本",
    "scope": {
        "categories": ["political", "violence"],
        "min_severity": "moderate"
    }
}
```

### 批量过滤

```
POST /kylin/word-filter/filter/batch
Content-Type: application/json

{
    "texts": ["文本1", "文本2"],
    "scope": {}
}
```

### 获取分类列表

```
GET /kylin/word-filter/categories
```

## TC260-003 标准分类

### 高风险（17 类）

| 编码 | 名称 |
|------|------|
| `political` | 政治敏感 |
| `violence` | 暴力恐怖 |
| `pornography` | 色情低俗 |
| `cyberbullying` | 网络欺凌 |
| `drugs` | 毒品违法 |
| `rumor` | 谣言虚假 |
| `religious_extremism` | 宗教极端 |
| `ethnic_discrimination` | 民族歧视 |
| `separatism` | 分裂主义 |
| `terrorist_org` | 恐怖组织 |
| `cult` | 邪教 |
| `firearms` | 枪支弹药 |
| `riot_instigation` | 暴乱煽动 |
| `national_security` | 危害国家安全 |
| `espionage` | 间谍活动 |
| `money_laundering` | 洗钱 |
| `human_trafficking` | 人口贩卖 |

### 中风险（14 类）

| 编码 | 名称 |
|------|------|
| `vulgarity` | 低俗媚俗 |
| `clickbait` | 标题党 |
| `discrimination` | 歧视 |
| `bad_inducement` | 不良诱导 |
| `ip_infringement` | 侵犯知识产权 |
| `privacy_leak` | 泄露隐私 |
| `false_ad` | 虚假广告 |
| `pyramid_scheme` | 传销 |
| `gambling` | 赌博 |
| `prohibited_drugs` | 违禁药品 |
| `prohibited_trade` | 违禁品交易 |
| `illegal_fundraising` | 非法集资 |
| `surrogacy` | 代孕 |
| `organ_trade` | 器官买卖 |

## 使用示例

### 通过 Facade 使用

```php
use Kylin\WordFilter\Facades\KylinWordFilter;

// 过滤文本
$result = KylinWordFilter::filter('待过滤文本');

// 检测是否包含敏感词
$hasSensitive = KylinWordFilter::hasSensitiveWord('待检测文本');

// 批量过滤
$results = KylinWordFilter::batchFilter(['文本1', '文本2']);
```

### 通过服务容器使用

```php
use Kylin\WordFilter\Services\WordFilterService;

$result = app(WordFilterService::class)->filter('待过滤文本');
```

### 过滤结果格式

```json
{
    "original": "原始文本",
    "filtered": "过滤后文本",
    "mode": "replace",
    "matches": [
        {
            "word": "敏感词",
            "position": 3,
            "length": 3,
            "severity": "high",
            "category": "political"
        }
    ],
    "has_sensitive": true,
    "risk_level": "high"
}
```

## 数据库表

### kylin_sensitive_words - 敏感词表

| 字段 | 类型 | 说明 |
|------|------|------|
| `word` | varchar(100) | 敏感词 |
| `category_id` | bigint | 分类 ID |
| `severity` | enum | 严重程度：low/moderate/high/severe |
| `is_variant` | boolean | 是否为变体词 |
| `parent_id` | bigint | 父级词 ID（变体词指向原始词） |
| `status` | enum | 状态：active/disabled |

### kylin_word_categories - 词库分类表

| 字段 | 类型 | 说明 |
|------|------|------|
| `code` | varchar(50) | 分类编码 |
| `name` | varchar(100) | 分类名称 |
| `risk_level` | enum | 风险等级：high/medium |
| `description` | text | 描述 |
| `word_count` | int | 词数统计 |

### kylin_word_filter_versions - 词库版本表

| 字段 | 类型 | 说明 |
|------|------|------|
| `version` | varchar(20) | 版本号 |
| `total_words` | int | 总词数 |
| `category_stats` | json | 分类统计 |
| `checksum` | varchar(32) | 校验和 |
| `change_summary` | text | 变更摘要 |
| `published_at` | timestamp | 发布时间 |
