using Dpz.Core.Public.ViewModel.Response;

namespace Dpz.Core.Service.RepositoryService;

public interface IUserTwoFactorService
{
    /// <summary>
    /// 获取用户安全绑定状态，包括 2FA 与 Passkey 是否已绑定
    /// </summary>
    /// <param name="account">用户账号</param>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns>用户安全绑定状态；账号无效或用户不存在时返回未绑定状态</returns>
    Task<UserSecurityBindingStatusResponse> GetBindingStatusAsync(
        string? account,
        CancellationToken cancellationToken = default
    );

    /// <summary>
    /// 开始 2FA 绑定流程，生成临时密钥和 setup token，并写入短期缓存
    /// </summary>
    /// <param name="account">用户账号</param>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns>临时凭据；账号无效、用户不存在或已绑定 2FA 时返回 null</returns>
    Task<UserTwoFactorSetupChallenge?> BeginSetupAsync(
        string? account,
        CancellationToken cancellationToken = default
    );

    /// <summary>
    /// 获取已绑定 2FA 用户的密钥
    /// </summary>
    /// <param name="account">用户账号</param>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns>已绑定密钥；账号无效、用户不存在、未绑定或密钥为空时返回 null</returns>
    Task<string?> GetBoundKeyAsync(string? account, CancellationToken cancellationToken = default);

    /// <summary>
    /// 根据 setup token 读取 2FA 绑定流程中的临时密钥
    /// </summary>
    /// <param name="account">用户账号</param>
    /// <param name="setupToken">绑定流程开始时生成的 setup token</param>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns>临时密钥；token 无效、过期或账号不匹配时返回 null</returns>
    Task<string?> GetSetupKeyAsync(
        string? account,
        string? setupToken,
        CancellationToken cancellationToken = default
    );

    /// <summary>
    /// 使用 setup token 完成 2FA 绑定，并将临时密钥写入数据库
    /// </summary>
    /// <param name="account">用户账号</param>
    /// <param name="setupToken">绑定流程开始时生成的 setup token</param>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns>异步任务</returns>
    Task BindAsync(
        string? account,
        string? setupToken,
        CancellationToken cancellationToken = default
    );

    /// <summary>
    /// 解绑 2FA，并清除已保存的密钥
    /// </summary>
    /// <param name="account">用户账号</param>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns>异步任务</returns>
    Task UnbindAsync(string? account, CancellationToken cancellationToken = default);
}