Initial WhaleTown V2 backend

src/core/db/users/user_status.enum.ts

@@ -0,0 +1,173 @@
+/**
+ * 用户状态枚举（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);
+}