# 邮件模块文档

## 模块说明
邮件模块是一个统一的邮件发送系统，支持多种邮件服务商，包括SMTP、阿里云邮件推送等。

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

## 数据表设计

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

### 邮件记录表 (mail_logs)
| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | bigint | 主键ID |
| template_id | bigint | 模板ID |
| to | varchar(255) | 收件人 |
| cc | varchar(255) | 抄送人 |
| bcc | varchar(255) | 密送人 |
| subject | varchar(255) | 邮件主题 |
| content | text | 邮件内容 |
| data | json | 发送数据 |
| status | varchar(20) | 状态 |
| message | varchar(255) | 发送结果 |
| sent_at | timestamp | 发送时间 |
| created_at | timestamp | 创建时间 |
| updated_at | timestamp | 更新时间 |

## 枚举定义

### 邮件状态 (MailStatus)
- PENDING: 待发送
- SENDING: 发送中
- SENT: 已发送
- FAILED: 发送失败

### 邮件服务商 (MailProvider)
- SMTP: SMTP服务
- ALIYUN: 阿里云邮件推送
- SENDCLOUD: SendCloud
- MAILGUN: Mailgun

## 核心服务

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

主要方法：
- send(array $data): 发送邮件
- sendBatch(array $data): 批量发送邮件
- getTemplate(int $id): 获取模板
- createTemplate(array $data): 创建模板
- updateTemplate(int $id, array $data): 更新模板
- deleteTemplate(int $id): 删除模板

## 队列处理

### SendMailQueue
邮件发送队列，处理异步发送任务。

## 使用示例

```php
// 发送邮件
$mailService = new MailService();
$mailService->send([
    'template_id' => 1,
    'to' => 'example@example.com',
    'data' => [
        'name' => '张三',
        'amount' => 100
    ]
]);

// 批量发送邮件
$mailService->sendBatch([
    [
        'template_id' => 1,
        'to' => 'example1@example.com',
        'data' => ['name' => '张三']
    ],
    [
        'template_id' => 1,
        'to' => 'example2@example.com',
        'data' => ['name' => '李四']
    ]
]);
```

## 注意事项
1. 邮件发送采用队列异步处理
2. 支持失败重试机制
3. 支持变量替换
4. 支持多服务商
5. 支持发送频率限制
6. 支持邮件黑名单
7. 支持发送统计
8. 支持HTML和纯文本格式
9. 支持附件发送
10. 支持抄送和密送