feat: 实现邮箱验证码登录和腾讯云SES集成
- 实现邮箱验证码登录功能，支持自动注册新用户 - 修复验证码生成逻辑，确保前后端验证码一致 - 添加腾讯云SES webhook回调接口，支持6种邮件事件 - 配置ngrok内网穿透支持，允许外部访问 - 优化登录页面UI，采用全屏背景和居中布局 - 清理调试代码和未使用的导入 - 添加完整的配置文档和测试脚本
This commit is contained in:
AIGC Developer
247
demo/TENCENT_SES_WEBHOOK_DESIGN.md
Normal file
247
demo/TENCENT_SES_WEBHOOK_DESIGN.md
Normal file
@@ -0,0 +1,247 @@
|
||||
# 腾讯云SES邮件验证回调路径设计
|
||||
|
||||
## 📧 **回调接口设计**
|
||||
|
||||
### 🔗 **回调地址**
|
||||
```
|
||||
POST /api/tencent/ses/webhook
|
||||
```
|
||||
|
||||
### 🌐 **完整URL示例**
|
||||
```
|
||||
https://your-domain.com/api/tencent/ses/webhook
|
||||
```
|
||||
|
||||
## 🔧 **腾讯云控制台配置**
|
||||
|
||||
### 1️⃣ **配置步骤**
|
||||
1. 登录腾讯云邮件推送控制台
|
||||
2. 导航至"邮件配置" > "回调配置" > "回调地址配置"
|
||||
3. 选择回调级别：
|
||||
- **账户级回调**：对该账户下所有发信地址生效
|
||||
- **发信地址级回调**：仅对指定发信地址生效（优先级更高）
|
||||
4. 输入回调地址：`https://your-domain.com/api/tencent/ses/webhook`
|
||||
5. 保存配置
|
||||
|
||||
### 2️⃣ **端口要求**
|
||||
- 仅支持端口：**8080**, **8081**, **8082**
|
||||
- 必须使用HTTPS协议
|
||||
- 确保回调地址可公网访问
|
||||
|
||||
## 📊 **支持的事件类型**
|
||||
|
||||
| 事件类型 | 描述 | 触发时机 |
|
||||
|---------|------|---------|
|
||||
| `delivery` | 递送成功 | 邮件成功送达收件人邮箱 |
|
||||
| `reject` | 腾讯云拒信 | 由于腾讯云策略原因被拒绝发送 |
|
||||
| `bounce` | ESP退信 | 邮件被收件人邮箱服务提供商退回 |
|
||||
| `open` | 用户打开邮件 | 收件人打开了邮件 |
|
||||
| `click` | 点击链接 | 收件人点击了邮件中的链接 |
|
||||
| `unsubscribe` | 退订 | 收件人选择退订邮件 |
|
||||
|
||||
## 📝 **回调数据格式**
|
||||
|
||||
### 基础数据结构
|
||||
```json
|
||||
{
|
||||
"eventType": "delivery",
|
||||
"messageId": "0000014a-f4d4-4f4f-8f4f-4f4f4f4f4f4f-000000",
|
||||
"email": "user@example.com",
|
||||
"timestamp": "2024-01-01T12:00:00.000Z"
|
||||
}
|
||||
```
|
||||
|
||||
### 递送成功事件
|
||||
```json
|
||||
{
|
||||
"eventType": "delivery",
|
||||
"messageId": "0000014a-f4d4-4f4f-8f4f-4f4f4f4f4f4f-000000",
|
||||
"email": "user@example.com",
|
||||
"timestamp": "2024-01-01T12:00:00.000Z"
|
||||
}
|
||||
```
|
||||
|
||||
### 拒信事件
|
||||
```json
|
||||
{
|
||||
"eventType": "reject",
|
||||
"messageId": "0000014a-f4d4-4f4f-8f4f-4f4f4f4f4f4f-000000",
|
||||
"email": "user@example.com",
|
||||
"reason": "Content policy violation",
|
||||
"timestamp": "2024-01-01T12:00:00.000Z"
|
||||
}
|
||||
```
|
||||
|
||||
### 退信事件
|
||||
```json
|
||||
{
|
||||
"eventType": "bounce",
|
||||
"messageId": "0000014a-f4d4-4f4f-8f4f-4f4f4f4f4f4f-000000",
|
||||
"email": "user@example.com",
|
||||
"bounceType": "Permanent",
|
||||
"bounceSubType": "General",
|
||||
"timestamp": "2024-01-01T12:00:00.000Z"
|
||||
}
|
||||
```
|
||||
|
||||
### 打开事件
|
||||
```json
|
||||
{
|
||||
"eventType": "open",
|
||||
"messageId": "0000014a-f4d4-4f4f-8f4f-4f4f4f4f4f4f-000000",
|
||||
"email": "user@example.com",
|
||||
"timestamp": "2024-01-01T12:00:00.000Z",
|
||||
"userAgent": "Mozilla/5.0...",
|
||||
"ipAddress": "192.168.1.1"
|
||||
}
|
||||
```
|
||||
|
||||
### 点击事件
|
||||
```json
|
||||
{
|
||||
"eventType": "click",
|
||||
"messageId": "0000014a-f4d4-4f4f-8f4f-4f4f4f4f4f4f-000000",
|
||||
"email": "user@example.com",
|
||||
"timestamp": "2024-01-01T12:00:00.000Z",
|
||||
"link": "https://example.com/click",
|
||||
"userAgent": "Mozilla/5.0...",
|
||||
"ipAddress": "192.168.1.1"
|
||||
}
|
||||
```
|
||||
|
||||
### 退订事件
|
||||
```json
|
||||
{
|
||||
"eventType": "unsubscribe",
|
||||
"messageId": "0000014a-f4d4-4f4f-8f4f-4f4f4f4f4f4f-000000",
|
||||
"email": "user@example.com",
|
||||
"timestamp": "2024-01-01T12:00:00.000Z",
|
||||
"unsubscribeType": "one-click"
|
||||
}
|
||||
```
|
||||
|
||||
## 🔒 **安全验证**
|
||||
|
||||
### 请求头验证
|
||||
```http
|
||||
X-Tencent-Token: your-token
|
||||
X-Tencent-Timestamp: 1640995200
|
||||
X-Tencent-Signature: calculated-signature
|
||||
```
|
||||
|
||||
### 签名验证流程
|
||||
1. 获取请求头中的Token、时间戳、签名
|
||||
2. 验证时间戳（防止重放攻击）
|
||||
3. 使用预共享密钥计算签名
|
||||
4. 对比签名是否一致
|
||||
|
||||
## 🚀 **ngrok测试配置**
|
||||
|
||||
### 1️⃣ **启动ngrok**
|
||||
```bash
|
||||
# 穿透后端端口8080
|
||||
ngrok http 8080
|
||||
```
|
||||
|
||||
### 2️⃣ **获取公网地址**
|
||||
```
|
||||
Forwarding https://abc123.ngrok.io -> http://localhost:8080
|
||||
```
|
||||
|
||||
### 3️⃣ **配置回调地址**
|
||||
```
|
||||
https://abc123.ngrok.io/api/tencent/ses/webhook
|
||||
```
|
||||
|
||||
### 4️⃣ **测试回调**
|
||||
```bash
|
||||
curl -X POST https://abc123.ngrok.io/api/tencent/ses/webhook \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "X-Tencent-Token: test-token" \
|
||||
-H "X-Tencent-Timestamp: 1640995200" \
|
||||
-H "X-Tencent-Signature: test-signature" \
|
||||
-d '{
|
||||
"eventType": "delivery",
|
||||
"messageId": "test-123",
|
||||
"email": "test@example.com",
|
||||
"timestamp": "2024-01-01T12:00:00.000Z"
|
||||
}'
|
||||
```
|
||||
|
||||
## 📋 **业务处理逻辑**
|
||||
|
||||
### 递送成功处理
|
||||
- 更新邮件状态为"已送达"
|
||||
- 记录递送统计
|
||||
- 更新用户活跃度
|
||||
- 触发后续营销流程
|
||||
|
||||
### 拒信处理
|
||||
- 记录拒信原因
|
||||
- 检查邮件内容合规性
|
||||
- 更新发送策略
|
||||
- 通知管理员
|
||||
|
||||
### 退信处理
|
||||
- 区分硬退信和软退信
|
||||
- 硬退信：从邮件列表移除
|
||||
- 软退信：标记重试
|
||||
- 更新邮箱有效性状态
|
||||
|
||||
### 打开/点击处理
|
||||
- 记录用户行为统计
|
||||
- 分析用户兴趣
|
||||
- 更新用户画像
|
||||
- 触发个性化推荐
|
||||
|
||||
### 退订处理
|
||||
- 立即停止发送邮件
|
||||
- 更新用户订阅状态
|
||||
- 记录退订原因
|
||||
- 发送退订确认
|
||||
|
||||
## ⚠️ **注意事项**
|
||||
|
||||
1. **重试机制**：腾讯云SES会重试失败的回调，最多3次
|
||||
2. **响应要求**：必须返回HTTP 200状态码
|
||||
3. **处理时间**：建议在5秒内完成处理
|
||||
4. **幂等性**：确保重复回调不会产生副作用
|
||||
5. **日志记录**：详细记录所有回调事件
|
||||
6. **监控告警**：设置回调失败告警机制
|
||||
|
||||
## 🔧 **扩展功能**
|
||||
|
||||
### 数据库设计
|
||||
```sql
|
||||
-- 邮件事件表
|
||||
CREATE TABLE email_events (
|
||||
id BIGINT PRIMARY KEY AUTO_INCREMENT,
|
||||
message_id VARCHAR(255) NOT NULL,
|
||||
email VARCHAR(255) NOT NULL,
|
||||
event_type VARCHAR(50) NOT NULL,
|
||||
event_data JSON,
|
||||
timestamp DATETIME NOT NULL,
|
||||
created_at DATETIME DEFAULT CURRENT_TIMESTAMP
|
||||
);
|
||||
|
||||
-- 邮件统计表
|
||||
CREATE TABLE email_statistics (
|
||||
id BIGINT PRIMARY KEY AUTO_INCREMENT,
|
||||
email VARCHAR(255) NOT NULL,
|
||||
total_sent INT DEFAULT 0,
|
||||
total_delivered INT DEFAULT 0,
|
||||
total_opened INT DEFAULT 0,
|
||||
total_clicked INT DEFAULT 0,
|
||||
total_bounced INT DEFAULT 0,
|
||||
last_activity DATETIME,
|
||||
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
|
||||
);
|
||||
```
|
||||
|
||||
### 监控指标
|
||||
- 回调成功率
|
||||
- 事件处理延迟
|
||||
- 各事件类型分布
|
||||
- 错误率统计
|
||||
|
||||
现在您有了一个完整的腾讯云SES邮件验证回调路径设计！
|
||||
Reference in New Issue
Block a user