package com.dne.ems.service;

import com.dne.ems.dto.JwtAuthenticationResponse;
import com.dne.ems.dto.LoginRequest;
import com.dne.ems.dto.SignUpRequest;

/**
 * 认证服务接口，提供用户认证和安全相关的核心功能
 *
 * <p>主要功能包括：
 * <ul>
 *   <li>用户注册与登录</li>
 *   <li>密码重置与验证</li>
 *   <li>JWT令牌生成</li>
 * </ul>
 *
 * <p>典型使用示例：
 * <pre>{@code
 * // 用户注册
 * authService.registerUser(signUpRequest);
 *
 * // 用户登录
 * JwtAuthenticationResponse response = authService.signIn(loginRequest);
 * }</pre>
 *
 * @author DNE开发团队
 * @version 1.0
 * @since 2024
 */
public interface AuthService {

    /**
     * 请求密码重置，发送重置验证码到用户邮箱
     *
     * <p>安全流程：
     * <ol>
     *   <li>验证邮箱格式</li>
     *   <li>如果邮箱已注册，发送6位数字验证码(有效期5分钟)</li>
     *   <li>无论用户是否存在都返回成功，防止用户枚举攻击</li>
     * </ol>
     *
     * @param email 用户注册邮箱(必须符合name@domain.com格式)
     * @throws IllegalArgumentException 如果邮箱格式无效
     * @see com.dne.ems.service.VerificationCodeService 验证码服务
     */
    void requestPasswordReset(String email);

    /**
     * 使用令牌重置密码（旧方法，保留以兼容历史代码）
     * 
     * @param token 密码重置令牌
     * @param newPassword 新密码
     * @deprecated 使用基于验证码的 {@link #resetPasswordWithCode(String, String, String)} 替代
     */
    @Deprecated
    void resetPassword(String token, String newPassword);
    
    /**
     * 使用验证码重置密码
     *
     * <p>重置流程：
     * <ol>
     *   <li>验证邮箱是否注册</li>
     *   <li>验证验证码是否正确且在有效期内(5分钟)</li>
     *   <li>验证新密码复杂度</li>
     *   <li>更新密码并清除验证码</li>
     * </ol>
     *
     * <p>密码复杂度要求：
     * <ul>
     *   <li>长度8-20位</li>
     *   <li>包含大小写字母和数字</li>
     *   <li>至少一个特殊字符(!@#$%^&*)</li>
     *   <li>不能与旧密码相同</li>
     * </ul>
     *
     * @param email 用户注册邮箱
     * @param code 验证码(6位数字)
     * @param newPassword 新密码，必须符合密码复杂度要求
     * @throws ResourceNotFoundException 如果邮箱未注册
     * @throws InvalidOperationException 如果验证码无效或过期
     * @throws IllegalArgumentException 如果新密码不符合要求
     * @see com.dne.ems.validation.PasswordValidator 密码验证器
     */
    void resetPasswordWithCode(String email, String code, String newPassword);

    /**
     * 注册新用户
     *
     * @param signUpRequest 包含用户名、邮箱、密码等注册信息
     * @throws UserAlreadyExistsException 如果用户名或邮箱已被注册
     * @throws IllegalArgumentException 如果注册信息无效
     */
    void registerUser(SignUpRequest signUpRequest);

    /**
     * 用户登录
     *
     * @param request 包含用户名/邮箱和密码的登录请求
     * @return 包含JWT令牌的认证响应，令牌有效期24小时
     * @throws ResourceNotFoundException 如果用户不存在
     * @throws InvalidOperationException 如果密码不匹配
     */
    JwtAuthenticationResponse signIn(LoginRequest request);

    /**
     * 处理用户登出逻辑
     */
    void logout();
}