Next.js 的 API 路由文件（route.ts）的核心拆解

D:\trea\ployment\project24\Foresight-beta\apps\web\src\app\api\email-otp\request\route.ts

这是一个 Next.js 的 API 路由文件 ，用于处理 发送邮箱验证码 的请求。

它是后端逻辑的一部分，主要用于 绑定邮箱到钱包地址 时的身份验证。

1. 这个文件做什么？怎么做的？

- 做什么 ：接收前端发来的“发送验证码”请求（包含邮箱和钱包地址），生成一个 6 位数字验证码，通过 SMTP 邮件服务发送给用户，并将验证码临时存储在服务器内存中以便后续验证。
- 怎么做的 ：
1. 身份核验 ：检查请求者的 Session（Cookie）是否与请求中的钱包地址一致，防止冒充。
2. 生成与存储 ：生成随机 6 位数，存入全局内存对象（ globalThis ，通过 getEmailOtpShared 获取），设置 15 分钟有效期。
3. 邮件发送 ：使用 nodemailer 库连接配置好的 SMTP 服务器（如 Gmail, Outlook 等）发送邮件。
4. 开发环境后门 ：如果是开发环境且邮件发送失败，它会直接把验证码返回给前端（方便调试）。

2. 核心功能

1. 安全性检查 ： getSessionAddress(req) 确保发起请求的用户确实拥有该钱包地址的会话。
2. 防刷/限流 ：检查 rec.lockUntil ，如果用户请求太频繁会被锁定（返回 429）。
3. 验证码生命周期管理 ：生成、存储、过期时间（15分钟）。
4. 邮件发送服务 ：封装 SMTP 发送逻辑。

3. 怎么找？（关联文件位置）

- 前端调用（Frontend） ：

- 位置： apps/web/src/components/WalletModal.tsx (约 329 行)
- 代码特征： fetch('/api/email-otp/request', ...)
- 注意：项目中有两套验证码逻辑， LoginModal 用的是 Supabase，而这个 API 是自定义的，主要在 WalletModal 中使用。
- 共享工具/存储（Shared Utils） ：

- 位置： apps/web/src/lib/serverUtils.ts
- 内容：定义了内存存储结构 ( getEmailOtpShared ) 和 Session 解析逻辑。
- 配置文件（Config） ：

- 位置：项目根目录 .env 文件
- 关键词： SMTP_HOST , SMTP_PORT , SMTP_USER , SMTP_PASS 。

4. 梳理执行逻辑

输入 ：POST 请求，Body JSON { email: "...", walletAddress: "..." }

流程图解 ：

1. 初始化

- 获取全局共享存储 store 和日志 logs 。
- 解析 Body 获取 email 和 walletAddress 。
2. 前置校验 (Validation)

- Cookie 校验 ：从 Cookie 解析 fs_session ，对比其地址与 Body 中的 walletAddress 是否一致。不一致 $\rightarrow$ 401 Unauthorized 。
- 格式校验 ：检查邮箱格式。错误 $\rightarrow$ 400 Bad Request 。
3. 状态检查 (State Check)

- 从 store 获取该邮箱的记录。
- 锁定检查 ：如果当前时间 < lockUntil ，说明被锁定。 $\rightarrow$ 429 Too Many Requests 。
4. 生成与更新 (Update)

- 生成 6 位随机码 genCode() 。
- 更新内存记录：设置 code ， expiresAt (当前时间+15分钟)，记录发送时间。
- 写入 store 。
5. 发送邮件 (IO Action)

- 记录日志 status: 'queued' 。
- 调用 sendMailSMTP 。
- 成功 ：记录日志 status: 'sent' $\rightarrow$ 返回 200 OK { success: true } 。
- 失败 (Exception) ：
- 记录错误日志。
- 开发环境特权 ：如果 NODE_ENV !== 'production' ，返回 200 OK 但附带 codePreview （直接把验证码告诉你）。
- 生产环境 ：返回 500 Internal Server Error 。