// iyixiGames.Application/Services/IUserService.cs

using iyixiGames.Domain.DTOs.Auth;
using iyixiGames.Domain.Entities;
// 引入用于异步操作的命名空间
// 确保引入你的领域实体（如 User 类）所在的命名空间

// 确保引入认证相关的数据传输对象（DTOs），如 LoginRequest, LoginResponse

namespace iyixiGames.Infrastructure.Services
{
    /// <summary>
    /// 定义用户服务接口。
    /// 该接口规定了所有与用户管理相关的核心业务操作，遵循单一职责原则，
    /// 将用户相关的业务逻辑从控制器中解耦出来，提高了代码的可维护性和可测试性。
    /// </summary>
    public interface IUserService
    {
        /// <summary>
        /// 根据用户名异步获取用户实体。
        /// 此方法主要用于查找用户是否存在以及是否处于激活状态，是登录和注册前置检查的关键。
        /// </summary>
        /// <param name="username">要查询的用户的唯一用户名。</param>
        /// <returns>
        /// 一个 <see cref="Task{TResult}"/>，其结果为找到的 <see cref="User"/> 实体；
        /// 如果没有找到匹配的用户，或者找到的用户处于非激活状态，则返回 null。
        /// </returns>
        Task<User?> GetUserByUsernameAsync(string username);

        /// <summary>
        /// 验证给定用户的密码是否正确。
        /// 此方法负责将用户输入的明文密码与数据库中存储的哈希密码进行比对。
        /// </summary>
        /// <param name="user">要验证密码的 <see cref="User"/> 实体，该实体应包含存储的密码哈希和盐值。</param>
        /// <param name="password">用户输入的明文密码。</param>
        /// <returns>
        /// 一个 <see cref="Task{TResult}"/>，其结果为布尔值：
        /// 如果密码有效（匹配），则为 true；否则为 false。
        /// </returns>
        Task<bool> VerifyPasswordAsync(User user, string password);

        /// <summary>
        /// 创建密码的哈希值和随机盐值。
        /// 此方法用于在存储用户密码到数据库之前，对其进行安全哈希处理。
        /// </summary>
        /// <param name="password">需要进行哈希处理的明文密码。</param>
        /// <returns>
        /// 一个 <see cref="Task{TResult}"/>，其结果为一个元组：
        /// Item1 (string HashedPassword): 经过哈希处理后的密码字符串（通常是 Base64 编码）。
        /// Item2 (string Salt): 用于此次哈希操作的随机盐值字符串（通常是 Base64 编码）。
        /// </returns>
        Task<(string HashedPassword, string Salt)> CreatePasswordHash(string password);

        /// <summary>
        /// 处理用户登录请求的核心业务逻辑。
        /// 此方法负责验证用户凭据，并在登录成功时更新用户状态（如最后登录时间）。
        /// </summary>
        /// <param name="request">包含用户名和密码的 <see cref="LoginRequest"/> 数据传输对象。</param>
        /// <returns>
        /// 一个 <see cref="Task{TResult}"/>，其结果为 <see cref="LoginResponse"/> 对象。
        /// 该响应包含登录是否成功的信息、相关消息，以及成功登录用户的 ID 和用户名。
        /// </returns>
        Task<LoginResponse> LoginAsync(LoginRequest request);

        /// <summary>
        /// 注册新用户。
        /// 此方法负责验证新用户的唯一性（用户名和电子邮件），哈希密码，并将新用户数据持久化到数据库。
        /// </summary>
        /// <param name="username">要注册的新用户的唯一用户名。</param>
        /// <param name="email">要注册的新用户的唯一电子邮件地址。</param>
        /// <param name="fullName">新用户的全名。</param>
        /// <param name="password">新用户的明文密码。</param>
        /// <returns>
        /// 一个 <see cref="Task{TResult}"/>，其结果为新创建的 <see cref="User"/> 实体；
        /// 如果注册失败（例如，用户名或电子邮件已被占用），则返回 null。
        /// </returns>
        Task<User?> RegisterUserAsync(string username, string email, string fullName, string password);

        /// <summary>
        /// 根据电子邮件地址异步获取用户实体。
        /// 此方法主要用于检查电子邮件的唯一性，例如在用户注册时确保没有重复的邮箱被注册。
        /// 它会查找数据库中与给定电子邮件地址匹配的第一个用户，无论该用户是否处于激活状态。
        /// </summary>
        /// <param name="email">要查询的用户的电子邮件地址。</param>
        /// <returns>
        /// 一个 <see cref="Task{TResult}"/>，其结果为找到的 <see cref="User"/> 实体；
        /// 如果数据库中没有找到与该电子邮件地址匹配的用户，则返回 null。
        /// </returns>
        Task<User?> GetUserByEmailAsync(string email);
    }
}