/**
 * 邀请码模块类型定义（audit-P2-3 新增）
 *
 * 纯类型文件，无 `server-only`，可被 Server / Client Component 安全导入。
 */

/** 邀请码角色（与系统角色一致） */
export type InvitationRole = "student" | "teacher" | "parent" | "admin"

/** 邀请码记录（数据库行） */
export interface InvitationCodeRecord {
  id: string
  code: string
  email: string | null
  role: InvitationRole
  classId: string | null
  notes: string | null
  createdAt: Date
  createdBy: string | null
  expiresAt: Date | null
  usedBy: string | null
  usedAt: Date | null
}

/** 批量生成邀请码的输入 */
export interface GenerateInvitationCodesInput {
  /** 生成数量（1-100） */
  count: number
  role: InvitationRole
  /** 可选：限定邮箱（留空则任意邮箱可用） */
  email?: string | null
  /** 可选：自动加入的班级 ID */
  classId?: string | null
  /** 可选：过期时间（ISO 字符串或 Date） */
  expiresAt?: Date | null
  /** 可选：管理员备注 */
  notes?: string | null
}

/** 批量生成邀请码的结果 */
export interface GenerateInvitationCodesResult {
  /** 生成的邀请码列表（含明文 code，仅此一次返回完整明文） */
  codes: InvitationCodeRecord[]
  /** 批次 ID（同一批生成的邀请码共享同一 batchId） */
  batchId: string
}

/** 校验邀请码的结果 */
export interface ValidateInvitationCodeResult {
  valid: boolean
  /** 校验失败原因（valid=false 时有值） */
  reason?: "not_found" | "already_used" | "expired" | "email_mismatch"
  /** 校验通过时返回邀请码记录（脱敏：不含 code 明文） */
  code?: Omit<InvitationCodeRecord, "code">
}

/** 使用邀请码的输入 */
export interface ConsumeInvitationCodeInput {
  code: string
  /** 使用者邮箱（用于校验 email 限定） */
  email: string
  /** 使用者 userId（注册后写入 usedBy） */
  userId: string
}
