0.0.8.0

docs/EMAIL_CONFIGURATION.md

@@ -0,0 +1,212 @@
+# 邮箱服务配置说明
+
+## 📧 当前配置
+
+本项目使用 **163 邮箱** 作为 SMTP 服务器，用于发送协作邀请邮件。
+
+### 配置信息
+
+```env
+SMTP_HOST="smtp.163.com"
+SMTP_PORT="465"
+SMTP_USER="cftservice@163.com"
+SMTP_PASS="SChncqpqS9TDPUD2"
+SMTP_FROM="中华家谱 <cftservice@163.com>"
+```
+
+## 🔧 配置步骤
+
+### 1. 环境变量配置
+
+在项目根目录的 `.env` 文件中添加以上配置。
+
+### 2. 163 邮箱设置
+
+#### 2.1 开启 SMTP 服务
+1. 登录 163 邮箱
+2. 进入 **设置** → **POP3/SMTP/IMAP**
+3. 开启 **SMTP 服务**
+4. 获取授权密码（不是邮箱登录密码）
+
+#### 2.2 授权密码
+- 当前使用的授权密码：`SChncqpqS9TDPUD2`
+- ⚠️ **安全提示**：请勿将此密码泄露给他人
+
+### 3. 端口说明
+
+| 端口 | 加密方式 | 说明 |
+|------|---------|------|
+| 465 | SSL/TLS | 推荐使用（当前配置） |
+| 25 | 无加密 | 不推荐 |
+| 587 | STARTTLS | 可选 |
+
+## 📨 邮件功能
+
+### 当前支持的邮件类型
+
+1. **协作邀请邮件**
+   - 邀请用户加入家族树
+   - 发送初始密码（新用户）
+   - 提供登录链接
+
+### 邮件模板
+
+邮件模板位于：`/lib/mail.ts`
+
+```typescript
+export async function sendInvitationEmail(
+  to: string,
+  inviterName: string,
+  treeName: string,
+  role: string,
+  password?: string
+)
+```
+
+## 🧪 测试邮件发送
+
+### 方法 1：通过 API 测试
+
+```bash
+# 测试发送邀请邮件
+curl -X POST http://localhost:3000/api/trees/[treeId]/invite \
+  -H "Content-Type: application/json" \
+  -d '{
+    "email": "test@example.com",
+    "role": "VIEWER"
+  }'
+```
+
+### 方法 2：通过界面测试
+
+1. 登录系统
+2. 进入任一家族树
+3. 点击 **设置** → **协作者管理**
+4. 添加协作者并发送邀请
+
+## 🔍 故障排查
+
+### 常见问题
+
+#### 1. 邮件发送失败
+
+**可能原因**：
+- SMTP 服务未开启
+- 授权密码错误
+- 网络连接问题
+- 163 邮箱被限制发送
+
+**解决方案**：
+```bash
+# 检查环境变量
+echo $SMTP_USER
+echo $SMTP_HOST
+
+# 查看应用日志
+tail -f logs/app.log
+```
+
+#### 2. 邮件被标记为垃圾邮件
+
+**解决方案**：
+- 配置 SPF 记录
+- 配置 DKIM 签名
+- 使用企业邮箱
+
+#### 3. 发送频率限制
+
+163 邮箱对发送频率有限制：
+- 免费邮箱：每天约 50 封
+- VIP 邮箱：每天约 500 封
+
+**建议**：
+- 使用企业邮箱
+- 或使用专业邮件服务（如 SendGrid、阿里云邮件推送）
+
+## 🔐 安全建议
+
+### 1. 保护授权密码
+
+```bash
+# 不要将 .env 文件提交到 Git
+echo ".env" >> .gitignore
+
+# 使用环境变量管理工具
+# 如：dotenv-vault, AWS Secrets Manager
+```
+
+### 2. 定期更换密码
+
+建议每 3-6 个月更换一次授权密码。
+
+### 3. 监控邮件发送
+
+```typescript
+// 添加邮件发送日志
+console.log(`邮件已发送至: ${to}`)
+console.log(`发送时间: ${new Date().toISOString()}`)
+```
+
+## 🚀 生产环境配置
+
+### 推荐方案
+
+#### 方案 1：使用企业邮箱
+- 阿里云企业邮箱
+- 腾讯企业邮箱
+- 网易企业邮箱
+
+#### 方案 2：使用专业邮件服务
+- **SendGrid**：免费额度 100 封/天
+- **阿里云邮件推送**：按量付费
+- **AWS SES**：按量付费
+
+### 配置示例（SendGrid）
+
+```env
+SMTP_HOST="smtp.sendgrid.net"
+SMTP_PORT="465"
+SMTP_USER="apikey"
+SMTP_PASS="your-sendgrid-api-key"
+SMTP_FROM="noreply@yourdomain.com"
+```
+
+## 📊 监控和日志
+
+### 添加邮件发送统计
+
+```typescript
+// lib/mail.ts
+let emailSentCount = 0
+
+export async function sendInvitationEmail(...) {
+  try {
+    await transporter.sendMail({...})
+    emailSentCount++
+    console.log(`邮件发送成功，总计: ${emailSentCount}`)
+  } catch (error) {
+    console.error('邮件发送失败:', error)
+    throw error
+  }
+}
+```
+
+## 📝 维护记录
+
+| 日期 | 操作 | 操作人 |
+|------|------|--------|
+| 2025-11-23 | 配置 163 邮箱服务 | System |
+| - | - | - |
+
+## 🔗 相关链接
+
+- [163 邮箱帮助中心](https://help.mail.163.com/)
+- [Nodemailer 文档](https://nodemailer.com/)
+- [SMTP 协议说明](https://zh.wikipedia.org/wiki/SMTP)
+
+## 📞 技术支持
+
+如遇到邮件发送问题，请：
+1. 检查环境变量配置
+2. 查看应用日志
+3. 联系系统管理员