邮件服务与验证码中心

sequenceDiagram
    autonumber
    actor User as 用户客户端
    participant Server as 业务 API 控制器
    participant VS as VerificationService
    participant Redis as Redis / 内存存储
    participant SMTP as SMTP 邮件中继

    User->>Server: 请求发送验证码 (POST /api/v1/s/auth/ext/send-code)
    Server->>VS: 调用 save_code(scope, identifier, code)
    VS->>Redis: 检查 60s 冷却键是否存在？
    alt 处于冷却期内
        Redis-->>VS: 冷却键存在
        VS-->>Server: 抛出 AppError::Validation("请等待60秒后再试")
        Server-->>User: HTTP 422 提示频繁操作
    else 冷却期已过
        VS->>Redis: 写入验证码 (TTL: 300s) 并设置 60s 冷却标记
        VS-->>Server: 验证码保存成功
        Server->>SMTP: 调用 send_email(to, subject, body)
        SMTP-->>User: 投递包含 6 位验证码的邮件
        Server-->>User: HTTP 200 验证码已发送
    end

    User->>Server: 提交验证码与业务数据进行核销 (POST /verify)
    Server->>VS: 调用 verify_code(scope, identifier, code)
    VS->>Redis: 查询比对并原子删除 (One-Time Use)
    alt 验证码正确
        VS-->>Server: 校验通过
        Server-->>User: HTTP 200 完成注册/登录/绑定
    else 验证码错误或已过期
        VS-->>Server: 校验失败
        Server-->>User: HTTP 422 验证码无效或已过期
    end

use foundry::prelude::*;
use foundry_engine::services::email::send_email;

pub async fn notify_order_shipped(
    customer_email: &str,
    order_no: &str,
) -> AppResult<()> {
    let subject = format!("您的订单 #{} 已正式发货", order_no);
    let body = format!(
        "尊敬的客户：\n\n您的订单 {} 已经移交顺丰速运发出。感谢您的选购！\n\nFoundry 团队",
        order_no
    );

    // 异步发送邮件
    send_email(customer_email, &subject, &body).await?;
    info!("发货通知邮件已投递至: {}", customer_email);
    Ok(())
}

use foundry::prelude::*;
use foundry_engine::services::email::send_email;
use foundry_engine::services::verification::VerificationService;

pub async fn handle_send_register_code(
    state: &AppState,
    target_email: &str,
) -> AppResult<ApiResponse<String>> {
    // 1. 初始化验证码服务 (优先使用 Redis，无则自动回退内存)
    let verifier = VerificationService::new(state.redis.clone());

    // 2. 生成 6 位随机安全数字验证码 (100000..=999999)
    let code = VerificationService::generate_code();

    // 3. 校验 60s 冷却期并存入 (TTL: 5 分钟)
    // scope: 业务作用域, identifier: 用户标识
    verifier.save_code("register", target_email, &code).await?;

    // 4. 发送验证码邮件
    let subject = "【Foundry】注册安全验证码";
    let body = format!("您好！您的注册验证码为：{}。该验证码 5 分钟内有效，请勿泄露给他人。", code);
    send_email(target_email, &subject, &body).await?;

    Ok(ApiResponse::ok("验证码已成功发送".into()))
}

pub async fn handle_verify_register_code(
    state: &AppState,
    target_email: &str,
    input_code: &str,
) -> AppResult<ApiResponse<()>> {
    let verifier = VerificationService::new(state.redis.clone());

    // 原子核销验证码：校验成功后立即销毁，防止重放
    let is_valid = verifier.verify_code("register", target_email, input_code).await?;

    if !is_valid {
        return Err(AppError::Validation("验证码错误或已失效，请重新获取".into()));
    }

    info!("用户 {} 邮箱验证通过，继续后续业务", target_email);
    Ok(ApiResponse::ok(()))
}