@hed-hog/lms 0.0.304 → 0.0.306

package/src/class-group/class-group.service.ts

@@ -0,0 +1,1802 @@
+import { PrismaService } from '@hed-hog/api-prisma';
+import {
+    BadRequestException,
+    ConflictException,
+    Injectable,
+    NotFoundException,
+} from '@nestjs/common';
+import { Prisma } from '@prisma/client';
+import { PrismaClientKnownRequestError } from '@prisma/client/runtime/library';
+import { randomUUID } from 'node:crypto';
+import {
+  CreateClassGroupDto,
+  type ClassGroupSessionRecurrenceDto,
+  type ClassGroupSessionTemplateDto,
+} from './dto/create-class-group.dto';
+import { CreateSessionDto, type SessionRecurrenceDto } from './dto/create-session.dto';
+import { UpdateClassGroupDto } from './dto/update-class-group.dto';
+import { UpdateSessionDto } from './dto/update-session.dto';
+
+type SessionScope = 'single' | 'series';
+type SessionRecurrenceDay = 'MO' | 'TU' | 'WE' | 'TH' | 'FR' | 'SA' | 'SU';
+
+type NormalizedSessionRecurrence = {
+  frequency: 'daily' | 'weekly' | 'monthly' | 'yearly';
+  interval: number;
+  until: string;
+  daysOfWeek?: SessionRecurrenceDay[];
+};
+
+type ClassSessionTemplateSummary = {
+  title: string;
+  isRecurring: boolean;
+  recurrence?: NormalizedSessionRecurrence | null;
+};
+
+@Injectable()
+export class ClassGroupService {
+  private static readonly DAY_ORDER: SessionRecurrenceDay[] = [
+    'MO',
+    'TU',
+    'WE',
+    'TH',
+    'FR',
+    'SA',
+    'SU',
+  ];
+
+  private static readonly UTC_DAY_TO_CODE: SessionRecurrenceDay[] = [
+    'SU',
+    'MO',
+    'TU',
+    'WE',
+    'TH',
+    'FR',
+    'SA',
+  ];
+
+  constructor(private readonly prisma: PrismaService) {}
+
+  private isEmailCode(code?: string | null) {
+    return (code ?? '').toLowerCase() === 'email';
+  }
+
+  private isPhoneCode(code?: string | null) {
+    const normalized = (code ?? '').toLowerCase();
+    return normalized === 'phone' || normalized === 'mobile';
+  }
+
+  private getClassGroupInclude() {
+    const include: any = {
+      course: {
+        select: {
+          id: true,
+          title: true,
+          primary_color: true,
+        },
+      },
+      _count: {
+        select: {
+          course_enrollment: {
+            where: {
+              status: { not: 'cancelled' },
+            },
+          },
+          course_class_session: true,
+        },
+      },
+      instructor: {
+        select: {
+          id: true,
+          person: {
+            select: {
+              name: true,
+            },
+          },
+        },
+      },
+    };
+
+    return include;
+  }
+
+  private getSessionInclude() {
+    return {
+      course_class_session_instructor: {
+        orderBy: { id: 'asc' as const },
+        select: {
+          instructor_id: true,
+          role: true,
+          instructor: {
+            select: {
+              person: {
+                select: {
+                  name: true,
+                },
+              },
+            },
+          },
+        },
+      },
+    };
+  }
+
+  async list(params: {
+    page?: number;
+    pageSize?: number;
+    search?: string;
+    status?: string;
+    deliveryMode?: string;
+    courseId?: number;
+  }) {
+    const page = Math.max(Number(params.page) || 1, 1);
+    const pageSize = Math.max(Number(params.pageSize) || 12, 1);
+    const skip = (page - 1) * pageSize;
+
+    const where: any = {};
+
+    const status = this.normalizeStatus(params.status);
+    if (status) {
+      where.status = status;
+    }
+
+    const deliveryMode = this.normalizeDeliveryMode(params.deliveryMode);
+    if (deliveryMode) {
+      where.delivery_mode = deliveryMode;
+    }
+
+    if (params.courseId) {
+      where.course_id = params.courseId;
+    }
+
+    if (params.search?.trim()) {
+      const search = params.search.trim();
+      where.OR = [
+        { code: { contains: search, mode: 'insensitive' } },
+        { title: { contains: search, mode: 'insensitive' } },
+        { course: { title: { contains: search, mode: 'insensitive' } } },
+      ];
+    }
+
+    const [classes, total] = await Promise.all([
+      this.prisma.course_class_group.findMany({
+        skip,
+        take: pageSize,
+        where,
+        orderBy: { created_at: 'desc' },
+        include: this.getClassGroupInclude(),
+      }),
+      this.prisma.course_class_group.count({ where }),
+    ]);
+
+    return {
+      total,
+      page,
+      pageSize,
+      lastPage: Math.max(1, Math.ceil(total / pageSize)),
+      data: classes.map((item) => this.mapClassGroup(item)),
+    };
+  }
+
+  async stats() {
+    const [totalClasses, ongoingClasses, classes] = await Promise.all([
+      this.prisma.course_class_group.count(),
+      this.prisma.course_class_group.count({ where: { status: 'ongoing' } }),
+      this.prisma.course_class_group.findMany({
+        select: {
+          id: true,
+          status: true,
+          capacity: true,
+          _count: {
+            select: {
+              course_enrollment: {
+                where: {
+                  status: { not: 'cancelled' },
+                },
+              },
+            },
+          },
+        },
+      }),
+    ]);
+
+    const openVacancies = classes
+      .filter((item) => item.status === 'open')
+      .reduce(
+        (sum, item) =>
+          sum + Math.max((item.capacity ?? 0) - item._count.course_enrollment, 0),
+        0,
+      );
+
+    const occupancyRate =
+      classes.length > 0
+        ? Math.round(
+            (classes.reduce(
+              (sum, item) =>
+                sum +
+                item._count.course_enrollment / Math.max(item.capacity ?? 1, 1),
+              0,
+            ) /
+              classes.length) *
+              100,
+          )
+        : 0;
+
+    return {
+      totalClasses,
+      ongoingClasses,
+      openVacancies,
+      occupancyRate,
+    };
+  }
+
+  async getById(id: number) {
+    const item = await this.prisma.course_class_group.findUnique({
+      where: { id },
+      include: this.getClassGroupInclude(),
+    });
+
+    if (!item) {
+      return null;
+    }
+
+    const sessionTemplateSummary = await this.getClassSessionTemplateSummary(id);
+
+    return {
+      ...this.mapClassGroup(item),
+      sessionTitle: sessionTemplateSummary?.title ?? null,
+      sessionRecurrenceSummary: sessionTemplateSummary
+        ? {
+            ...(sessionTemplateSummary.recurrence ?? {}),
+            isRecurring: sessionTemplateSummary.isRecurring,
+          }
+        : null,
+    };
+  }
+
+  async create(dto: CreateClassGroupDto) {
+    await this.assertCourseExists(dto.courseId);
+    if (dto.instructorId) {
+      await this.assertInstructorExists(dto.instructorId);
+    }
+    this.assertDatesAndTimes({
+      startDate: dto.startDate,
+      endDate: dto.endDate,
+      startTime: dto.startTime,
+      endTime: dto.endTime,
+    });
+
+    try {
+      const created = await this.prisma.$transaction(async (tx) => {
+        const createdClass = await tx.course_class_group.create({
+          data: {
+            code: dto.code,
+            course_id: dto.courseId,
+            instructor_id: dto.instructorId,
+            title: dto.title,
+            description: dto.description,
+            delivery_mode: dto.deliveryMode,
+            status: dto.status ?? 'open',
+            start_date: new Date(dto.startDate),
+            end_date: dto.endDate ? new Date(dto.endDate) : null,
+            start_time: dto.startTime,
+            end_time: dto.endTime,
+            week_days: dto.weekDays,
+            capacity: dto.capacity ?? 30,
+            location: dto.location,
+            virtual_room_url: dto.virtualRoomUrl,
+          },
+          include: this.getClassGroupInclude(),
+        });
+
+        if (dto.sessionTemplate) {
+          await this.syncClassSessionsFromTemplate(
+            tx,
+            createdClass.id,
+            createdClass,
+            dto.sessionTemplate,
+          );
+        }
+
+        return createdClass;
+      });
+
+      return this.mapClassGroup(created);
+    } catch (error) {
+      this.handlePrismaError(error);
+    }
+  }
+
+  async update(id: number, dto: UpdateClassGroupDto) {
+    const existing = await this.prisma.course_class_group.findUnique({
+      where: { id },
+      select: {
+        id: true,
+        course_id: true,
+        code: true,
+        title: true,
+        description: true,
+        delivery_mode: true,
+        instructor_id: true,
+        start_date: true,
+        end_date: true,
+        start_time: true,
+        end_time: true,
+        location: true,
+        virtual_room_url: true,
+      },
+    });
+
+    if (!existing) {
+      throw new NotFoundException('Class not found');
+    }
+
+    const courseId = dto.courseId ?? existing.course_id;
+    await this.assertCourseExists(courseId);
+    if (dto.instructorId) {
+      await this.assertInstructorExists(dto.instructorId);
+    }
+
+    this.assertDatesAndTimes({
+      startDate: dto.startDate ?? existing.start_date.toISOString(),
+      endDate:
+        dto.endDate !== undefined
+          ? dto.endDate
+          : existing.end_date?.toISOString(),
+      startTime:
+        dto.startTime !== undefined ? dto.startTime : existing.start_time ?? undefined,
+      endTime:
+        dto.endTime !== undefined ? dto.endTime : existing.end_time ?? undefined,
+    });
+
+    const status =
+      dto.status !== undefined ? this.normalizeStatus(dto.status) : undefined;
+    const deliveryMode =
+      dto.deliveryMode !== undefined
+        ? this.normalizeDeliveryMode(dto.deliveryMode)
+        : undefined;
+
+    try {
+      const updated = await this.prisma.$transaction(async (tx) => {
+        const updatedClass = await tx.course_class_group.update({
+          where: { id },
+          data: {
+            ...(dto.code !== undefined && { code: dto.code }),
+            ...(dto.courseId !== undefined && { course_id: dto.courseId }),
+            ...(dto.instructorId !== undefined && {
+              instructor_id: dto.instructorId,
+            }),
+            ...(dto.title !== undefined && { title: dto.title }),
+            ...(dto.description !== undefined && { description: dto.description }),
+            ...(deliveryMode !== undefined && { delivery_mode: deliveryMode }),
+            ...(status !== undefined && { status }),
+            ...(dto.startDate !== undefined && { start_date: new Date(dto.startDate) }),
+            ...(dto.endDate !== undefined && {
+              end_date: dto.endDate ? new Date(dto.endDate) : null,
+            }),
+            ...(dto.startTime !== undefined && { start_time: dto.startTime }),
+            ...(dto.endTime !== undefined && { end_time: dto.endTime }),
+            ...(dto.weekDays !== undefined && { week_days: dto.weekDays }),
+            ...(dto.capacity !== undefined && { capacity: dto.capacity }),
+            ...(dto.location !== undefined && { location: dto.location }),
+            ...(dto.virtualRoomUrl !== undefined && {
+              virtual_room_url: dto.virtualRoomUrl,
+            }),
+          },
+          include: this.getClassGroupInclude(),
+        });
+
+        if (dto.sessionTemplate) {
+          await this.syncClassSessionsFromTemplate(
+            tx,
+            id,
+            updatedClass,
+            dto.sessionTemplate,
+            { futureOnly: true },
+          );
+        }
+
+        return updatedClass;
+      });
+
+      return this.mapClassGroup(updated);
+    } catch (error) {
+      this.handlePrismaError(error);
+    }
+  }
+
+  async remove(id: number) {
+    await this.prisma.course_class_group.delete({ where: { id } });
+    return { success: true };
+  }
+
+  private async getClassSessionTemplateSummary(
+    classGroupId: number,
+  ): Promise<ClassSessionTemplateSummary | null> {
+    const today = this.getSessionMutationFloorDate();
+    const session =
+      (await this.prisma.course_class_session.findFirst({
+        where: {
+          course_class_group_id: classGroupId,
+          session_date: { gte: today },
+          status: { notIn: ['completed', 'cancelled'] },
+        },
+        orderBy: [{ session_date: 'asc' }, { occurrence_index: 'asc' }],
+        select: {
+          title: true,
+          recurrence_rule: true,
+          recurrence_id: true,
+        },
+      })) ??
+      (await this.prisma.course_class_session.findFirst({
+        where: { course_class_group_id: classGroupId },
+        orderBy: [{ session_date: 'asc' }, { occurrence_index: 'asc' }],
+        select: {
+          title: true,
+          recurrence_rule: true,
+          recurrence_id: true,
+        },
+      }));
+
+    if (!session) {
+      return null;
+    }
+
+    return {
+      title: session.title,
+      recurrence: this.parseRecurrenceRule(session.recurrence_rule),
+      isRecurring: Boolean(session.recurrence_id),
+    };
+  }
+
+  private getSessionMutationFloorDate() {
+    return this.normalizeSessionDate(new Date());
+  }
+
+  private buildClassSessionDto(
+    classGroup: any,
+    sessionTemplate: ClassGroupSessionTemplateDto,
+  ): CreateSessionDto {
+    if (!classGroup.start_date) {
+      throw new BadRequestException('Class start date is required to generate sessions');
+    }
+
+    if (!classGroup.start_time || !classGroup.end_time) {
+      throw new BadRequestException('Class start and end times are required to generate sessions');
+    }
+
+    const deliveryMode = classGroup.delivery_mode;
+    const isOnline = deliveryMode === 'online';
+    const isHybrid = deliveryMode === 'hybrid';
+
+    return {
+      title: sessionTemplate.title.trim(),
+      description: sessionTemplate.description ?? classGroup.description ?? undefined,
+      sessionDate: this.toDateKey(this.normalizeSessionDate(classGroup.start_date)),
+      startTime: classGroup.start_time,
+      endTime: classGroup.end_time,
+      location:
+        isOnline && !isHybrid
+          ? undefined
+          : sessionTemplate.location ?? classGroup.location ?? undefined,
+      meetingUrl:
+        !isOnline && !isHybrid
+          ? undefined
+          : sessionTemplate.meetingUrl ?? classGroup.virtual_room_url ?? undefined,
+      color: sessionTemplate.color ?? undefined,
+      status: 'scheduled',
+      instructorId: classGroup.instructor_id ?? undefined,
+      recurrence: sessionTemplate.recurrence
+        ? this.toSessionRecurrenceDto(sessionTemplate.recurrence)
+        : undefined,
+    };
+  }
+
+  private toSessionRecurrenceDto(
+    recurrence: ClassGroupSessionRecurrenceDto,
+  ): SessionRecurrenceDto {
+    return {
+      frequency: recurrence.frequency,
+      interval: recurrence.interval,
+      until: recurrence.until,
+      daysOfWeek: recurrence.daysOfWeek,
+    };
+  }
+
+  private async syncClassSessionsFromTemplate(
+    tx: Prisma.TransactionClient,
+    classGroupId: number,
+    classGroup: any,
+    sessionTemplate: ClassGroupSessionTemplateDto,
+    options?: { futureOnly?: boolean },
+  ) {
+    const createDto = this.buildClassSessionDto(classGroup, sessionTemplate);
+    const mutableWhere: any = {
+      course_class_group_id: classGroupId,
+    };
+
+    if (options?.futureOnly) {
+      mutableWhere.session_date = { gte: this.getSessionMutationFloorDate() };
+      mutableWhere.status = { notIn: ['completed', 'cancelled'] };
+    }
+
+    const mutableSessions = await tx.course_class_session.findMany({
+      where: mutableWhere,
+      select: { id: true },
+    });
+
+    if (mutableSessions.length > 0) {
+      const sessionIds = mutableSessions.map((session) => session.id);
+
+      await tx.course_class_attendance.deleteMany({
+        where: { course_class_session_id: { in: sessionIds } },
+      });
+      await tx.course_class_session_instructor.deleteMany({
+        where: { course_class_session_id: { in: sessionIds } },
+      });
+      await tx.course_class_session.deleteMany({
+        where: { id: { in: sessionIds } },
+      });
+    }
+
+    await this.createSessionSeriesInTransaction(tx, classGroupId, createDto, {
+      minDate: options?.futureOnly ? this.getSessionMutationFloorDate() : undefined,
+    });
+  }
+
+  private mapClassGroup(item: any) {
+    const instructorName =
+      item.instructor?.person?.name?.trim() ??
+      item.instructorName?.trim?.() ??
+      item.professorName?.trim?.() ??
+      '';
+
+    return {
+      id: item.id,
+      code: item.code,
+      title: item.title,
+      description: item.description ?? '',
+      deliveryMode: item.delivery_mode,
+      status: item.status,
+      startDate: item.start_date,
+      endDate: item.end_date,
+      startTime: item.start_time,
+      endTime: item.end_time,
+      weekDays: item.week_days,
+      capacity: item.capacity,
+      location: item.location,
+      virtualRoomUrl: item.virtual_room_url,
+      courseId: item.course_id,
+      instructorId: item.instructor_id ?? item.instructor?.id ?? null,
+      instructorName,
+      instructor: instructorName,
+      professorName: instructorName,
+      professor: instructorName,
+      courseTitle: item.course?.title ?? '',
+      primaryColor: item.course?.primary_color ?? null,
+      enrolledCount: item._count?.course_enrollment ?? 0,
+      sessionCount: item._count?.course_class_session ?? 0,
+      occupancyRate: Math.round(
+        ((item._count?.course_enrollment ?? 0) / Math.max(item.capacity ?? 1, 1)) *
+          100,
+      ),
+      createdAt: item.created_at,
+      updatedAt: item.updated_at,
+    };
+  }
+
+  private normalizeStatus(value?: string) {
+    if (!value) return undefined;
+
+    const normalized = value.trim().toLowerCase();
+    const valid = ['open', 'ongoing', 'completed', 'cancelled'];
+
+    if (!valid.includes(normalized)) {
+      throw new BadRequestException('Invalid status');
+    }
+
+    return normalized as 'open' | 'ongoing' | 'completed' | 'cancelled';
+  }
+
+  private normalizeDeliveryMode(value?: string) {
+    if (!value) return undefined;
+
+    const normalized = value.trim().toLowerCase();
+    const valid = ['presential', 'online', 'hybrid'];
+
+    if (!valid.includes(normalized)) {
+      throw new BadRequestException('Invalid delivery mode');
+    }
+
+    return normalized as 'presential' | 'online' | 'hybrid';
+  }
+
+  private assertDatesAndTimes(params: {
+    startDate: string;
+    endDate?: string;
+    startTime?: string;
+    endTime?: string;
+  }) {
+    const startDate = new Date(params.startDate);
+    if (Number.isNaN(startDate.getTime())) {
+      throw new BadRequestException('Invalid start date');
+    }
+
+    if (params.endDate) {
+      const endDate = new Date(params.endDate);
+      if (Number.isNaN(endDate.getTime())) {
+        throw new BadRequestException('Invalid end date');
+      }
+      if (endDate.getTime() < startDate.getTime()) {
+        throw new BadRequestException('End date cannot be before start date');
+      }
+    }
+
+    if (params.startTime && params.endTime) {
+      const start = this.timeToMinutes(params.startTime);
+      const end = this.timeToMinutes(params.endTime);
+
+      if (start >= end) {
+        throw new BadRequestException('End time must be after start time');
+      }
+    }
+  }
+
+  private timeToMinutes(value: string) {
+    const [hours, minutes] = value.split(':').map(Number);
+    return hours * 60 + minutes;
+  }
+
+  private async assertCourseExists(courseId: number) {
+    const exists = await this.prisma.course.findUnique({
+      where: { id: courseId },
+      select: { id: true },
+    });
+
+    if (!exists) {
+      throw new NotFoundException('Course not found');
+    }
+  }
+
+  // ── Students ────────────────────────────────────────────────────────────────
+
+  async listStudents(classGroupId: number, search?: string) {
+    const group = await this.prisma.course_class_group.findUnique({
+      where: { id: classGroupId },
+      select: { id: true, course_id: true },
+    });
+    if (!group) throw new NotFoundException('Class not found');
+
+    const enrollments = await this.prisma.course_enrollment.findMany({
+      where: {
+        course_class_group_id: classGroupId,
+        status: { not: 'cancelled' },
+      },
+      include: {
+        person: {
+          select: {
+            id: true,
+            name: true,
+            contact: {
+              select: { value: true, contact_type: { select: { code: true } } },
+            },
+          },
+        },
+      },
+      orderBy: { enrolled_at: 'asc' },
+    });
+
+    const mapped = enrollments.map((e) => {
+      const contacts = e.person.contact;
+      const email =
+        contacts.find((c) => this.isEmailCode(c.contact_type.code))?.value ?? '';
+      const phone =
+        contacts.find((c) => this.isPhoneCode(c.contact_type.code))?.value ?? '';
+      return {
+        id: e.person.id,
+        enrollmentId: e.id,
+        nome: e.person.name,
+        email,
+        telefone: phone,
+        matriculadoEm: e.enrolled_at,
+        progresso: e.progress_percent,
+        status: e.status,
+      };
+    });
+
+    if (search?.trim()) {
+      const q = search.trim().toLowerCase();
+      return mapped.filter(
+        (s) =>
+          s.nome.toLowerCase().includes(q) ||
+          s.email.toLowerCase().includes(q),
+      );
+    }
+
+    return mapped;
+  }
+
+  async enrollStudent(classGroupId: number, personId: number) {
+    const group = await this.prisma.course_class_group.findUnique({
+      where: { id: classGroupId },
+      select: { id: true, course_id: true, capacity: true },
+    });
+    if (!group) throw new NotFoundException('Class not found');
+
+    const existing = await this.prisma.course_enrollment.findFirst({
+      where: { course_class_group_id: classGroupId, person_id: personId },
+    });
+    if (existing) {
+      if (existing.status === 'cancelled') {
+        return this.prisma.course_enrollment.update({
+          where: { id: existing.id },
+          data: { status: 'active', enrolled_at: new Date() },
+        });
+      }
+      throw new ConflictException('Student already enrolled');
+    }
+
+    return this.prisma.course_enrollment.create({
+      data: {
+        person_id: personId,
+        course_class_group_id: classGroupId,
+        course_id: group.course_id,
+        status: 'active',
+        enrolled_at: new Date(),
+      },
+    });
+  }
+
+  async createAndEnrollStudent(
+    classGroupId: number,
+    dto: { name: string; email?: string; phone?: string },
+  ) {
+    const group = await this.prisma.course_class_group.findUnique({
+      where: { id: classGroupId },
+      select: { id: true },
+    });
+
+    if (!group) {
+      throw new NotFoundException('Class not found');
+    }
+
+    const name = dto.name.trim();
+    const email = dto.email?.trim();
+    const phone = dto.phone?.trim();
+
+    if (!name) {
+      throw new BadRequestException('Name is required');
+    }
+
+    let personId: number;
+
+    if (email) {
+      const existingByEmail = await this.prisma.person.findFirst({
+        where: {
+          contact: {
+            some: {
+              value: { equals: email, mode: 'insensitive' },
+              contact_type: { code: { in: ['email', 'EMAIL'] } },
+            },
+          },
+        },
+        select: { id: true },
+      });
+
+      if (existingByEmail) {
+        personId = existingByEmail.id;
+      }
+    }
+
+    if (!personId) {
+      const [emailType, phoneType] = await Promise.all([
+        this.prisma.contact_type.findFirst({
+          where: { code: { in: ['email', 'EMAIL'] } },
+          select: { id: true },
+        }),
+        this.prisma.contact_type.findFirst({
+          where: { code: { in: ['mobile', 'MOBILE', 'phone', 'PHONE'] } },
+          orderBy: { id: 'asc' },
+          select: { id: true },
+        }),
+      ]);
+
+      const createdPerson = await this.prisma.person.create({
+        data: {
+          name,
+          type: 'individual',
+          status: 'active',
+        },
+        select: { id: true },
+      });
+
+      personId = createdPerson.id;
+
+      const contactsToCreate: Array<{
+        person_id: number;
+        contact_type_id: number;
+        value: string;
+        is_primary: boolean;
+      }> = [];
+
+      if (email && emailType) {
+        contactsToCreate.push({
+          person_id: personId,
+          contact_type_id: emailType.id,
+          value: email,
+          is_primary: true,
+        });
+      }
+
+      if (phone && phoneType) {
+        contactsToCreate.push({
+          person_id: personId,
+          contact_type_id: phoneType.id,
+          value: phone,
+          is_primary: true,
+        });
+      }
+
+      if (contactsToCreate.length > 0) {
+        await this.prisma.contact.createMany({
+          data: contactsToCreate,
+        });
+      }
+    }
+
+    const person = await this.prisma.person.findUnique({
+      where: { id: personId },
+      include: {
+        contact: {
+          select: {
+            value: true,
+            contact_type: { select: { code: true } },
+          },
+        },
+      },
+    });
+
+    return {
+      id: person?.id,
+      nome: person?.name ?? '',
+      email:
+        person?.contact.find((c) => this.isEmailCode(c.contact_type.code))
+          ?.value ?? '',
+    };
+  }
+
+  async removeStudent(classGroupId: number, personId: number) {
+    const enrollment = await this.prisma.course_enrollment.findFirst({
+      where: {
+        course_class_group_id: classGroupId,
+        person_id: personId,
+        status: { not: 'cancelled' },
+      },
+    });
+    if (!enrollment) throw new NotFoundException('Enrollment not found');
+
+    await this.prisma.course_enrollment.update({
+      where: { id: enrollment.id },
+      data: { status: 'cancelled' },
+    });
+    return { success: true };
+  }
+
+  async getStudentProfile(classGroupId: number, personId: number) {
+    const enrollment = await this.prisma.course_enrollment.findFirst({
+      where: {
+        course_class_group_id: classGroupId,
+        person_id: personId,
+        status: { not: 'cancelled' },
+      },
+      include: {
+        person: {
+          select: {
+            id: true,
+            name: true,
+            contact: {
+              select: {
+                id: true,
+                value: true,
+                contact_type: { select: { code: true } },
+              },
+            },
+          },
+        },
+      },
+    });
+
+    if (!enrollment) {
+      throw new NotFoundException('Student not found in this class');
+    }
+
+    const email =
+      enrollment.person.contact.find((c) => this.isEmailCode(c.contact_type.code))
+        ?.value ?? '';
+    const phone =
+      enrollment.person.contact.find((c) => this.isPhoneCode(c.contact_type.code))
+        ?.value ?? '';
+
+    return {
+      id: enrollment.person.id,
+      enrollmentId: enrollment.id,
+      nome: enrollment.person.name,
+      email,
+      telefone: phone,
+      matriculadoEm: enrollment.enrolled_at,
+      progresso: enrollment.progress_percent,
+      status: enrollment.status,
+    };
+  }
+
+  async updateStudentProfile(
+    classGroupId: number,
+    personId: number,
+    dto: { name?: string; email?: string; phone?: string },
+  ) {
+    const enrollment = await this.prisma.course_enrollment.findFirst({
+      where: {
+        course_class_group_id: classGroupId,
+        person_id: personId,
+        status: { not: 'cancelled' },
+      },
+      select: { id: true },
+    });
+
+    if (!enrollment) {
+      throw new NotFoundException('Student not found in this class');
+    }
+
+    const name = dto.name?.trim();
+    const email = dto.email?.trim();
+    const phone = dto.phone?.trim();
+
+    if (dto.name !== undefined && !name) {
+      throw new BadRequestException('Name is required');
+    }
+
+    if (name) {
+      await this.prisma.person.update({
+        where: { id: personId },
+        data: { name },
+      });
+    }
+
+    const [emailType, phoneType] = await Promise.all([
+      this.prisma.contact_type.findFirst({
+        where: { code: { in: ['email', 'EMAIL'] } },
+        select: { id: true },
+      }),
+      this.prisma.contact_type.findFirst({
+        where: { code: { in: ['mobile', 'MOBILE', 'phone', 'PHONE'] } },
+        orderBy: { id: 'asc' },
+        select: { id: true },
+      }),
+    ]);
+
+    if (dto.email !== undefined && emailType) {
+      const existingEmail = await this.prisma.contact.findFirst({
+        where: { person_id: personId, contact_type_id: emailType.id },
+        select: { id: true },
+      });
+
+      if (email) {
+        if (existingEmail) {
+          await this.prisma.contact.update({
+            where: { id: existingEmail.id },
+            data: { value: email },
+          });
+        } else {
+          await this.prisma.contact.create({
+            data: {
+              person_id: personId,
+              contact_type_id: emailType.id,
+              value: email,
+              is_primary: true,
+            },
+          });
+        }
+      } else if (existingEmail) {
+        await this.prisma.contact.delete({ where: { id: existingEmail.id } });
+      }
+    }
+
+    if (dto.phone !== undefined) {
+      const existingPhone = await this.prisma.contact.findFirst({
+        where: {
+          person_id: personId,
+          contact_type: { code: { in: ['mobile', 'MOBILE', 'phone', 'PHONE'] } },
+        },
+        orderBy: { id: 'asc' },
+        select: { id: true },
+      });
+
+      if (phone) {
+        if (existingPhone) {
+          await this.prisma.contact.update({
+            where: { id: existingPhone.id },
+            data: { value: phone },
+          });
+        } else if (phoneType) {
+          await this.prisma.contact.create({
+            data: {
+              person_id: personId,
+              contact_type_id: phoneType.id,
+              value: phone,
+              is_primary: true,
+            },
+          });
+        }
+      } else if (existingPhone) {
+        await this.prisma.contact.delete({ where: { id: existingPhone.id } });
+      }
+    }
+
+    return this.getStudentProfile(classGroupId, personId);
+  }
+
+  async searchPeople(search: string, classGroupId?: number) {
+    const q = search.trim();
+    if (!q) return [];
+
+    const enrolledIds = classGroupId
+      ? (
+          await this.prisma.course_enrollment.findMany({
+            where: {
+              course_class_group_id: classGroupId,
+              status: { not: 'cancelled' },
+            },
+            select: { person_id: true },
+          })
+        ).map((e) => e.person_id)
+      : [];
+
+    const people = await this.prisma.person.findMany({
+      where: {
+        AND: [
+          {
+            OR: [
+              { name: { contains: q, mode: 'insensitive' } },
+              {
+                contact: {
+                  some: {
+                    value: { contains: q, mode: 'insensitive' },
+                    contact_type: { code: { in: ['email', 'EMAIL'] } },
+                  },
+                },
+              },
+            ],
+          },
+          enrolledIds.length > 0 ? { id: { notIn: enrolledIds } } : {},
+        ],
+      },
+      include: {
+        contact: {
+          select: { value: true, contact_type: { select: { code: true } } },
+        },
+      },
+      take: 20,
+    });
+
+    const personIds = people.map((person) => person.id);
+
+    const [instructors, enrolledPeople] =
+      personIds.length > 0
+        ? await Promise.all([
+            this.prisma.instructor.findMany({
+              where: {
+                person_id: { in: personIds },
+                status: 'active',
+              },
+              select: {
+                person_id: true,
+                can_teach_courses: true,
+              },
+            }),
+            this.prisma.course_enrollment.findMany({
+              where: {
+                person_id: { in: personIds },
+                status: { not: 'cancelled' },
+              },
+              select: { person_id: true },
+              distinct: ['person_id'],
+            }),
+          ])
+        : [[], []];
+
+    const instructorByPersonId = new Map(
+      instructors.map((instructor) => [instructor.person_id, instructor]),
+    );
+    const enrolledPersonIds = new Set(
+      enrolledPeople.map((enrollment) => enrollment.person_id),
+    );
+
+    return people.map((p) => {
+      const instructor = instructorByPersonId.get(p.id);
+      const isInstructor = Boolean(instructor);
+      const canTeachCourses = Boolean(instructor?.can_teach_courses);
+      const isStudentByEnrollment = enrolledPersonIds.has(p.id);
+
+      return {
+        id: p.id,
+        nome: p.name,
+        email:
+          p.contact.find((c) => this.isEmailCode(c.contact_type.code))
+            ?.value ?? '',
+        isInstructor,
+        canTeachCourses,
+        isStudentByEnrollment,
+      };
+    });
+  }
+
+  // ── Sessions ─────────────────────────────────────────────────────────────────
+
+  async listSessions(classGroupId: number) {
+    const group = await this.prisma.course_class_group.findUnique({
+      where: { id: classGroupId },
+      select: { id: true },
+    });
+    if (!group) throw new NotFoundException('Class not found');
+
+    const sessions = await this.prisma.course_class_session.findMany({
+      where: { course_class_group_id: classGroupId },
+      orderBy: [{ session_date: 'asc' }, { occurrence_index: 'asc' }],
+      include: this.getSessionInclude(),
+    });
+
+    return sessions.map((s) => this.mapSession(s));
+  }
+
+  async createSession(classGroupId: number, dto: CreateSessionDto) {
+    const group = await this.prisma.course_class_group.findUnique({
+      where: { id: classGroupId },
+      select: { id: true },
+    });
+    if (!group) throw new NotFoundException('Class not found');
+
+    if (dto.instructorId) {
+      await this.assertInstructorExists(dto.instructorId);
+    }
+
+    const created = await this.prisma.$transaction((tx) =>
+      this.createSessionSeriesInTransaction(tx, classGroupId, dto),
+    );
+
+    if (!created) {
+      throw new BadRequestException('No sessions were generated for the provided recurrence');
+    }
+
+    return this.mapSession(created);
+  }
+
+  private async createSessionSeriesInTransaction(
+    tx: Prisma.TransactionClient,
+    classGroupId: number,
+    dto: CreateSessionDto,
+    options?: { minDate?: Date },
+  ) {
+    const normalizedRecurrence = dto.recurrence
+      ? this.normalizeSessionRecurrence(dto.recurrence, dto.sessionDate)
+      : null;
+    const fullOccurrenceDates = normalizedRecurrence
+      ? this.buildRecurringSessionDates(dto.sessionDate, normalizedRecurrence)
+      : [this.toSessionDate(dto.sessionDate)];
+    const occurrenceDates = options?.minDate
+      ? fullOccurrenceDates.filter(
+          (date) =>
+            this.normalizeSessionDate(date).getTime() >=
+            this.normalizeSessionDate(options.minDate!).getTime(),
+        )
+      : fullOccurrenceDates;
+
+    if (occurrenceDates.length === 0) {
+      return null;
+    }
+
+    const recurrenceId = normalizedRecurrence ? randomUUID() : null;
+    const recurrenceRule = normalizedRecurrence
+      ? JSON.stringify(normalizedRecurrence)
+      : null;
+
+    const first = await tx.course_class_session.create({
+      data: {
+        course_class_group_id: classGroupId,
+        title: dto.title,
+        description: dto.description ?? null,
+        session_date: occurrenceDates[0],
+        start_time: dto.startTime,
+        end_time: dto.endTime,
+        location: dto.location ?? null,
+        meeting_url: dto.meetingUrl ?? null,
+        color: dto.color ?? null,
+        status: dto.status ?? 'scheduled',
+        recurrence_id: recurrenceId,
+        recurrence_rule: recurrenceRule,
+        occurrence_index: normalizedRecurrence ? 0 : null,
+        is_exception: false,
+        ...(dto.instructorId && {
+          course_class_session_instructor: {
+            create: {
+              instructor_id: dto.instructorId,
+              role: 'lead',
+            },
+          },
+        }),
+      },
+      include: this.getSessionInclude(),
+    });
+
+    for (let index = 1; index < occurrenceDates.length; index += 1) {
+      await tx.course_class_session.create({
+        data: {
+          course_class_group_id: classGroupId,
+          title: dto.title,
+          description: dto.description ?? null,
+          session_date: occurrenceDates[index],
+          start_time: dto.startTime,
+          end_time: dto.endTime,
+          location: dto.location ?? null,
+          meeting_url: dto.meetingUrl ?? null,
+          color: dto.color ?? null,
+          status: dto.status ?? 'scheduled',
+          recurrence_id: recurrenceId,
+          recurrence_rule: recurrenceRule,
+          occurrence_index: normalizedRecurrence ? index : null,
+          is_exception: false,
+          parent_session_id: first.id,
+          ...(dto.instructorId && {
+            course_class_session_instructor: {
+              create: {
+                instructor_id: dto.instructorId,
+                role: 'lead',
+              },
+            },
+          }),
+        },
+      });
+    }
+
+    return first;
+  }
+
+  async updateSession(
+    classGroupId: number,
+    sessionId: number,
+    dto: UpdateSessionDto,
+  ) {
+    const session = await this.prisma.course_class_session.findFirst({
+      where: { id: sessionId, course_class_group_id: classGroupId },
+    });
+    if (!session) throw new NotFoundException('Session not found');
+
+    if (dto.instructorId) {
+      await this.assertInstructorExists(dto.instructorId);
+    }
+
+    const scope: SessionScope = dto.applyScope ?? 'single';
+    const normalizedRecurrence = dto.recurrence
+      ? this.normalizeSessionRecurrence(
+          dto.recurrence,
+          dto.sessionDate ?? this.toDateKey(session.session_date),
+        )
+      : null;
+    const nextRecurrenceRule = normalizedRecurrence
+      ? JSON.stringify(normalizedRecurrence)
+      : dto.recurrence === undefined
+        ? undefined
+        : null;
+
+    if (scope === 'series' && session.recurrence_id) {
+      const seriesSessions = await this.prisma.course_class_session.findMany({
+        where: {
+          course_class_group_id: classGroupId,
+          recurrence_id: session.recurrence_id,
+        },
+        orderBy: [{ session_date: 'asc' }, { occurrence_index: 'asc' }],
+      });
+
+      const dayDelta = dto.sessionDate
+        ? this.diffInDays(
+            this.toSessionDate(dto.sessionDate),
+            this.normalizeSessionDate(session.session_date),
+          )
+        : 0;
+
+      await this.prisma.$transaction(async (tx) => {
+        for (const seriesSession of seriesSessions) {
+          await tx.course_class_session.update({
+            where: { id: seriesSession.id },
+            data: {
+              ...(dto.title !== undefined && { title: dto.title }),
+              ...(dto.description !== undefined && {
+                description: dto.description,
+              }),
+              ...(dto.startTime !== undefined && { start_time: dto.startTime }),
+              ...(dto.endTime !== undefined && { end_time: dto.endTime }),
+              ...(dto.location !== undefined && { location: dto.location }),
+              ...(dto.meetingUrl !== undefined && {
+                meeting_url: dto.meetingUrl,
+              }),
+              ...(dto.color !== undefined && { color: dto.color }),
+              ...(dto.status !== undefined && { status: dto.status }),
+              ...(dto.sessionDate !== undefined && {
+                session_date: this.addDaysUtc(seriesSession.session_date, dayDelta),
+              }),
+              ...(nextRecurrenceRule !== undefined && {
+                recurrence_rule: nextRecurrenceRule,
+              }),
+            },
+          });
+
+          if (dto.instructorId !== undefined) {
+            await tx.course_class_session_instructor.deleteMany({
+              where: { course_class_session_id: seriesSession.id },
+            });
+
+            if (dto.instructorId) {
+              await tx.course_class_session_instructor.create({
+                data: {
+                  course_class_session_id: seriesSession.id,
+                  instructor_id: dto.instructorId,
+                  role: 'lead',
+                },
+              });
+            }
+          }
+        }
+      });
+
+      const updated = await this.prisma.course_class_session.findUnique({
+        where: { id: sessionId },
+        include: this.getSessionInclude(),
+      });
+
+      if (!updated) {
+        throw new NotFoundException('Session not found');
+      }
+
+      return this.mapSession(updated);
+    }
+
+    const updated = await this.prisma.course_class_session.update({
+      where: { id: sessionId },
+      data: {
+        ...(dto.title !== undefined && { title: dto.title }),
+        ...(dto.description !== undefined && { description: dto.description }),
+        ...(dto.sessionDate !== undefined && {
+          session_date: this.toSessionDate(dto.sessionDate),
+        }),
+        ...(dto.startTime !== undefined && { start_time: dto.startTime }),
+        ...(dto.endTime !== undefined && { end_time: dto.endTime }),
+        ...(dto.location !== undefined && { location: dto.location }),
+        ...(dto.meetingUrl !== undefined && { meeting_url: dto.meetingUrl }),
+        ...(dto.color !== undefined && { color: dto.color }),
+        ...(dto.status !== undefined && { status: dto.status }),
+        ...(nextRecurrenceRule !== undefined && {
+          recurrence_rule: nextRecurrenceRule,
+        }),
+        ...(session.recurrence_id && { is_exception: true }),
+        ...(dto.instructorId !== undefined && {
+          course_class_session_instructor: {
+            deleteMany: {},
+            ...(dto.instructorId
+              ? {
+                  create: {
+                    instructor_id: dto.instructorId,
+                    role: 'lead',
+                  },
+                }
+              : {}),
+          },
+        }),
+      },
+      include: this.getSessionInclude(),
+    });
+
+    return this.mapSession(updated);
+  }
+
+  async deleteSession(
+    classGroupId: number,
+    sessionId: number,
+    scope: SessionScope = 'single',
+  ) {
+    const session = await this.prisma.course_class_session.findFirst({
+      where: { id: sessionId, course_class_group_id: classGroupId },
+    });
+    if (!session) throw new NotFoundException('Session not found');
+
+    if (scope === 'series' && session.recurrence_id) {
+      await this.prisma.course_class_session.deleteMany({
+        where: {
+          course_class_group_id: classGroupId,
+          recurrence_id: session.recurrence_id,
+        },
+      });
+      return { success: true };
+    }
+
+    await this.prisma.course_class_session.delete({ where: { id: sessionId } });
+    return { success: true };
+  }
+
+  // ── Attendance ───────────────────────────────────────────────────────────────
+
+  async getAttendance(classGroupId: number, sessionId: number) {
+    const session = await this.prisma.course_class_session.findFirst({
+      where: { id: sessionId, course_class_group_id: classGroupId },
+    });
+    if (!session) throw new NotFoundException('Session not found');
+
+    return this.prisma.course_class_attendance.findMany({
+      where: { course_class_session_id: sessionId },
+      include: {
+        person_course_class_attendance_student_idToperson: {
+          select: { id: true, name: true },
+        },
+      },
+    });
+  }
+
+  async saveAttendance(
+    classGroupId: number,
+    sessionId: number,
+    entries: Array<{ studentId: number; present: boolean; justification?: string }>,
+  ) {
+    const session = await this.prisma.course_class_session.findFirst({
+      where: { id: sessionId, course_class_group_id: classGroupId },
+    });
+    if (!session) throw new NotFoundException('Session not found');
+
+    await this.prisma.$transaction(async (tx) => {
+      const normalizedEntries = Array.from(
+        new Map(entries.map((entry) => [entry.studentId, entry])).values(),
+      );
+      const selectedStudentIds = normalizedEntries.map((entry) => entry.studentId);
+
+      if (selectedStudentIds.length > 0) {
+        await tx.course_class_attendance.deleteMany({
+          where: {
+            course_class_session_id: sessionId,
+            student_id: { notIn: selectedStudentIds },
+          },
+        });
+      } else {
+        await tx.course_class_attendance.deleteMany({
+          where: { course_class_session_id: sessionId },
+        });
+      }
+
+      for (const e of normalizedEntries) {
+        const existing = await tx.course_class_attendance.findFirst({
+          where: {
+            course_class_session_id: sessionId,
+            student_id: e.studentId,
+          },
+          select: { id: true },
+        });
+
+        if (existing) {
+          await tx.course_class_attendance.update({
+            where: { id: existing.id },
+            data: {
+              present: e.present,
+              justification: e.justification ?? null,
+            },
+          });
+          continue;
+        }
+
+        await tx.course_class_attendance.create({
+          data: {
+            course_class_session_id: sessionId,
+            student_id: e.studentId,
+            present: e.present,
+            justification: e.justification ?? null,
+          },
+        });
+      }
+    });
+
+    return { success: true };
+  }
+
+  private mapSession(s: any) {
+    const leadInstructor = s.course_class_session_instructor?.find(
+      (entry: any) => entry.role === 'lead',
+    );
+    const fallbackInstructor = s.course_class_session_instructor?.[0];
+    const sessionInstructor = leadInstructor ?? fallbackInstructor;
+
+    const recurrence = this.parseRecurrenceRule(s.recurrence_rule);
+
+    return {
+      id: s.id,
+      titulo: s.title,
+      descricao: s.description ?? '',
+      data: s.session_date,
+      horaInicio: s.start_time,
+      horaFim: s.end_time,
+      local: s.location ?? '',
+      meetingUrl: s.meeting_url ?? '',
+      cor: s.color ?? undefined,
+      status: s.status,
+      tipo: s.meeting_url ? 'online' : ('presencial' as const),
+      instructorId: sessionInstructor?.instructor_id ?? null,
+      instructorName:
+        sessionInstructor?.instructor?.person?.name ?? '',
+      recurrenceId: s.recurrence_id ?? null,
+      occurrenceIndex: s.occurrence_index ?? null,
+      isException: Boolean(s.is_exception),
+      recurrence,
+      isRecurring: Boolean(s.recurrence_id),
+    };
+  }
+
+  private normalizeSessionRecurrence(
+    recurrence: SessionRecurrenceDto,
+    sessionDate: string,
+  ): NormalizedSessionRecurrence {
+    const startDate = this.toSessionDate(sessionDate);
+    const untilDate = this.toSessionDate(recurrence.until);
+
+    if (untilDate.getTime() < startDate.getTime()) {
+      throw new BadRequestException('Recurrence end date must be on or after session date');
+    }
+
+    const normalizedDays = recurrence.daysOfWeek?.length
+      ? [...new Set(recurrence.daysOfWeek)].sort(
+          (left, right) =>
+            ClassGroupService.DAY_ORDER.indexOf(left) -
+            ClassGroupService.DAY_ORDER.indexOf(right),
+        )
+      : recurrence.frequency === 'weekly'
+        ? [this.getDayCode(startDate)]
+        : undefined;
+
+    return {
+      frequency: recurrence.frequency,
+      interval: recurrence.interval ?? 1,
+      until: this.toDateKey(untilDate),
+      ...(normalizedDays?.length ? { daysOfWeek: normalizedDays } : {}),
+    };
+  }
+
+  private buildRecurringSessionDates(
+    sessionDate: string,
+    recurrence: NormalizedSessionRecurrence,
+  ) {
+    const startDate = this.toSessionDate(sessionDate);
+    const untilDate = this.toSessionDate(recurrence.until);
+
+    switch (recurrence.frequency) {
+      case 'daily':
+        return this.buildDailyOccurrences(startDate, untilDate, recurrence.interval);
+      case 'weekly':
+        return this.buildWeeklyOccurrences(
+          startDate,
+          untilDate,
+          recurrence.interval,
+          recurrence.daysOfWeek,
+        );
+      case 'monthly':
+        return this.buildMonthlyOccurrences(startDate, untilDate, recurrence.interval);
+      case 'yearly':
+        return this.buildYearlyOccurrences(startDate, untilDate, recurrence.interval);
+      default:
+        return [startDate];
+    }
+  }
+
+  private buildDailyOccurrences(startDate: Date, untilDate: Date, interval: number) {
+    const dates: Date[] = [];
+
+    for (
+      let current = startDate;
+      current.getTime() <= untilDate.getTime();
+      current = this.addDaysUtc(current, interval)
+    ) {
+      dates.push(current);
+    }
+
+    return dates;
+  }
+
+  private buildWeeklyOccurrences(
+    startDate: Date,
+    untilDate: Date,
+    interval: number,
+    daysOfWeek?: SessionRecurrenceDay[],
+  ) {
+    const dates: Date[] = [];
+    const weekStart = this.startOfWeekMonday(startDate);
+    const normalizedDays = daysOfWeek?.length
+      ? daysOfWeek
+      : [this.getDayCode(startDate)];
+
+    for (
+      let currentWeek = weekStart;
+      currentWeek.getTime() <= untilDate.getTime();
+      currentWeek = this.addDaysUtc(currentWeek, interval * 7)
+    ) {
+      for (const dayCode of normalizedDays) {
+        const candidate = this.addDaysUtc(
+          currentWeek,
+          ClassGroupService.DAY_ORDER.indexOf(dayCode),
+        );
+
+        if (candidate.getTime() < startDate.getTime()) {
+          continue;
+        }
+
+        if (candidate.getTime() > untilDate.getTime()) {
+          continue;
+        }
+
+        dates.push(candidate);
+      }
+    }
+
+    return dates.sort((left, right) => left.getTime() - right.getTime());
+  }
+
+  private buildMonthlyOccurrences(startDate: Date, untilDate: Date, interval: number) {
+    const dates: Date[] = [];
+
+    for (let offset = 0; ; offset += interval) {
+      const candidate = this.addMonthsUtc(startDate, offset);
+
+      if (!candidate) {
+        continue;
+      }
+
+      if (candidate.getTime() > untilDate.getTime()) {
+        break;
+      }
+
+      dates.push(candidate);
+    }
+
+    return dates;
+  }
+
+  private buildYearlyOccurrences(startDate: Date, untilDate: Date, interval: number) {
+    const dates: Date[] = [];
+
+    for (let offset = 0; ; offset += interval) {
+      const candidate = this.addYearsUtc(startDate, offset);
+
+      if (!candidate) {
+        continue;
+      }
+
+      if (candidate.getTime() > untilDate.getTime()) {
+        break;
+      }
+
+      dates.push(candidate);
+    }
+
+    return dates;
+  }
+
+  private parseRecurrenceRule(value?: string | null): NormalizedSessionRecurrence | null {
+    if (!value) {
+      return null;
+    }
+
+    try {
+      const parsed = JSON.parse(value) as NormalizedSessionRecurrence;
+      return parsed?.frequency ? parsed : null;
+    } catch {
+      return null;
+    }
+  }
+
+  private toSessionDate(value: string | Date) {
+    if (value instanceof Date) {
+      return this.normalizeSessionDate(value);
+    }
+
+    const match = /^(\d{4})-(\d{2})-(\d{2})/.exec(value ?? '');
+
+    if (!match) {
+      throw new BadRequestException('Invalid session date');
+    }
+
+    return new Date(
+      Date.UTC(Number(match[1]), Number(match[2]) - 1, Number(match[3]), 12, 0, 0, 0),
+    );
+  }
+
+  private normalizeSessionDate(value: Date) {
+    return new Date(
+      Date.UTC(
+        value.getUTCFullYear(),
+        value.getUTCMonth(),
+        value.getUTCDate(),
+        12,
+        0,
+        0,
+        0,
+      ),
+    );
+  }
+
+  private toDateKey(value: Date) {
+    return value.toISOString().slice(0, 10);
+  }
+
+  private getDayCode(value: Date): SessionRecurrenceDay {
+    return ClassGroupService.UTC_DAY_TO_CODE[value.getUTCDay()];
+  }
+
+  private startOfWeekMonday(value: Date) {
+    const day = value.getUTCDay();
+    const diff = day === 0 ? -6 : 1 - day;
+    return this.addDaysUtc(value, diff);
+  }
+
+  private addDaysUtc(value: Date, amount: number) {
+    const next = new Date(value.getTime());
+    next.setUTCDate(next.getUTCDate() + amount);
+    return this.normalizeSessionDate(next);
+  }
+
+  private addMonthsUtc(value: Date, amount: number) {
+    const year = value.getUTCFullYear();
+    const month = value.getUTCMonth() + amount;
+    const day = value.getUTCDate();
+    const candidate = new Date(Date.UTC(year, month, day, 12, 0, 0, 0));
+
+    if (candidate.getUTCDate() !== day) {
+      return null;
+    }
+
+    return candidate;
+  }
+
+  private addYearsUtc(value: Date, amount: number) {
+    const year = value.getUTCFullYear() + amount;
+    const month = value.getUTCMonth();
+    const day = value.getUTCDate();
+    const candidate = new Date(Date.UTC(year, month, day, 12, 0, 0, 0));
+
+    if (candidate.getUTCMonth() !== month || candidate.getUTCDate() !== day) {
+      return null;
+    }
+
+    return candidate;
+  }
+
+  private diffInDays(left: Date, right: Date) {
+    const msPerDay = 24 * 60 * 60 * 1000;
+    return Math.round(
+      (this.normalizeSessionDate(left).getTime() - this.normalizeSessionDate(right).getTime()) /
+        msPerDay,
+    );
+  }
+
+  private async assertInstructorExists(instructorId: number) {
+    const instructor = await this.prisma.instructor.findUnique({
+      where: { id: instructorId },
+      select: { id: true },
+    });
+
+    if (!instructor) {
+      throw new NotFoundException('Instructor not found');
+    }
+  }
+
+  private handlePrismaError(error: unknown): never {
+    if (
+      error instanceof PrismaClientKnownRequestError &&
+      error.code === 'P2002'
+    ) {
+      throw new ConflictException('Class code already exists');
+    }
+
+    throw error;
+  }
+}