# 邮件发送工具模块文档
## 1. 模块概述
该模块基于 `nodemailer` 实现邮件发送功能，并提供注册验证码、重置密码验证码两类邮件的HTML模板生成能力，适用于系统中的邮件通知场景（如用户注册、密码重置）。

## 2. 依赖
- 第三方库：`nodemailer`（需提前安装）
- 全局配置：`Chan.config` 需包含 `EMAIL`（邮件服务配置）和 `APP_NAME`（应用名称）字段

## 3. 配置说明
`Chan.config.EMAIL` 需包含以下配置项：

| 配置项 | 类型 | 说明 |
|--------|------|------|
| HOST | string | 邮件服务器主机地址（如 smtp.qq.com） |
| PORT | string/number | 邮件服务器端口（如 465、587） |
| SECURE | string | 是否启用SSL加密（"true" 或 "false"） |
| USER | string | 发件人邮箱账号 |
| PASS | string | 发件人邮箱授权码/密码 |
| FROM | string | 发件人显示格式（如 "应用名称 <xxx@xxx.com>"） |

## 4. API 详情
### 4.1 sendMail - 发送邮件
#### 功能描述
创建邮件传输器，验证邮件服务配置后发送邮件，支持纯文本和HTML格式内容。

#### 函数签名
```javascript
async function sendMail(to, subject, text, html = null) => Promise<Object>
```

#### 参数说明
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| to | string | 是 | - | 收件人邮箱地址 |
| subject | string | 是 | - | 邮件主题 |
| text | string | 是 | - | 邮件纯文本内容 |
| html | string \| null | 否 | null | 邮件HTML内容，未传则使用text内容替代 |

#### 返回值
`Promise<Object>`：nodemailer 发送邮件后的响应对象（包含 messageId 等信息）。

#### 异常抛出
- 邮件服务配置验证失败：抛出 `Error("邮件服务未配置")`
- 邮件发送失败：打印错误日志并抛出原错误对象

#### 使用示例
```javascript
import { sendMail, genRegEmailHtml } from './chanjs/common/email.js';

// 发送注册验证码邮件
async function sendRegCodeEmail(email, code) {
  const subject = `${Chan.config.APP_NAME} 注册验证码`;
  const text = `您的注册验证码是：${code}，有效期10分钟。`;
  const html = genRegEmailHtml(code);
  
  try {
    const result = await sendMail(email, subject, text, html);
    console.log("邮件发送成功：", result.messageId);
  } catch (error) {
    console.error("发送失败：", error);
  }
}
```

### 4.2 genRegEmailHtml - 生成注册验证码邮件HTML模板
#### 功能描述
生成美观的注册验证码邮件HTML字符串，包含应用名称、验证码、有效期等信息。

#### 函数签名
```javascript
function genRegEmailHtml(code, minutes = 10) => string
```

#### 参数说明
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| code | string | 是 | - | 注册验证码 |
| minutes | number | 否 | 10 | 验证码有效期（分钟） |

#### 返回值
`string`：完整的邮件HTML字符串。

### 4.3 genResetPasswordEmail - 生成重置密码邮件HTML模板
#### 功能描述
生成重置密码验证码的邮件HTML字符串，样式与注册邮件区分，突出重置密码场景。

#### 函数签名
```javascript
function genResetPasswordEmail(code, minutes = 10) => string
```

#### 参数说明
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| code | string | 是 | - | 重置密码验证码 |
| minutes | number | 否 | 10 | 验证码有效期（分钟） |

#### 返回值
`string`：完整的邮件HTML字符串。

## 5. 模板样式说明
- 注册邮件模板：头部背景色为蓝色（#007bff），最大宽度750px，整体风格简洁清晰。
- 重置密码邮件模板：头部背景色为绿色（#28a745），最大宽度600px，布局与注册邮件一致，文案适配重置密码场景。
- 两类模板均包含：应用名称、验证码醒目展示、有效期提示、版权信息，适配主流邮箱的HTML渲染规则。

## 6. 异常处理建议
1. 调用 `sendMail` 时务必使用 `try/catch` 捕获异常，避免程序崩溃；
2. 邮件服务配置错误（如HOST/PORT错误）会触发“邮件服务未配置”异常，需检查 `Chan.config.EMAIL` 配置；
3. 发送失败（如收件人邮箱格式错误、服务器拒绝）需记录详细错误日志，便于排查问题。

## 7. 扩展建议
1. 可新增更多邮件模板（如通知类、营销类），参考现有模板结构封装；
2. 可添加邮件发送重试机制，提升稳定性；
3. 可将模板样式抽离为配置项，支持自定义主题色、模板宽度等。