AIGC/demo/TENCENT_SES_STARTUP_CHECKLIST.md

# 腾讯云SES邮件服务启动检查清单

## ✅ 启动前必需准备项

### 1. 腾讯云账号和凭证 ⚠️ **必需**

#### 获取步骤：
1. **登录腾讯云控制台**
   - 访问：https://console.cloud.tencent.com
   - 如无账号，需先注册

2. **获取API密钥**
   - 访问：https://console.cloud.tencent.com/cam/capi
   - 创建或查看API密钥
   - 获取以下信息：
     ```
     SecretID: 例如 AKIDz8krbsJ5yKBZQpn74WFkmLPx3gnPhESA
     SecretKey: 例如 Gu5t9xGARNpqDXcd3I4WZkFpAALPVZ7pKbNScfFsj
     ```

3. **开通SES（邮件推送）服务**
   - 访问：https://console.cloud.tencent.com/ses
   - 确保服务已开通
   - 查看是否有免费额度或已充值

### 2. 配置发信地址 ⚠️ **必需**

#### 配置步骤：
1. **创建发信地址**
   - 在SES控制台的"发信地址"中创建
   - 输入你的邮箱地址（例如：noreply@yourdomain.com）

2. **验证发信地址**
   - 腾讯云会向该邮箱发送验证邮件
   - 点击邮件中的验证链接完成验证
   - ⚠️ **重要**：只有验证通过的邮箱才能发送邮件

3. **记录已验证的发信地址**
   - 例如：`noreply@vionow.com`
   - 配置到 `application-dev.properties` 中的 `tencent.ses.from-email`

### 3. 创建邮件模板 ⚠️ **必需（生产环境）**

#### 配置步骤：
1. **访问模板管理**
   - 在SES控制台的"邮件模板"中创建

2. **创建模板**
   - 模板类型：选择"触发邮件"或"批量邮件"
   - 模板内容示例：
     ```
     您的验证码是：{{code}}
     验证码有效期5分钟，请勿泄露给他人。
     如果不是您本人操作，请忽略此邮件。
     ```
   - 在模板中使用 `{{变量名}}` 来定义可替换的变量

3. **记录模板ID**
   - 创建成功后，在模板列表中找到模板ID
   - 例如：`12345`
   - 配置到 `application-dev.properties` 中的 `tencent.ses.template-id`

### 4. 配置文件更新 ⚠️ **必需**

#### 更新 `demo/src/main/resources/application-dev.properties`：

```properties
# 腾讯云SES配置
tencent.ses.secret-id=你的SecretID                    # ⚠️ 必须配置
tencent.ses.secret-key=你的SecretKey                  # ⚠️ 必须配置
tencent.ses.region=ap-beijing                         # 可选，默认beijing
tencent.ses.from-email=已验证的发信地址               # ⚠️ 必须配置
tencent.ses.from-name=AIGC平台                        # 可选
tencent.ses.template-id=0                            # 0=开发模式，实际模板ID=生产模式
```

#### 当前配置状态检查：
- ✅ SecretID: 已配置（`AKIDz8krbsJ5yKBZQpn74WFkmLPx3gnPhESA`）
- ✅ SecretKey: 已配置
- ✅ Region: 已配置（`ap-beijing`）
- ✅ From-email: 已配置（`noreply@vionow.com`）
- ⚠️ Template-id: 当前为 `0`（开发模式）

### 5. Maven依赖检查 ✅ **已完成**

项目已包含腾讯云SDK依赖：
```xml
<dependency>
    <groupId>com.tencentcloudapi</groupId>
    <artifactId>tencentcloud-sdk-java</artifactId>
    <version>3.1.880</version>
</dependency>
```
✅ 无需额外操作

## 📋 快速检查清单

启动前请确认：

- [ ] ✅ 腾讯云账号已注册
- [ ] ✅ 已获取SecretID和SecretKey
- [ ] ✅ 已开通SES邮件推送服务
- [ ] ✅ 已创建并验证发信地址
- [ ] ✅ 配置文件 `application-dev.properties` 已更新正确的凭证
- [ ] ✅ 发信地址已配置到 `tencent.ses.from-email`
- [ ] ⚠️ 生产环境：已创建邮件模板并获取模板ID

## 🚀 启动步骤

### 方式1：开发模式启动（无需模板，推荐先测试）

**特点**：
- 不需要创建邮件模板
- 不会实际发送邮件
- 验证码会在日志中显示
- 适合本地开发测试

**配置**：
```properties
tencent.ses.template-id=0  # 保持为0
```

**启动**：
```bash
cd demo
./mvnw spring-boot:run
# 或
mvn spring-boot:run
```

**测试**：
```bash
# 调用发送验证码接口
curl -X POST http://localhost:8080/api/verification/email/send \
  -H "Content-Type: application/json" \
  -d '{"email":"your-email@example.com"}'
```

**查看日志**：
```
WARN  未配置邮件模板ID，使用开发模式。验证码: 123456, 邮箱: your-email@example.com
INFO  开发模式：邮件验证码发送到: your-email@example.com, 验证码: 123456
```

### 方式2：生产模式启动（需要模板）

**特点**：
- 实际发送邮件
- 需要配置模板ID
- 需要已验证的发信地址

**配置**：
```properties
tencent.ses.template-id=你的模板ID  # 例如: 12345
```

**启动**：
```bash
cd demo
./mvnw spring-boot:run
```

**测试**：
```bash
# 调用发送验证码接口
curl -X POST http://localhost:8080/api/verification/email/send \
  -H "Content-Type: application/json" \
  -d '{"email":"your-email@example.com"}'
```

**查看日志**：
```
INFO  开始发送邮件，收件人: your-email@example.com, 主题: 验证码, 模板ID: 12345
INFO  邮件发送成功，收件人: your-email@example.com, 消息ID: xxx
```

## 🔍 启动后验证

### 1. 检查服务是否正常启动
```bash
# 查看启动日志，确认没有错误
# 应该看到类似信息：
# Started DemoApplication in X.XXX seconds
```

### 2. 测试邮件发送功能
```bash
# 方式1：使用curl
curl -X POST http://localhost:8080/api/verification/email/send \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com"}'

# 方式2：使用前端页面
# 访问注册/登录页面，输入邮箱，点击发送验证码
```

### 3. 检查日志输出
- **开发模式**：应该看到"开发模式"相关日志
- **生产模式**：应该看到"邮件发送成功"或错误信息

## ⚠️ 常见问题排查

### 问题1：启动时报配置错误
```
Could not resolve placeholder 'tencent.ses.secret-id'
```
**解决**：检查 `application-dev.properties` 文件是否存在并配置了所有必需项

### 问题2：发送失败 - 认证错误
```
InvalidSecretId.InvalidSignature
```
**解决**：
- 检查SecretID和SecretKey是否正确
- 确认没有多余的空格或特殊字符

### 问题3：发送失败 - 发信地址未验证
```
InvalidParameter.EmailAddressNotVerified
```
**解决**：
- 确认发信地址已在腾讯云SES控制台验证
- 检查 `tencent.ses.from-email` 配置是否正确

### 问题4：发送失败 - 模板不存在
```
ResourceNotFound.TemplateNotFound
```
**解决**：
- 确认模板ID是否正确
- 检查模板是否在正确的区域创建
- 确认模板状态为"已审核通过"

### 问题5：开发模式下收不到邮件
**这是正常的！**
开发模式（template-id=0）不会实际发送邮件，只会在日志中显示验证码。

## 📝 当前配置状态

根据 `application-dev.properties`：

| 配置项 | 状态 | 说明 |
|--------|------|------|
| SecretID | ✅ 已配置 | 需要确认是否正确 |
| SecretKey | ✅ 已配置 | 需要确认是否正确 |
| Region | ✅ 已配置 | ap-beijing |
| From-email | ✅ 已配置 | noreply@vionow.com |
| Template-id | ⚠️ 开发模式 | 当前为0，如需实际发送需配置模板ID |

## 🎯 推荐启动流程

### 第一步：开发模式测试（推荐先做）
1. ✅ 确保SecretID和SecretKey已配置
2. ✅ 确保from-email已配置（即使未验证也可先测试）
3. ✅ 保持template-id=0
4. ✅ 启动服务
5. ✅ 测试发送验证码接口
6. ✅ 查看日志确认功能正常

### 第二步：配置真实发送（如需要）
1. ✅ 在腾讯云SES控制台验证发信地址
2. ✅ 创建邮件模板并获取模板ID
3. ✅ 更新template-id配置
4. ✅ 重启服务
5. ✅ 测试实际发送邮件

## 📚 参考资源

- 腾讯云SES控制台：https://console.cloud.tencent.com/ses
- API密钥管理：https://console.cloud.tencent.com/cam/capi
- 腾讯云SES文档：https://cloud.tencent.com/document/product/1288

## ✅ 总结

**最小启动要求**：
1. ✅ SecretID和SecretKey（已配置）
2. ✅ From-email地址（已配置，需确认已验证）
3. ✅ Template-id=0（开发模式，已配置）

**当前状态**：**可以直接启动**（开发模式）

如果需要实际发送邮件，需要：
- 验证发信地址
- 创建邮件模板并配置template-id