fix: SMTP 465/SSL support + add SMTP config to .env.example and 备忘录

Author: zcj220

.env.example

@@ -30,6 +30,24 @@ TP_SERVER_HOST=0.0.0.0
 TP_SERVER_PORT=8900
 TP_SERVER_LOG_LEVEL=INFO
 
+# ── 邮件验证码 ──────────────────────────────────
+# 注册时发送验证码邮件（不配置则走开发模式，验证码直接返回在 API 响应中）
+# REQUIRE_EMAIL_VERIFICATION=true   ← 上线前改为 true
+REQUIRE_EMAIL_VERIFICATION=false
+#
+# 企业邮 SMTP（以腾讯企业邮为例）
+# SMTP_HOST=smtp.exmail.qq.com         # 腾讯企业邮
+# SMTP_HOST=smtp.mxhichina.com         # 阿里云企业邮
+# SMTP_PORT=465                        # 465=SSL, 587=TLS/STARTTLS
+# SMTP_USER=no-reply@xinzaoai.com
+# SMTP_PASS=邮箱密码或授权码
+# SMTP_FROM=no-reply@xinzaoai.com      # 默认等于 SMTP_USER，可省略
+SMTP_HOST=
+SMTP_PORT=465
+SMTP_USER=
+SMTP_PASS=
+SMTP_FROM=
+
 # ── 支付（预留） ────────────────────────────────
 PAYMENT_WEBHOOK_SECRET=
 

src/auth/service.py

@@ -511,10 +511,17 @@ def send_verification_email(email: str, code: str) -> bool:
     msg["From"] = from_email
     msg["To"] = email
     try:
-        with smtplib.SMTP(smtp_host, smtp_port, timeout=10) as server:
-            server.starttls()
-            server.login(smtp_user, smtp_pass)
-            server.sendmail(from_email, [email], msg.as_string())
+        if smtp_port == 465:
+            # 端口 465：直接 SSL
+            with smtplib.SMTP_SSL(smtp_host, smtp_port, timeout=10) as server:
+                server.login(smtp_user, smtp_pass)
+                server.sendmail(from_email, [email], msg.as_string())
+        else:
+            # 端口 587：STARTTLS
+            with smtplib.SMTP(smtp_host, smtp_port, timeout=10) as server:
+                server.starttls()
+                server.login(smtp_user, smtp_pass)
+                server.sendmail(from_email, [email], msg.as_string())
         logger.info("验证码邮件已发送 → {}", email)
         return True
     except Exception as e:

开发备忘录.md

@@ -2652,6 +2652,56 @@ sudo systemctl restart nginx
 | 443 | TCP | HTTPS | 腾讯云防火墙 |
 | 3306 | - | MySQL | 阿里云 RDS 白名单添加 82.157.97.179 |
 
+### 15.6 邮件验证码（SMTP）配置
+
+#### 当前状态
+- **开发模式**（`REQUIRE_EMAIL_VERIFICATION=false`）：服务器把验证码直接附在 API 响应的 `dev_code` 字段里，插件自动填入，用户无需收邮件。⚠️ 上线前必须开启真实发信。
+- 发件邮箱：`no-reply@xinzaoai.com`（企业邮箱，已注册）
+- 后端代码：`src/auth/service.py → send_verification_email()` 已完整实现，只需配置环境变量。
+
+#### 上线前操作（一次性）
+
+1. **登录企业邮箱后台**，找到 SMTP 信息（服务器地址、端口、密码/授权码）
+
+2. **更新服务器环境变量**（SSH 到服务器后编辑 .env）：
+
+```bash
+ssh -i key/TestPilotAi.pem ubuntu@82.157.97.179
+sudo nano /opt/testpilot/app/.env
+```
+
+  在 .env 中加入（以腾讯企业邮为例）：
+  ```
+  REQUIRE_EMAIL_VERIFICATION=true
+  SMTP_HOST=smtp.exmail.qq.com
+  SMTP_PORT=465
+  SMTP_USER=no-reply@xinzaoai.com
+  SMTP_PASS=你的邮箱密码
+  SMTP_FROM=no-reply@xinzaoai.com
+  ```
+
+  其他常见企业邮 SMTP 地址：
+  | 邮箱服务商 | SMTP_HOST | SMTP_PORT |
+  |----------|-----------|-----------|
+  | 腾讯企业邮 | smtp.exmail.qq.com | 465（SSL） |
+  | 阿里云企业邮 | smtp.mxhichina.com | 465（SSL） |
+  | 网易企业邮 | smtp.qiye.163.com | 465（SSL） |
+
+3. **重启服务**：
+```bash
+sudo systemctl restart testpilot-api
+sudo systemctl status testpilot-api
+```
+
+4. **验证**：注册新账号，邮箱收到"【TestPilot AI】注册验证码 XXXXXX"邮件即成功
+
+#### 关键技术细节
+- 验证码有效期：10 分钟，使用一次即失效
+- 发送内容：主题 `【TestPilot AI】注册验证码 {code}`，正文纯文本
+- 代码位置：`src/auth/service.py` → `send_verification_email(email, code)`
+- 使用 `smtplib.SMTP` + `starttls()`（端口587）或先 `smtplib.SMTP_SSL`（端口465）
+- ⚠️ 当前代码对 465/SSL 和 587/TLS 的处理：统一走 `starttls()`，如果企业邮要求 465 纯 SSL，需要改用 `smtplib.SMTP_SSL`
+
 ---
 
 ### iOS 真机测试完整验证（2026-03-15）