core_wing_web/邮件发送测试说明.md

# 邮件发送测试说明

## 📧 功能概述

项目已集成邮件发送功能，支持：
- 简单文本邮件
- HTML格式邮件
- 验证码邮件（带精美HTML模板）

## 🔧 配置步骤

### 1. 邮箱配置

在 `src/main/resources/application.properties` 中配置邮件服务器信息：

```properties
# 邮件配置
spring.mail.host=smtp.chengmail.cn          # SMTP服务器地址
spring.mail.port=465                        # SMTP端口
spring.mail.username=dev@corewing.com       # 发件人邮箱
spring.mail.password=HRTmmNrBRjSxfwAk       # 邮箱授权码
spring.mail.default-encoding=UTF-8
spring.mail.properties.mail.smtp.auth=true
spring.mail.properties.mail.smtp.starttls.enable=true
spring.mail.properties.mail.smtp.starttls.required=true
spring.mail.properties.mail.smtp.ssl.enable=false
```

### 2. 常用邮箱SMTP配置

#### QQ邮箱
```properties
spring.mail.host=smtp.qq.com
spring.mail.port=587  # 或 465 (SSL)
spring.mail.username=your_email@qq.com
spring.mail.password=your_authorization_code
```

**获取QQ邮箱授权码：**
1. 登录QQ邮箱网页版
2. 设置 -> 账户
3. 开启 "POP3/SMTP服务" 或 "IMAP/SMTP服务"
4. 生成授权码（16位字符）

#### 163邮箱
```properties
spring.mail.host=smtp.163.com
spring.mail.port=465
spring.mail.username=your_email@163.com
spring.mail.password=your_authorization_code
```

#### Gmail
```properties
spring.mail.host=smtp.gmail.com
spring.mail.port=587
spring.mail.username=your_email@gmail.com
spring.mail.password=your_app_password
```

#### 企业邮箱（腾讯企业邮箱为例）
```properties
spring.mail.host=smtp.exmail.qq.com
spring.mail.port=465
spring.mail.username=your_email@your_domain.com
spring.mail.password=your_password
```

## 🧪 运行测试

### 方法一：使用IDE运行

1. 打开测试文件：`src/test/java/com/corewing/app/util/EmailUtilTest.java`

2. 修改测试邮箱地址：
   ```java
   String to = "test@example.com";  // 改为你的邮箱
   ```

3. 运行测试方法：
   - `testSendSimpleMail()` - 测试简单文本邮件
   - `testSendHtmlMail()` - 测试HTML邮件
   - `testSendVerifyCode()` - 测试验证码邮件
   - `testSendMultipleVerifyCode()` - 测试批量发送

### 方法二：使用Gradle命令行

```bash
# 运行所有邮件测试
./gradlew test --tests EmailUtilTest

# 运行单个测试方法
./gradlew test --tests EmailUtilTest.testSendVerifyCode
```

## 📝 测试示例

### 1. 简单文本邮件测试

```java
@Test
public void testSendSimpleMail() {
    String to = "your_email@example.com";
    String subject = "【CoreWing】简单文本邮件测试";
    String content = "这是一封测试邮件";

    boolean success = emailUtil.sendSimpleMail(to, subject, content);
    System.out.println(success ? "发送成功" : "发送失败");
}
```

### 2. 验证码邮件测试

```java
@Test
public void testSendVerifyCode() {
    String to = "your_email@example.com";
    String code = "123456";

    boolean success = emailUtil.sendVerifyCode(to, code);
    System.out.println(success ? "发送成功" : "发送失败");
}
```

## ✅ 预期结果

### 成功标志
```
✅ 验证码邮件发送成功！
   收件人: test@example.com
   验证码: 123456
   请检查收件箱（可能在垃圾邮件中）
```

### 验证码邮件样式
邮件将以精美的HTML格式展示：
- 紫色渐变标题
- 大字号验证码显示
- 友好的提示信息
- 有效期说明（5分钟）

## ❌ 常见问题

### 1. 发送失败：认证失败
**错误信息：** `Authentication failed`

**解决方法：**
- 确认邮箱授权码是否正确（不是邮箱密码！）
- QQ邮箱需要开启SMTP服务并生成授权码
- 检查用户名格式是否正确（完整邮箱地址）

### 2. 发送失败：连接超时
**错误信息：** `Connection timed out`

**解决方法：**
- 检查网络连接
- 确认SMTP服务器地址和端口是否正确
- 检查防火墙设置
- 尝试切换端口（587/465/25）

### 3. 发送失败：SSL错误
**错误信息：** `SSL handshake failed`

**解决方法：**
- 端口465使用SSL，需要设置 `spring.mail.properties.mail.smtp.ssl.enable=true`
- 端口587使用TLS，需要设置 `spring.mail.properties.mail.smtp.starttls.enable=true`

### 4. 邮件进入垃圾箱
**解决方法：**
- 这是正常现象，测试邮件可能被识别为垃圾邮件
- 在垃圾箱中将发件人标记为"非垃圾邮件"
- 添加发件人到通讯录

### 5. QQ邮箱授权码获取失败
**解决方法：**
1. 进入QQ邮箱网页版
2. 设置 -> 账户 -> POP3/IMAP/SMTP/Exchange/CardDAV/CalDAV服务
3. 开启"POP3/SMTP服务"
4. 通过密保验证后生成授权码
5. 授权码仅显示一次，请妥善保存

## 🔒 安全建议

1. **不要将授权码提交到代码仓库**
   - 使用环境变量或配置中心管理敏感信息
   - 在 `.gitignore` 中添加 `application.properties`

2. **生产环境配置**
   ```properties
   # 使用环境变量
   spring.mail.username=${MAIL_USERNAME}
   spring.mail.password=${MAIL_PASSWORD}
   ```

3. **限流保护**
   - 建议添加发送频率限制
   - 防止被恶意利用大量发送邮件

## 📊 测试检查清单

- [ ] 配置文件中邮箱信息填写正确
- [ ] 邮箱SMTP服务已开启
- [ ] 授权码获取成功
- [ ] 网络连接正常
- [ ] 测试邮箱地址修改为实际邮箱
- [ ] 运行测试方法
- [ ] 检查收件箱（包括垃圾邮件）
- [ ] 验证邮件内容和格式

## 🎯 实际应用

在验证码功能中的使用：

```java
// 发送邮箱验证码
POST /user/sendCode
{
  "account": "user@example.com",
  "type": "register"
}
```

系统将自动：
1. 生成6位随机验证码
2. 存储到Redis（有效期5分钟）
3. 发送精美的HTML邮件到用户邮箱
4. 用户输入验证码完成验证

## 📚 相关文档

- [Spring Boot Mail 官方文档](https://docs.spring.io/spring-boot/docs/current/reference/html/io.html#io.email)
- [API接口说明.md](./API接口说明.md) - 查看完整的API文档
- [CLAUDE.md](./CLAUDE.md) - 项目开发指南

## 💡 提示

- 首次测试建议使用 `testSendVerifyCode()` 方法
- 确保收件人邮箱地址正确
- 检查垃圾邮件箱
- 测试成功后可以通过API接口测试完整流程