namespace Dpz.Core.Public.ViewModel.Response;

/// <summary>
/// 用户安全绑定状态,包含 2FA 与 Passkey 的绑定情况
/// </summary>
public class UserSecurityBindingStatusResponse
{
    /// <summary>
    /// 是否已绑定 2FA
    /// </summary>
    public bool HasTwoFactor { get; set; }

    /// <summary>
    /// 是否已绑定 Passkey
    /// </summary>
    public bool HasPasskey { get; set; }

    /// <summary>
    /// 是否需要绑定 2FA(未绑定时为 true)
    /// </summary>
    public bool RequiresTwoFactor => !HasTwoFactor;

    /// <summary>
    /// 是否需要绑定 Passkey(未绑定时为 true)
    /// </summary>
    public bool RequiresPasskey => !HasPasskey;

    /// <summary>
    /// 是否已满足强制安全绑定要求
    /// </summary>
    public bool HasRequiredSecurity => HasPasskey;

    /// <summary>
    /// 是否需要进入安全绑定引导
    /// </summary>
    public bool RequiresSecurityOnboarding => !HasRequiredSecurity;

    /// <summary>
    /// 2FA 与 Passkey 是否均已绑定
    /// </summary>
    public bool IsFullyBound => HasTwoFactor && HasPasskey;
}

/// <summary>
/// 2FA 绑定初始化响应,包含二维码、手动密钥和 setup token
/// </summary>
public class UserTwoFactorSetupResponse
{
    /// <summary>
    /// 2FA 绑定 setup token,用于后续确认绑定
    /// </summary>
    public required string SetupToken { get; set; }

    /// <summary>
    /// 绑定的账号
    /// </summary>
    public required string Account { get; set; }

    /// <summary>
    /// 手动输入密钥(不含分隔符)
    /// </summary>
    public required string ManualEntryKey { get; set; }

    /// <summary>
    /// 二维码图片地址
    /// </summary>
    public required string QrCodeSetupImageUrl { get; set; }

    /// <summary>
    /// 2FA 绑定引导页地址
    /// </summary>
    public required string SetupUrl { get; set; }
}
⚠⚠    以下内容为AI分析的结果,请根据实际情况进行判断。

这段代码定义了两个 C# 响应模型(ViewModel/Response),用于向客户端返回与用户安全设置相关的数据。代码逻辑简洁,主要通过布尔属性和计算属性表达安全绑定状态,以及提供 2FA 初始化所需的凭据信息。


1. UserSecurityBindingStatusResponse — 用户安全绑定状态

该模型用于描述用户当前 2FA(两步验证) 和 Passkey(通行密钥) 的绑定情况,同时通过计算属性提供业务上的判断结果。

成员类型说明
HasTwoFactorbool是否已绑定 2FA
HasPasskeybool是否已绑定 Passkey
RequiresTwoFactorbool(只读计算)未绑定 2FA 时为 true,等价于 !HasTwoFactor
RequiresPasskeybool(只读计算)未绑定 Passkey 时为 true,等价于 !HasPasskey
HasRequiredSecuritybool(只读计算)是否满足强制安全要求,这里仅取决于 Passkey,即 HasPasskey
RequiresSecurityOnboardingbool(只读计算)是否需要进入安全绑定引导,即 !HasRequiredSecurity
IsFullyBoundbool(只读计算)2FA 和 Passkey 均绑定 时为 true

计算属性背后的业务含义

  • HasRequiredSecurity 只检查 Passkey,意味着系统的“强制安全要求”是 Passkey 必须绑定,而 2FA 可能是可选项或辅助项。
  • RequiresSecurityOnboarding 可用于前端判断是否弹出引导流程,避免已满足要求的用户重复被引导。
  • IsFullyBound 则代表升级到了最完善的安全状态(同时具备 2FA 和 Passkey),适合用于展示“安全等级完全达标”。

2. UserTwoFactorSetupResponse — 2FA 绑定初始化响应

当用户请求开启 2FA 时,后端返回该响应,包含用于客户端展示和确认绑定所需的数据。

成员类型说明
SetupTokenstring(required)绑定流程的标识令牌,后续用户使用验证码完成绑定时需要携带此 Token 给后端确认
Accountstring(required)绑定的账号标识,通常为用户邮箱或用户名,用于在 Authenticator 应用中展示
ManualEntryKeystring(required)手动输入的密钥(不带分隔符),用户可手动输入该密钥到 TOTP 应用中
QrCodeSetupImageUrlstring(required)二维码图片的 URL,扫码后可直接添加账号
SetupUrlstring(required)2FA 绑定引导页的地址,可引导用户完成后续操作

注意:所有属性都使用了 required 关键字,这意味着在对象初始化时必须为每个属性赋值,否则编译器会报错。这保证了响应数据的完整性——客户端拿到的对象必定包含可用信息。


使用场景总结

  • 当前端加载用户安全设置页时,可请求 UserSecurityBindingStatusResponse 来决定:
    • 是否需要展示“绑定 2FA”的按钮(RequiresTwoFactor)
    • 是否需要展示“绑定 Passkey”的按钮(RequiresPasskey)
    • 是否已经满足强制要求(HasRequiredSecurity)
    • 是否推送给用户安全引导流程(RequiresSecurityOnboarding)
  • 当用户点击“绑定 2FA”时,后端返回 UserTwoFactorSetupResponse,前端利用其中二维码图片或手动密钥生成器展示给用户,待用户输入验证码后再用 SetupToken 调用确认接口完成绑定。

这类代码结构清晰,通过计算属性减少了重复判断逻辑,在 API 响应模型中非常常见。

评论加载中...