/**
 * 用户状态枚举（Core层）
 *
 * 功能描述：
 * - 定义用户账户的各种状态
 * - 提供状态检查和描述功能
 * - 支持用户生命周期管理
 *
 * 职责分离：
 * - 用户状态枚举值定义和管理
 * - 状态描述和错误消息的国际化支持
 * - 状态验证和转换工具函数提供
 *
 * 最近修改：
 * - 2026-01-07: 架构优化 - 从Business层移动到Core层，符合架构分层原则 (修改者: moyin)
 *
 * @author moyin
 * @version 1.0.2
 * @since 2025-12-24
 * @lastModified 2026-01-07
 */

/**
 * 用户状态枚举
 *
 * 状态说明：
 * - active: 正常状态，可以正常使用所有功能
 * - inactive: 未激活状态，通常是新注册用户需要邮箱验证
 * - locked: 临时锁定状态，可以解锁恢复
 * - banned: 永久禁用状态，需要管理员处理
 * - deleted: 软删除状态，数据保留但不可使用
 * - pending: 待审核状态，需要管理员审核后激活
 */
export enum UserStatus {
  ACTIVE = 'active',      // 正常状态
  INACTIVE = 'inactive',  // 未激活状态
  LOCKED = 'locked',      // 锁定状态
  BANNED = 'banned',      // 禁用状态
  DELETED = 'deleted',    // 删除状态
  PENDING = 'pending'     // 待审核状态
}

/**
 * 获取用户状态的中文描述
 *
 * 技术实现：
 * 1. 根据用户状态枚举值查找对应的中文描述
 * 2. 提供用户友好的状态显示文本
 * 3. 处理未知状态的默认描述
 *
 * @param status 用户状态
 * @returns 状态描述
 * @throws 无异常抛出，未知状态返回默认描述
 *
 * @example
 * ```typescript
 * const description = getUserStatusDescription(UserStatus.ACTIVE);
 * // 返回: "正常"
 * ```
 */
export function getUserStatusDescription(status: UserStatus): string {
  const descriptions = {
    [UserStatus.ACTIVE]: '正常',
    [UserStatus.INACTIVE]: '未激活',
    [UserStatus.LOCKED]: '已锁定',
    [UserStatus.BANNED]: '已禁用',
    [UserStatus.DELETED]: '已删除',
    [UserStatus.PENDING]: '待审核'
  };

  return descriptions[status] || '未知状态';
}

/**
 * 检查用户是否可以登录
 *
 * 技术实现：
 * 1. 验证用户状态是否允许登录系统
 * 2. 只有正常状态的用户可以登录
 * 3. 其他状态均不允许登录
 *
 * @param status 用户状态
 * @returns 是否可以登录
 * @throws 无异常抛出
 *
 * @example
 * ```typescript
 * const canLogin = canUserLogin(UserStatus.ACTIVE);
 * // 返回: true
 * const cannotLogin = canUserLogin(UserStatus.LOCKED);
 * // 返回: false
 * ```
 */
export function canUserLogin(status: UserStatus): boolean {
  // 只有正常状态的用户可以登录
  return status === UserStatus.ACTIVE;
}

/**
 * 获取用户状态对应的错误消息
 *
 * 技术实现：
 * 1. 根据用户状态返回相应的错误提示信息
 * 2. 为不同状态提供用户友好的错误说明
 * 3. 指导用户如何解决状态问题
 *
 * @param status 用户状态
 * @returns 错误消息
 * @throws 无异常抛出，未知状态返回默认错误消息
 *
 * @example
 * ```typescript
 * const errorMsg = getUserStatusErrorMessage(UserStatus.LOCKED);
 * // 返回: "账户已被锁定，请联系管理员"
 * ```
 */
export function getUserStatusErrorMessage(status: UserStatus): string {
  const errorMessages = {
    [UserStatus.ACTIVE]: '', // 正常状态无错误
    [UserStatus.INACTIVE]: '账户未激活，请先验证邮箱',
    [UserStatus.LOCKED]: '账户已被锁定，请联系管理员',
    [UserStatus.BANNED]: '账户已被禁用，请联系管理员',
    [UserStatus.DELETED]: '账户不存在',
    [UserStatus.PENDING]: '账户待审核，请等待管理员审核'
  };

  return errorMessages[status] || '账户状态异常';
}

/**
 * 获取所有可用的用户状态
 *
 * 技术实现：
 * 1. 返回系统中定义的所有用户状态枚举值
 * 2. 用于状态选择器和验证逻辑
 * 3. 支持动态状态管理功能
 *
 * @returns 用户状态数组
 * @throws 无异常抛出
 *
 * @example
 * ```typescript
 * const allStatuses = getAllUserStatuses();
 * // 返回: [UserStatus.ACTIVE, UserStatus.INACTIVE, ...]
 * ```
 */
export function getAllUserStatuses(): UserStatus[] {
  return Object.values(UserStatus);
}

/**
 * 检查状态值是否有效
 *
 * 技术实现：
 * 1. 验证输入的字符串是否为有效的用户状态枚举值
 * 2. 提供类型安全的状态验证功能
 * 3. 支持动态状态值验证和类型转换
 *
 * @param status 状态值
 * @returns 是否为有效状态
 * @throws 无异常抛出
 *
 * @example
 * ```typescript
 * const isValid = isValidUserStatus('active');
 * // 返回: true
 * const isInvalid = isValidUserStatus('unknown');
 * // 返回: false
 * ```
 */
export function isValidUserStatus(status: string): status is UserStatus {
  return Object.values(UserStatus).includes(status as UserStatus);
}