@builder6/email 3.2.3 → 4.0.0

package/README.md

@@ -1,29 +1,421 @@
 # Builder6 Email Module
 
+Builder6 Email 模块为 Builder6 平台提供完整的邮件发送和队列管理功能，支持 SMTP 邮件发送、邮件队列处理、批量发送等企业级邮件服务。
 
-## Environment Variables
+## 功能特性
 
-```shell
+- **SMTP 邮件发送**: 支持标准 SMTP 协议发送邮件
+- **邮件队列**: 基于数据库的邮件队列，支持失败重试
+- **批量发送**: 支持批量邮件发送，可配置批次大小
+- **定时发送**: 自动定时检查队列并发送待发邮件
+- **邮件模板**: 支持 HTML 和文本邮件模板
+- **附件支持**: 支持邮件附件发送
+- **邮件验证**: 自动验证邮件地址格式
+- **发送日志**: 记录邮件发送状态和日志
+- **失败处理**: 发送失败自动重试机制
+- **队列保留**: 可选择发送后保留或删除队列记录
+
+## 安装
+
+```bash
+npm install @builder6/email
+```
+
+或
+
+```bash
+yarn add @builder6/email
+```
+
+## 环境变量
+
+### SMTP 服务器配置
+
+```bash
+# 启用邮件服务
+B6_EMAIL_ENABLED=true
+
+# 发件人地址
 B6_EMAIL_FROM=Steedos <noreply@steedos.com>
-B6_EMAIL_HOST=email.xxxx.amazonaws.com
+
+# SMTP 服务器地址
+B6_EMAIL_HOST=email.example.amazonaws.com
+
+# SMTP 服务器端口
 B6_EMAIL_PORT=465
-B6_EMAIL_USERNAME=xxxxx
-B6_EMAIL_PASSWORD=xxxxx
+
+# SMTP 用户名
+B6_EMAIL_USERNAME=your-smtp-username
+
+# SMTP 密码
+B6_EMAIL_PASSWORD=your-smtp-password
+
+# 使用 SSL/TLS
+B6_EMAIL_SECURE=true
+
+# 启用调试模式
+B6_EMAIL_DEBUG=false
+
+# 启用日志记录
+B6_EMAIL_LOGGER=true
+```
+
+### 邮件队列配置
+
+当 `B6_EMAIL_ENABLED=true` 时，系统会启动定时任务从 `_mail_queue` 集合中读取邮件并发送。
+
+```bash
+# 邮件队列检查间隔（毫秒），默认 3000ms = 3秒
+STEEDOS_EMAIL_QUEUE_INTERVAL=3000
+
+# 每次批量发送的邮件数量，默认 1
+STEEDOS_EMAIL_QUEUE_BATCH_SIZE=10
+
+# 邮件发送超时时间（毫秒），默认 60000ms = 60秒
+STEEDOS_EMAIL_QUEUE_TIMEOUT=60000
+
+# 邮件发送后是否保留队列记录，默认 false（删除）
+STEEDOS_EMAIL_QUEUE_KEEPS=false
+```
+
+### 常用 SMTP 提供商配置
+
+#### Gmail
+
+```bash
+B6_EMAIL_HOST=smtp.gmail.com
+B6_EMAIL_PORT=465
+B6_EMAIL_SECURE=true
+B6_EMAIL_USERNAME=your-email@gmail.com
+B6_EMAIL_PASSWORD=your-app-password
+```
+
+#### Amazon SES
+
+```bash
+B6_EMAIL_HOST=email-smtp.us-east-1.amazonaws.com
+B6_EMAIL_PORT=465
+B6_EMAIL_SECURE=true
+B6_EMAIL_USERNAME=your-smtp-username
+B6_EMAIL_PASSWORD=your-smtp-password
+```
+
+#### Outlook/Office 365
+
+```bash
+B6_EMAIL_HOST=smtp.office365.com
+B6_EMAIL_PORT=587
 B6_EMAIL_SECURE=false
+B6_EMAIL_USERNAME=your-email@outlook.com
+B6_EMAIL_PASSWORD=your-password
+```
+
+#### 腾讯企业邮箱
+
+```bash
+B6_EMAIL_HOST=smtp.exmail.qq.com
+B6_EMAIL_PORT=465
+B6_EMAIL_SECURE=true
+B6_EMAIL_USERNAME=your-email@company.com
+B6_EMAIL_PASSWORD=your-password
+```
+
+## 使用示例
+
+### 在 NestJS 应用中集成
+
+```typescript
+import { Module } from '@nestjs/common';
+import { EmailModule } from '@builder6/email';
+
+@Module({
+  imports: [EmailModule],
+})
+export class AppModule {}
+```
+
+### 使用 EmailService 发送邮件
+
+```typescript
+import { EmailService } from '@builder6/email';
+
+constructor(private emailService: EmailService) {}
+
+// 发送简单文本邮件
+async sendTextEmail() {
+  await this.emailService.send({
+    to: 'user@example.com',
+    subject: 'Welcome to Builder6',
+    text: 'Thank you for joining us!'
+  });
+}
+
+// 发送 HTML 邮件
+async sendHtmlEmail() {
+  await this.emailService.send({
+    to: 'user@example.com',
+    subject: 'Welcome to Builder6',
+    html: '<h1>Welcome!</h1><p>Thank you for joining us!</p>'
+  });
+}
+
+// 发送带附件的邮件
+async sendEmailWithAttachment() {
+  await this.emailService.send({
+    to: 'user@example.com',
+    subject: 'Document Attached',
+    html: '<p>Please find the document attached.</p>',
+    attachments: [
+      {
+        filename: 'document.pdf',
+        path: '/path/to/document.pdf'
+      }
+    ]
+  });
+}
+
+// 发送给多个收件人
+async sendToMultipleRecipients() {
+  await this.emailService.send({
+    to: ['user1@example.com', 'user2@example.com'],
+    cc: ['manager@example.com'],
+    bcc: ['admin@example.com'],
+    subject: 'Team Update',
+    html: '<p>Important team update...</p>'
+  });
+}
+```
+
+### 使用邮件队列
+
+```typescript
+import { EmailQueueService } from '@builder6/email';
+
+constructor(private emailQueueService: EmailQueueService) {}
+
+// 添加邮件到队列
+async queueEmail() {
+  await this.emailQueueService.addToQueue({
+    to: 'user@example.com',
+    subject: 'Queued Email',
+    html: '<p>This email will be sent by the queue processor.</p>',
+    priority: 1, // 优先级，数字越小优先级越高
+    scheduledAt: new Date('2024-01-20 10:00:00') // 计划发送时间
+  });
+}
+
+// 批量添加邮件到队列
+async queueBatchEmails(users: User[]) {
+  const emails = users.map(user => ({
+    to: user.email,
+    subject: 'Newsletter',
+    html: `<p>Hello ${user.name},</p><p>Your monthly newsletter...</p>`
+  }));
+  
+  await this.emailQueueService.addBatchToQueue(emails);
+}
+
+// 获取队列状态
+async getQueueStatus() {
+  const pending = await this.emailQueueService.getPendingCount();
+  const failed = await this.emailQueueService.getFailedCount();
+  
+  return { pending, failed };
+}
+
+// 重试失败的邮件
+async retryFailedEmails() {
+  await this.emailQueueService.retryFailed();
+}
+```
+
+## 邮件队列数据结构
+
+邮件队列存储在 MongoDB 的 `_mail_queue` 集合中：
+
+```typescript
+interface MailQueue {
+  _id: string;
+  to: string | string[];
+  cc?: string | string[];
+  bcc?: string | string[];
+  from?: string;
+  subject: string;
+  text?: string;
+  html?: string;
+  attachments?: Array<{
+    filename: string;
+    path?: string;
+    content?: Buffer;
+  }>;
+  status: 'pending' | 'sending' | 'sent' | 'failed';
+  priority: number; // 1-10，数字越小优先级越高
+  attempts: number; // 发送尝试次数
+  lastAttempt?: Date;
+  scheduledAt?: Date; // 计划发送时间
+  sentAt?: Date;
+  error?: string;
+  created: Date;
+  modified: Date;
+}
+```
+
+## 邮件模板
+
+### 使用 LiquidJS 模板
+
+```typescript
+import { EmailService } from '@builder6/email';
+
+async sendTemplatedEmail(user: User) {
+  const template = `
+    <h1>Welcome, {{ user.name }}!</h1>
+    <p>Your account has been created successfully.</p>
+    <p>Username: {{ user.username }}</p>
+    <p>Email: {{ user.email }}</p>
+  `;
+  
+  const html = this.emailService.renderTemplate(template, { user });
+  
+  await this.emailService.send({
+    to: user.email,
+    subject: 'Welcome to Builder6',
+    html
+  });
+}
+```
+
+## API 端点
+
+模块提供以下主要 API 端点（如果启用 HTTP 接口）：
+
+- **POST `/api/v6/email/send`**: 直接发送邮件（需要管理员权限）
+- **POST `/api/v6/email/queue`**: 添加邮件到队列
+- **GET `/api/v6/email/queue/status`**: 获取队列状态
+- **POST `/api/v6/email/queue/retry`**: 重试失败的邮件
+
+## 邮件队列处理流程
+
+1. **添加到队列**: 邮件信息写入 `_mail_queue` 集合，状态为 `pending`
+2. **定时检查**: 每隔 `STEEDOS_EMAIL_QUEUE_INTERVAL` 毫秒检查一次队列
+3. **批量处理**: 按优先级和创建时间排序，每次处理 `STEEDOS_EMAIL_QUEUE_BATCH_SIZE` 条
+4. **发送邮件**: 更新状态为 `sending`，调用 SMTP 发送
+5. **更新状态**: 
+   - 成功：更新为 `sent`，记录发送时间
+   - 失败：更新为 `failed`，记录错误信息，增加尝试次数
+6. **清理队列**: 如果 `STEEDOS_EMAIL_QUEUE_KEEPS=false`，删除已发送的邮件
+
+## 失败重试策略
+
+- 默认最大重试次数：3 次
+- 重试间隔：指数退避（exponential backoff）
+  - 第 1 次失败：等待 1 分钟
+  - 第 2 次失败：等待 5 分钟
+  - 第 3 次失败：等待 15 分钟
+- 超过最大重试次数后，邮件保持 `failed` 状态，需要手动处理
+
+## 性能优化
+
+### 批量发送优化
+
+```bash
+# 增加批量大小以提高吞吐量
+STEEDOS_EMAIL_QUEUE_BATCH_SIZE=50
+
+# 减少检查间隔以更快处理队列
+STEEDOS_EMAIL_QUEUE_INTERVAL=1000
+```
+
+### 连接池优化
+
+```bash
+# 配置 SMTP 连接池
+B6_EMAIL_POOL=true
+B6_EMAIL_POOL_MAX_CONNECTIONS=10
+B6_EMAIL_POOL_MAX_MESSAGES=100
+```
+
+## 监控和日志
+
+### 启用详细日志
+
+```bash
 B6_EMAIL_DEBUG=true
 B6_EMAIL_LOGGER=true
-B6_EMAIL_ENABLED=true
 ```
 
-## 配置定时发送
+### 日志信息包括
+
+- SMTP 连接状态
+- 邮件发送详情
+- 错误和异常信息
+- 队列处理统计
+
+## 使用场景
+
+- **用户通知**: 注册欢迎邮件、密码重置、系统通知
+- **营销邮件**: 新闻通讯、产品更新、促销活动
+- **交易邮件**: 订单确认、发货通知、发票
+- **报告邮件**: 定期生成并发送统计报告
+- **警报邮件**: 系统异常、安全警告、监控告警
+- **工作流通知**: 审批通知、任务提醒、到期提醒
+
+## 安全注意事项
+
+1. **凭据保护**: 使用环境变量存储 SMTP 凭据，不要硬编码
+2. **邮件验证**: 验证收件人邮箱地址格式，防止发送到无效地址
+3. **速率限制**: 遵守 SMTP 提供商的发送速率限制
+4. **SPF/DKIM**: 配置 SPF 和 DKIM 记录提高邮件送达率
+5. **退订链接**: 营销邮件应包含退订链接
+6. **敏感信息**: 避免在邮件中传输敏感信息，使用加密链接
+
+## 依赖项
+
+### 主要依赖
+
+- `nodemailer`: ^7.0.11 - 邮件发送库
+- `email-addresses`: ^5.0.0 - 邮件地址解析和验证
+- `bluebird`: ^3.7.2 - Promise 增强库
+- `lodash`: ^4.17.21 - 工具函数库
+
+### Peer Dependencies
+
+- `@builder6/core`: ^3.0.10 - 核心功能模块
+- `@builder6/moleculer`: ^3.0.10 - 微服务框架
+- `@nestjs/common`: ^11.0.0 - NestJS 核心
+- `@nestjs/core`: ^11.0.0 - NestJS 核心
+- `@nestjs/swagger`: ^11.0.7 - API 文档
+
+## 开发
+
+### 构建
+
+```bash
+npm run build
+```
+
+### 监听模式
+
+```bash
+npm run build:watch
+```
+
+### 格式化代码
+
+```bash
+npm run format
+```
+
+## 故障排查
+
+### 常见问题
 
-B6_EMAIL_ENABLED 时会启动定时发送任务，从 _mail_queue 集合中读取邮件发送任务，发送成功后删除任务。
+1. **邮件发送失败**: 检查 SMTP 配置和网络连接
+2. **认证失败**: 验证用户名和密码是否正确
+3. **被拒绝发送**: 检查是否超过了发送限制
+4. **邮件进入垃圾箱**: 配置 SPF、DKIM 和 DMARC 记录
+5. **队列积压**: 增加批量大小或减少检查间隔
 
-以下环境变量非必须配置。
+## License
 
-```shell
-STEEDOS_EMAIL_QUEUE_INTERVAL=3000 # 邮件定时器，单位：毫秒, 默认值：3000
-STEEDOS_EMAIL_QUEUE_BATCH_SIZE=1 # 邮件队列批量发送数量，默认值：1
-STEEDOS_EMAIL_QUEUE_TIMEOUT=60000 # 邮件队列超时时间，单位：毫秒，默认值：60000
-STEEDOS_EMAIL_QUEUE_KEEPS=false # 邮件发送之后是否保留邮件队列，默认值：false
-```
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@builder6/email",
-  "version": "3.2.3",
+  "version": "4.0.0",
   "main": "dist/index.js",
   "license": "MIT",
   "files": [
@@ -18,8 +18,8 @@
     "nodemailer": "^7.0.11"
   },
   "peerDependencies": {
-    "@builder6/core": "^3.0.10",
-    "@builder6/moleculer": "^3.0.10",
+    "@builder6/core": "^4.0.0",
+    "@builder6/moleculer": "^4.0.0",
     "@nestjs/common": "^11.0.0",
     "@nestjs/core": "^11.0.0",
     "@nestjs/swagger": "^11.0.7"
@@ -27,7 +27,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "544e8b41e82e41a3a7534cd30219c00d60285c63",
+  "gitHead": "6d6e13fed8d4b3c6de14f84dcb6287c5661ea6f6",
   "devDependencies": {
     "@types/bluebird": "^3.5.42"
   }