# 推送模块文档

## 模块说明
推送模块是一个统一的手机推送系统，支持多种推送服务商，包括极光推送、个推、友盟等。

## 目录结构
```
app/Module/Push/
├── Controllers/          # 控制器目录
├── Models/              # 模型目录
├── Repositorys/         # 仓库目录
├── Services/            # 服务目录
├── Validators/          # 验证器目录
├── Validations/         # 验证规则目录
├── Queues/              # 队列目录
├── Enums/               # 枚举目录
└── Commands/            # 命令目录
```

## 数据表设计

### 推送模板表 (push_templates)
| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | bigint | 主键ID |
| name | varchar(100) | 模板名称 |
| title | varchar(255) | 推送标题 |
| content | text | 推送内容 |
| variables | json | 变量定义 |
| status | tinyint | 状态：0禁用 1启用 |
| created_at | timestamp | 创建时间 |
| updated_at | timestamp | 更新时间 |

### 推送记录表 (push_logs)
| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | bigint | 主键ID |
| template_id | bigint | 模板ID |
| device_token | varchar(255) | 设备令牌 |
| title | varchar(255) | 推送标题 |
| content | text | 推送内容 |
| data | json | 推送数据 |
| status | varchar(20) | 状态 |
| message | varchar(255) | 推送结果 |
| message_id | varchar(100) | 消息ID |
| sent_at | timestamp | 发送时间 |
| created_at | timestamp | 创建时间 |
| updated_at | timestamp | 更新时间 |

### 设备表 (devices)
| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | bigint | 主键ID |
| user_id | bigint | 用户ID |
| device_token | varchar(255) | 设备令牌 |
| platform | varchar(20) | 平台 |
| model | varchar(100) | 设备型号 |
| version | varchar(50) | 系统版本 |
| status | tinyint | 状态：0禁用 1启用 |
| created_at | timestamp | 创建时间 |
| updated_at | timestamp | 更新时间 |

## 枚举定义

### 推送状态 (PushStatus)
- PENDING: 待发送
- SENDING: 发送中
- SENT: 已发送
- FAILED: 发送失败

### 推送服务商 (PushProvider)
- JPUSH: 极光推送
- GETUI: 个推
- UMENG: 友盟
- XIAOMI: 小米推送
- HUAWEI: 华为推送

### 设备平台 (DevicePlatform)
- IOS: iOS
- ANDROID: Android
- HARMONY: HarmonyOS

## 核心服务

### PushService
推送核心服务，负责推送的发送、模板管理等功能。

主要方法：
- send(array $data): 发送推送
- sendBatch(array $data): 批量发送推送
- getTemplate(int $id): 获取模板
- createTemplate(array $data): 创建模板
- updateTemplate(int $id, array $data): 更新模板
- deleteTemplate(int $id): 删除模板
- registerDevice(array $data): 注册设备
- unregisterDevice(string $deviceToken): 注销设备

## 队列处理

### SendPushQueue
推送发送队列，处理异步发送任务。

## 使用示例

```php
// 发送推送
$pushService = new PushService();
$pushService->send([
    'template_id' => 1,
    'device_token' => 'device_token_123',
    'data' => [
        'order_id' => '123456'
    ]
]);

// 批量发送推送
$pushService->sendBatch([
    [
        'template_id' => 1,
        'device_token' => 'device_token_123',
        'data' => ['order_id' => '123456']
    ],
    [
        'template_id' => 1,
        'device_token' => 'device_token_456',
        'data' => ['order_id' => '654321']
    ]
]);

// 注册设备
$pushService->registerDevice([
    'user_id' => 1,
    'device_token' => 'device_token_123',
    'platform' => DevicePlatform::IOS,
    'model' => 'iPhone 12',
    'version' => '15.0'
]);
```

## 注意事项
1. 推送发送采用队列异步处理
2. 支持失败重试机制
3. 支持变量替换
4. 支持多服务商
5. 支持发送频率限制
6. 支持设备黑名单
7. 支持发送统计
8. 支持定时推送
9. 支持标签推送
10. 支持别名推送
11. 支持分组推送
12. 支持透传消息