@hed-hog/lms 0.0.319 → 0.0.321

package/src/enterprise/training/training-admin.service.ts

@@ -0,0 +1,2523 @@
+import { PrismaService } from '@hed-hog/api-prisma';
+import {
+    BadRequestException,
+    ConflictException,
+    ForbiddenException,
+    Injectable,
+    NotFoundException,
+} from '@nestjs/common';
+
+@Injectable()
+export class TrainingAdminService {
+  constructor(private readonly prisma: PrismaService) {}
+
+  async getDashboard(userId: number, requestedEnterpriseId?: number) {
+    if (requestedEnterpriseId !== undefined) {
+      const allowed = await this.prisma.enterprise_user.findFirst({
+        where: { user_id: userId, enterprise_id: requestedEnterpriseId, status: 'active' },
+        select: { enterprise_id: true },
+      });
+      if (!allowed) {
+        throw new ForbiddenException('Access denied to the requested enterprise');
+      }
+    }
+
+    const enterpriseUser = requestedEnterpriseId !== undefined
+      ? { enterprise_id: requestedEnterpriseId }
+      : await this.prisma.enterprise_user.findFirst({
+          where: { user_id: userId, status: 'active' },
+          select: { enterprise_id: true },
+        });
+
+    if (!enterpriseUser) {
+      throw new NotFoundException('No active enterprise found for this user');
+    }
+
+    const enterpriseId = enterpriseUser.enterprise_id;
+    const now = new Date();
+    const currentMonthStart = this.startOfMonth(now);
+    const previousMonthStart = this.startOfMonth(this.addMonths(now, -1));
+
+    const [kpis, upcomingClasses, alerts, licenseInfo] = await Promise.all([
+      this.getKpis(enterpriseId, now, currentMonthStart, previousMonthStart),
+      this.getUpcomingClasses(enterpriseId, now),
+      this.getAlerts(enterpriseId),
+      this.getLicenseInfo(enterpriseId),
+    ]);
+
+    return {
+      kpis,
+      upcomingClasses,
+      alerts,
+      licenseInfo,
+    };
+  }
+
+  // ── Private helpers ───────────────────────────────────────────────────────────
+
+  private async getKpis(
+    enterpriseId: number,
+    now: Date,
+    currentMonthStart: Date,
+    previousMonthStart: Date,
+  ) {
+    const previousMonthEnd = this.endOfMonth(this.addMonths(now, -1));
+
+    const [
+      totalStudents,
+      previousTotalStudents,
+      activeClasses,
+      previousActiveClasses,
+      slotsInUse,
+      previousSlotsInUse,
+      avgProgress,
+    ] = await Promise.all([
+      this.prisma.enterprise_student.count({
+        where: { enterprise_id: enterpriseId },
+      }),
+      this.prisma.enterprise_student.count({
+        where: { enterprise_id: enterpriseId, created_at: { lt: currentMonthStart } },
+      }),
+      this.prisma.enterprise_class_group.count({
+        where: {
+          enterprise_id: enterpriseId,
+          course_class_group: { status: 'ongoing' },
+        },
+      }),
+      this.prisma.enterprise_class_group.count({
+        where: {
+          enterprise_id: enterpriseId,
+          course_class_group: { status: 'ongoing', created_at: { lt: currentMonthStart } },
+        },
+      }),
+      this.prisma.course_enrollment.count({
+        where: {
+          status: { not: 'cancelled' },
+          course_class_group: {
+            enterprise_class_group: { some: { enterprise_id: enterpriseId } },
+          },
+        },
+      }),
+      this.prisma.course_enrollment.count({
+        where: {
+          status: { not: 'cancelled' },
+          enrolled_at: { lt: currentMonthStart },
+          course_class_group: {
+            enterprise_class_group: { some: { enterprise_id: enterpriseId } },
+          },
+        },
+      }),
+      this.prisma.course_enrollment.aggregate({
+        where: {
+          status: { in: ['active', 'completed'] },
+          course_class_group: {
+            enterprise_class_group: { some: { enterprise_id: enterpriseId } },
+          },
+        },
+        _avg: { progress_percent: true },
+      }),
+    ]);
+
+    return {
+      totalStudents: {
+        value: totalStudents,
+        change: this.percentChange(totalStudents, previousTotalStudents),
+        changeType: 'percent' as const,
+      },
+      activeClasses: {
+        value: activeClasses,
+        change: activeClasses - previousActiveClasses,
+        changeType: 'absolute' as const,
+      },
+      slotsInUse: {
+        value: slotsInUse,
+        change: slotsInUse - previousSlotsInUse,
+        changeType: 'absolute' as const,
+      },
+      averageProgress: {
+        value: this.round(avgProgress._avg.progress_percent ?? 0, 1),
+        change: null,
+        changeType: 'percent' as const,
+      },
+    };
+  }
+
+  private async getUpcomingClasses(enterpriseId: number, now: Date) {
+    const rows = await this.prisma.enterprise_class_group.findMany({
+      where: {
+        enterprise_id: enterpriseId,
+        course_class_group: { status: { in: ['open', 'ongoing'] } },
+      },
+      take: 10,
+      include: {
+        course_class_group: {
+          include: {
+            course: {
+              select: {
+                id: true,
+                title: true,
+                course_image: {
+                  where: { image_type: { slug: 'course-logo' } },
+                  orderBy: { is_primary: 'desc' as const },
+                  take: 1,
+                  select: { file: { select: { location: true } } },
+                },
+              },
+            },
+            _count: {
+              select: {
+                course_enrollment: { where: { status: { not: 'cancelled' } } },
+              },
+            },
+            course_class_session: {
+              where: { session_date: { gte: now } },
+              orderBy: { session_date: 'asc' },
+              take: 1,
+              include: {
+                course_class_session_instructor: {
+                  where: { role: 'lead' },
+                  take: 1,
+                  include: {
+                    instructor: {
+                      include: { person: { select: { name: true } } },
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    });
+
+    return rows.map((row) => {
+      const cg = row.course_class_group;
+      const nextSession = cg.course_class_session[0] ?? null;
+      const leadInstructor =
+        nextSession?.course_class_session_instructor[0]?.instructor?.person?.name ?? null;
+
+      return {
+        id: cg.id,
+        name: cg.title,
+        courseId: cg.course?.id ?? null,
+        courseName: cg.course?.title ?? null,
+        courseLogoUrl: cg.course?.course_image?.[0]?.file?.location ?? null,
+        instructor: leadInstructor,
+        startDate: cg.start_date,
+        nextSession: nextSession
+          ? {
+              date: nextSession.session_date,
+              time: nextSession.start_time,
+              location: nextSession.location ?? null,
+            }
+          : null,
+        slots: cg._count.course_enrollment,
+        totalSlots: cg.capacity ?? null,
+        status: cg.status,
+        deliveryMode: cg.delivery_mode ?? null,
+      };
+    });
+  }
+
+  private async getLicenseInfo(enterpriseId: number) {
+    const [enterprise, totalStudents, activePersonRows] = await Promise.all([
+      this.prisma.enterprise.findUnique({
+        where: { id: enterpriseId },
+        select: { license_limit: true },
+      }),
+      this.prisma.enterprise_student.count({
+        where: { enterprise_id: enterpriseId },
+      }),
+      this.prisma.course_enrollment.findMany({
+        where: {
+          status: 'active',
+          course_class_group: {
+            enterprise_class_group: { some: { enterprise_id: enterpriseId } },
+          },
+        },
+        select: { person_id: true },
+        distinct: ['person_id'],
+      }),
+    ]);
+
+    return {
+      limit: (enterprise?.license_limit as number | null) ?? null,
+      totalStudents,
+      activeStudents: activePersonRows.length,
+    };
+  }
+
+  private async getAlerts(enterpriseId: number) {
+    const alerts: Array<{
+      type: string;
+      message: string;
+      severity: 'info' | 'warning' | 'danger';
+    }> = [];
+
+    // Classes near capacity (>= 90%)
+    const openRows = await this.prisma.enterprise_class_group.findMany({
+      where: {
+        enterprise_id: enterpriseId,
+        course_class_group: { status: 'open' },
+      },
+      include: {
+        course_class_group: {
+          include: {
+            _count: {
+              select: {
+                course_enrollment: { where: { status: { not: 'cancelled' } } },
+              },
+            },
+          },
+        },
+      },
+    });
+
+    for (const row of openRows) {
+      const cg = row.course_class_group;
+      const max = cg.capacity ?? 0;
+      if (max > 0 && cg._count.course_enrollment / max >= 0.9) {
+        alerts.push({
+          type: 'capacity',
+          message: `Turma "${cg.title}" está quase lotada (${cg._count.course_enrollment}/${max} vagas)`,
+          severity: 'warning',
+        });
+      }
+    }
+
+    // Open classes without any sessions scheduled
+    const withoutSessions = await this.prisma.enterprise_class_group.count({
+      where: {
+        enterprise_id: enterpriseId,
+        course_class_group: {
+          status: 'open',
+          course_class_session: { none: {} },
+        },
+      },
+    });
+
+    if (withoutSessions > 0) {
+      alerts.push({
+        type: 'no_sessions',
+        message: `${withoutSessions} turma(s) aberta(s) sem sessões agendadas`,
+        severity: 'info',
+      });
+    }
+
+    return alerts;
+  }
+
+  async getClassGroups(
+    userId: number,
+    options: {
+      enterpriseId?: number;
+      search?: string;
+      status?: string;
+      deliveryMode?: string;
+      instructorId?: number;
+    } = {},
+  ) {
+    if (options.enterpriseId !== undefined) {
+      const allowed = await this.prisma.enterprise_user.findFirst({
+        where: { user_id: userId, enterprise_id: options.enterpriseId, status: 'active' },
+        select: { enterprise_id: true },
+      });
+      if (!allowed) {
+        throw new ForbiddenException('Access denied to the requested enterprise');
+      }
+    }
+
+    const enterpriseUser =
+      options.enterpriseId !== undefined
+        ? { enterprise_id: options.enterpriseId }
+        : await this.prisma.enterprise_user.findFirst({
+            where: { user_id: userId, status: 'active' },
+            select: { enterprise_id: true },
+          });
+
+    if (!enterpriseUser) {
+      throw new NotFoundException('No active enterprise found for this user');
+    }
+
+    const enterpriseId = enterpriseUser.enterprise_id;
+    const { search, status, deliveryMode, instructorId } = options;
+    const now = new Date();
+
+    const classGroups = await this.prisma.course_class_group.findMany({
+      where: {
+        AND: [
+          { enterprise_class_group: { some: { enterprise_id: enterpriseId } } },
+          ...(status ? [{ status: status as any }] : []),
+          ...(deliveryMode ? [{ delivery_mode: deliveryMode as any }] : []),
+          ...(instructorId !== undefined ? [{ instructor_id: instructorId }] : []),
+          ...(search
+            ? [
+                {
+                  OR: [
+                    { title: { contains: search, mode: 'insensitive' as const } },
+                    { code: { contains: search, mode: 'insensitive' as const } },
+                    { course: { title: { contains: search, mode: 'insensitive' as const } } },
+                  ],
+                },
+              ]
+            : []),
+        ],
+      },
+      orderBy: { start_date: 'desc' },
+      include: {
+        course: {
+          select: {
+            id: true,
+            title: true,
+            course_image: {
+              where: { image_type: { slug: { in: ['course-logo', 'course-banner'] } } },
+              orderBy: { is_primary: 'desc' as const },
+              select: {
+                file: { select: { location: true } },
+                image_type: { select: { slug: true } },
+              },
+            },
+          },
+        },
+        instructor: {
+          include: { person: { select: { name: true } } },
+        },
+        _count: {
+          select: {
+            course_enrollment: { where: { status: { not: 'cancelled' } } },
+          },
+        },
+        course_class_session: {
+          where: { session_date: { gte: now } },
+          orderBy: { session_date: 'asc' },
+          take: 1,
+          select: { session_date: true, start_time: true, location: true },
+        },
+      },
+    });
+
+    const cgIds = classGroups.map((cg) => cg.id);
+
+    const completedCounts =
+      cgIds.length > 0
+        ? await this.prisma.course_enrollment.groupBy({
+            by: ['course_class_group_id'],
+            where: {
+              course_class_group_id: { in: cgIds },
+              status: { not: 'cancelled' },
+              completed_at: { not: null },
+            },
+            _count: true,
+          })
+        : [];
+
+    const completedCountMap = new Map(
+      completedCounts.map((r) => [r.course_class_group_id, r._count]),
+    );
+
+    const data = classGroups.map((cg) => {
+      const nextSession = cg.course_class_session[0] ?? null;
+      const totalEnrolled = cg._count.course_enrollment;
+      const completedCount = completedCountMap.get(cg.id) ?? 0;
+      const completionRate =
+        totalEnrolled > 0 ? this.round((completedCount / totalEnrolled) * 100, 0) : 0;
+
+      return {
+        id: cg.id,
+        name: cg.title,
+        code: cg.code ?? '',
+        courseId: cg.course?.id ?? null,
+        courseName: cg.course?.title ?? null,
+        courseLogoUrl:
+          cg.course?.course_image.find((ci) => ci.image_type?.slug === 'course-logo')?.file
+            ?.location ?? null,
+        courseBannerUrl:
+          cg.course?.course_image.find((ci) => ci.image_type?.slug === 'course-banner')?.file
+            ?.location ?? null,
+        instructorName: (cg as any).instructor?.person?.name ?? null,
+        instructorAvatarUrl: null as string | null,
+        startDate: cg.start_date,
+        endDate: cg.end_date ?? null,
+        nextSession: nextSession
+          ? {
+              date: nextSession.session_date,
+              time: nextSession.start_time,
+              location: nextSession.location ?? null,
+            }
+          : null,
+        slots: totalEnrolled,
+        totalSlots: cg.capacity ?? null,
+        status: cg.status,
+        deliveryMode: cg.delivery_mode ?? null,
+        completionRate,
+      };
+    });
+
+    return { data, total: data.length };
+  }
+
+  // ── Class-group detail endpoints ─────────────────────────────────────────────
+
+  private async assertAdminHasAccessToClassGroup(userId: number, classGroupId: number) {
+    const enterpriseUser = await this.prisma.enterprise_user.findFirst({
+      where: { user_id: userId, status: 'active' },
+      select: { enterprise_id: true },
+    });
+    if (!enterpriseUser) throw new NotFoundException('No active enterprise found for this user');
+
+    const cg = await this.prisma.course_class_group.findFirst({
+      where: {
+        id: classGroupId,
+        enterprise_class_group: { some: { enterprise_id: enterpriseUser.enterprise_id } },
+      },
+      select: { id: true },
+    });
+    if (!cg) throw new NotFoundException('Class group not found or not accessible');
+    return enterpriseUser.enterprise_id;
+  }
+
+  async getClassGroupDetail(userId: number, classGroupId: number) {
+    await this.assertAdminHasAccessToClassGroup(userId, classGroupId);
+    const now = new Date();
+
+    const cg = await this.prisma.course_class_group.findUnique({
+      where: { id: classGroupId },
+      include: {
+        course: { select: { id: true, title: true } },
+        instructor: { select: { person: { select: { name: true } } } },
+        _count: {
+          select: {
+            course_enrollment: { where: { status: { not: 'cancelled' } } },
+            course_class_session: true,
+          },
+        },
+        course_class_session: {
+          where: { session_date: { gte: now } },
+          orderBy: { session_date: 'asc' },
+          take: 1,
+          select: { session_date: true, start_time: true, location: true, meeting_url: true },
+        },
+      },
+    });
+    if (!cg) throw new NotFoundException(`Class group #${classGroupId} not found`);
+
+    const completedSessions = await this.prisma.course_class_session.count({
+      where: { course_class_group_id: classGroupId, session_date: { lt: now } },
+    });
+
+    const pastSessions = await this.prisma.course_class_session.findMany({
+      where: { course_class_group_id: classGroupId, session_date: { lt: now } },
+      select: {
+        id: true,
+        course_class_attendance: { where: { present: true }, select: { student_id: true } },
+      },
+    });
+
+    const totalEnrolled = cg._count.course_enrollment;
+    let avgAttendance = 0;
+    if (pastSessions.length > 0 && totalEnrolled > 0) {
+      const pcts = pastSessions.map((s) => (s.course_class_attendance.length / totalEnrolled) * 100);
+      avgAttendance = this.round(pcts.reduce((a, b) => a + b, 0) / pcts.length, 0);
+    }
+
+    const completedEnrollments = await this.prisma.course_enrollment.count({
+      where: { course_class_group_id: classGroupId, status: { not: 'cancelled' }, completed_at: { not: null } },
+    });
+    const completionRate = totalEnrolled > 0 ? this.round((completedEnrollments / totalEnrolled) * 100, 0) : 0;
+
+    const nextSession = cg.course_class_session[0] ?? null;
+    return {
+      id: cg.id,
+      courseName: cg.course?.title ?? null,
+      className: cg.title,
+      code: cg.code ?? null,
+      instructorName: cg.instructor?.person?.name ?? null,
+      instructorAvatarUrl: null as string | null,
+      instructorBio: null as string | null,
+      startDate: cg.start_date,
+      endDate: cg.end_date ?? null,
+      status: cg.status,
+      deliveryMode: cg.delivery_mode,
+      totalSlots: cg.capacity ?? null,
+      enrolledCount: totalEnrolled,
+      totalSessions: cg._count.course_class_session,
+      completedSessions,
+      avgAttendance,
+      completionRate,
+      nextSession: nextSession
+        ? {
+            date: nextSession.session_date,
+            time: nextSession.start_time,
+            location: nextSession.location ?? null,
+            meetingUrl: nextSession.meeting_url ?? null,
+          }
+        : null,
+    };
+  }
+
+  async getClassGroupStudents(
+    userId: number,
+    classGroupId: number,
+    params: { page?: number; pageSize?: number; search?: string; status?: string } = {},
+  ) {
+    await this.assertAdminHasAccessToClassGroup(userId, classGroupId);
+    const page = Math.max(Number(params.page) || 1, 1);
+    const pageSize = Math.max(Number(params.pageSize) || 20, 1);
+    const skip = (page - 1) * pageSize;
+
+    const where: any = {
+      course_class_group_id: classGroupId,
+      status: { not: 'cancelled' },
+    };
+    if (params.search) {
+      where.person = { name: { contains: params.search, mode: 'insensitive' } };
+    }
+
+    const [enrollments, total, totalSessions] = await Promise.all([
+      this.prisma.course_enrollment.findMany({
+        where,
+        skip,
+        take: pageSize,
+        orderBy: { person: { name: 'asc' } },
+        include: { person: { select: { id: true, name: true } } },
+      }),
+      this.prisma.course_enrollment.count({ where }),
+      this.prisma.course_class_session.count({ where: { course_class_group_id: classGroupId } }),
+    ]);
+
+    if (enrollments.length === 0) {
+      return { total, page, pageSize, lastPage: Math.max(1, Math.ceil(total / pageSize)), data: [] };
+    }
+
+    const personIds = enrollments.map((e) => e.person_id).filter(Boolean) as number[];
+    const attendanceRows = await this.prisma.course_class_attendance.groupBy({
+      by: ['student_id'],
+      where: { student_id: { in: personIds }, present: true },
+      _count: { id: true },
+    });
+    const attendanceMap = new Map(attendanceRows.map((r) => [r.student_id, r._count.id]));
+
+    const allData = enrollments.map((e) => {
+      const presentCount = attendanceMap.get(e.person_id ?? 0) ?? 0;
+      const attendance = totalSessions > 0 ? this.round((presentCount / totalSessions) * 100, 0) : 0;
+      const progress = e.progress_percent ?? 0;
+      const grade = e.final_score != null ? Number(e.final_score) : null;
+      let status: 'ok' | 'risk' | 'inactive';
+      if (e.status === 'paused') status = 'inactive';
+      else if (attendance < 60 || progress < 50) status = 'risk';
+      else status = 'ok';
+      return { id: e.person_id, name: e.person?.name ?? null, avatarUrl: null as string | null, progress, attendance, grade, status };
+    }).filter((s) => !params.status || s.status === params.status);
+
+    return { total, page, pageSize, lastPage: Math.max(1, Math.ceil(total / pageSize)), data: allData };
+  }
+
+  async getClassGroupSessions(userId: number, classGroupId: number) {
+    await this.assertAdminHasAccessToClassGroup(userId, classGroupId);
+    const now = new Date();
+
+    const sessions = await this.prisma.course_class_session.findMany({
+      where: { course_class_group_id: classGroupId },
+      orderBy: { session_date: 'asc' },
+      select: {
+        id: true,
+        title: true,
+        session_date: true,
+        start_time: true,
+        end_time: true,
+        location: true,
+        meeting_url: true,
+        course_class_attendance: { where: { present: true }, select: { student_id: true } },
+      },
+    });
+
+    const totalStudents = await this.prisma.course_enrollment.count({
+      where: { course_class_group_id: classGroupId, status: { not: 'cancelled' } },
+    });
+
+    let hasFoundNext = false;
+    return sessions.map((s) => {
+      const isPast = s.session_date < now;
+      let status: 'completed' | 'next' | 'upcoming';
+      if (isPast) {
+        status = 'completed';
+      } else if (!hasFoundNext) {
+        status = 'next';
+        hasFoundNext = true;
+      } else {
+        status = 'upcoming';
+      }
+      return {
+        id: s.id,
+        title: s.title,
+        date: s.session_date,
+        time: s.start_time,
+        endTime: s.end_time ?? null,
+        location: s.location ?? null,
+        meetingUrl: s.meeting_url ?? null,
+        status,
+        attendanceCount: isPast ? s.course_class_attendance.length : null,
+        totalStudents,
+      };
+    });
+  }
+
+  async getClassGroupMaterials(userId: number, classGroupId: number) {
+    await this.assertAdminHasAccessToClassGroup(userId, classGroupId);
+
+    const materials = await this.prisma.course_class_group_material.findMany({
+      where: { course_class_group_id: classGroupId },
+      orderBy: [{ sort_order: 'asc' }, { created_at: 'asc' }],
+      select: {
+        id: true,
+        title: true,
+        description: true,
+        material_type: true,
+        url: true,
+        sort_order: true,
+        created_at: true,
+      },
+    });
+
+    return materials.map((m) => ({
+      id: m.id,
+      title: m.title,
+      description: m.description ?? null,
+      materialType: m.material_type,
+      url: m.url ?? null,
+    }));
+  }
+
+  // ── License management methods ────────────────────────────────────────────────
+
+  async listLicenses(
+    userId: number,
+    params: { page?: number; pageSize?: number; search?: string; status?: string; department?: string },
+  ) {
+    const enterpriseUser = await this.prisma.enterprise_user.findFirst({
+      where: { user_id: userId, status: 'active' },
+      select: { enterprise_id: true },
+    });
+    if (!enterpriseUser) throw new NotFoundException('No active enterprise found for this user');
+
+    const enterpriseId = enterpriseUser.enterprise_id;
+    const page = Math.max(Number(params.page) || 1, 1);
+    const pageSize = Math.max(Number(params.pageSize) || 10, 1);
+    const skip = (page - 1) * pageSize;
+
+    const where: any = { enterprise_id: enterpriseId };
+    if (params.search?.trim()) {
+      where.person = { name: { contains: params.search.trim(), mode: 'insensitive' } };
+    }
+    if (params.status && params.status !== 'all') {
+      where.status = params.status;
+    }
+
+    const [rows, total, enterprise] = await Promise.all([
+      this.prisma.enterprise_student.findMany({
+        where,
+        skip,
+        take: pageSize,
+        orderBy: { created_at: 'desc' },
+        include: {
+          person: {
+            select: {
+              id: true,
+              name: true,
+              contact: {
+                where: { is_primary: true, contact_type: { code: { in: ['email', 'EMAIL'] } } },
+                select: { value: true },
+                take: 1,
+              },
+            },
+          },
+        },
+      }),
+      this.prisma.enterprise_student.count({ where }),
+      this.prisma.enterprise.findUnique({
+        where: { id: enterpriseId },
+        select: { license_limit: true },
+      }),
+    ]);
+
+    return {
+      total,
+      page,
+      pageSize,
+      lastPage: Math.max(1, Math.ceil(total / pageSize)),
+      licenseLimit: (enterprise?.license_limit as number | null) ?? null,
+      data: rows.map((r) => ({
+        id: r.id,
+        personId: r.person_id,
+        name: r.person?.name ?? null,
+        email: r.person?.contact?.[0]?.value ?? null,
+        status: r.status,
+        createdAt: r.created_at,
+      })),
+    };
+  }
+
+  async assignLicense(
+    userId: number,
+    dto: { name: string; email?: string; department?: string },
+  ) {
+    const enterpriseUser = await this.prisma.enterprise_user.findFirst({
+      where: { user_id: userId, status: 'active' },
+      select: { enterprise_id: true },
+    });
+    if (!enterpriseUser) throw new NotFoundException('No active enterprise found for this user');
+
+    const enterpriseId = enterpriseUser.enterprise_id;
+
+    const licenseInfo = await this.getLicenseInfo(enterpriseId);
+    if (licenseInfo.limit !== null && licenseInfo.totalStudents >= licenseInfo.limit) {
+      throw new ConflictException('Enterprise license limit reached');
+    }
+
+    const name = dto.name.trim();
+    if (!name) throw new BadRequestException('Name is required');
+    const email = dto.email?.trim();
+
+    let personId: number | undefined;
+
+    if (email) {
+      const existing = await this.prisma.person.findFirst({
+        where: {
+          contact: {
+            some: {
+              value: { equals: email, mode: 'insensitive' },
+              contact_type: { code: { in: ['email', 'EMAIL'] } },
+            },
+          },
+        },
+        select: { id: true },
+      });
+      if (existing) personId = existing.id;
+    }
+
+    if (!personId) {
+      const emailType = email
+        ? await this.prisma.contact_type.findFirst({
+            where: { code: { in: ['email', 'EMAIL'] } },
+            select: { id: true },
+          })
+        : null;
+
+      const created = await this.prisma.person.create({
+        data: { name, type: 'individual', status: 'active' },
+        select: { id: true },
+      });
+      personId = created.id;
+
+      if (email && emailType) {
+        await this.prisma.contact.create({
+          data: {
+            person_id: personId,
+            contact_type_id: emailType.id,
+            value: email,
+            is_primary: true,
+          },
+        });
+      }
+    }
+
+    const existingStudent = await this.prisma.enterprise_student.findFirst({
+      where: { enterprise_id: enterpriseId, person_id: personId },
+      select: { id: true, status: true },
+    });
+
+    if (existingStudent) {
+      if (existingStudent.status !== 'inactive') {
+        throw new ConflictException('This person already has an active license');
+      }
+      return this.prisma.enterprise_student.update({
+        where: { id: existingStudent.id },
+        data: { status: 'active' },
+        select: { id: true, person_id: true, status: true, created_at: true },
+      });
+    }
+
+    return this.prisma.enterprise_student.create({
+      data: { enterprise_id: enterpriseId, person_id: personId, status: 'pending' },
+      select: { id: true, person_id: true, status: true, created_at: true },
+    });
+  }
+
+  async revokeLicense(userId: number, personId: number) {
+    const enterpriseUser = await this.prisma.enterprise_user.findFirst({
+      where: { user_id: userId, status: 'active' },
+      select: { enterprise_id: true },
+    });
+    if (!enterpriseUser) throw new NotFoundException('No active enterprise found for this user');
+
+    const existing = await this.prisma.enterprise_student.findFirst({
+      where: { enterprise_id: enterpriseUser.enterprise_id, person_id: personId },
+      select: { id: true },
+    });
+    if (!existing) throw new NotFoundException('Student not found in your enterprise');
+
+    return this.prisma.enterprise_student.update({
+      where: { id: existing.id },
+      data: { status: 'inactive' },
+      select: { id: true },
+    });
+  }
+
+  // ── Enrollment methods ────────────────────────────────────────────────────────
+
+  async getEnrollableStudents(
+    userId: number,
+    classGroupId: number,
+    search?: string,
+  ) {
+    const enterpriseId = await this.assertAdminHasAccessToClassGroup(userId, classGroupId);
+
+    const enrolled = await this.prisma.course_enrollment.findMany({
+      where: {
+        course_class_group_id: classGroupId,
+        status: { not: 'cancelled' },
+      },
+      select: { person_id: true },
+    });
+    const enrolledIds = enrolled.map((e) => e.person_id);
+
+    const where: Record<string, unknown> = { enterprise_id: enterpriseId };
+    if (enrolledIds.length > 0) {
+      where.person_id = { notIn: enrolledIds };
+    }
+    if (search?.trim()) {
+      where.person = { name: { contains: search.trim(), mode: 'insensitive' } };
+    }
+
+    const rows = await this.prisma.enterprise_student.findMany({
+      where: where as any,
+      take: 50,
+      orderBy: { person: { name: 'asc' } },
+      include: {
+        person: {
+          select: {
+            id: true,
+            name: true,
+            contact: {
+              where: { is_primary: true, contact_type: { code: { in: ['email', 'EMAIL'] } } },
+              select: { value: true },
+              take: 1,
+            },
+          },
+        },
+      },
+    });
+
+    return {
+      data: rows.map((r) => ({
+        id: r.id,
+        personId: r.person_id,
+        name: r.person?.name ?? null,
+        email: r.person?.contact?.[0]?.value ?? null,
+        status: r.status,
+      })),
+    };
+  }
+
+  async getLicenseAvailability(userId: number) {
+    const enterpriseUser = await this.prisma.enterprise_user.findFirst({
+      where: { user_id: userId, status: 'active' },
+      select: { enterprise_id: true },
+    });
+    if (!enterpriseUser) throw new NotFoundException('No active enterprise found for this user');
+
+    const info = await this.getLicenseInfo(enterpriseUser.enterprise_id);
+    return {
+      limit: info.limit,
+      totalStudents: info.totalStudents,
+      hasAvailableSlot: info.limit === null || info.totalStudents < info.limit,
+    };
+  }
+
+  async enrollExistingStudent(
+    userId: number,
+    classGroupId: number,
+    personId: number,
+  ) {
+    const enterpriseId = await this.assertAdminHasAccessToClassGroup(userId, classGroupId);
+
+    const esRecord = await this.prisma.enterprise_student.findFirst({
+      where: { enterprise_id: enterpriseId, person_id: personId },
+      select: { id: true },
+    });
+    if (!esRecord) throw new NotFoundException('Student not found in your enterprise');
+
+    const classGroup = await this.prisma.course_class_group.findUnique({
+      where: { id: classGroupId },
+      select: {
+        capacity: true,
+        course_id: true,
+        _count: { select: { course_enrollment: { where: { status: { not: 'cancelled' } } } } },
+      },
+    });
+    if (
+      classGroup?.capacity &&
+      classGroup._count.course_enrollment >= classGroup.capacity
+    ) {
+      throw new ConflictException('Class group is at full capacity');
+    }
+
+    const licenseInfo = await this.getLicenseInfo(enterpriseId);
+    if (licenseInfo.limit !== null && licenseInfo.totalStudents >= licenseInfo.limit) {
+      throw new ConflictException('Enterprise license limit reached');
+    }
+
+    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: classGroup!.course_id,
+        status: 'active',
+        enrolled_at: new Date(),
+      },
+    });
+  }
+
+  async createAndEnrollNewStudent(
+    userId: number,
+    classGroupId: number,
+    dto: { name: string; email?: string; department?: string },
+  ) {
+    const enterpriseId = await this.assertAdminHasAccessToClassGroup(userId, classGroupId);
+
+    const classGroup = await this.prisma.course_class_group.findUnique({
+      where: { id: classGroupId },
+      select: {
+        capacity: true,
+        course_id: true,
+        _count: { select: { course_enrollment: { where: { status: { not: 'cancelled' } } } } },
+      },
+    });
+    if (
+      classGroup?.capacity &&
+      classGroup._count.course_enrollment >= classGroup.capacity
+    ) {
+      throw new ConflictException('Class group is at full capacity');
+    }
+
+    const licenseInfo = await this.getLicenseInfo(enterpriseId);
+    if (licenseInfo.limit !== null && licenseInfo.totalStudents >= licenseInfo.limit) {
+      throw new ConflictException('Enterprise license limit reached');
+    }
+
+    const name = dto.name.trim();
+    if (!name) throw new BadRequestException('Name is required');
+    const email = dto.email?.trim();
+
+    let personId: number | undefined;
+
+    if (email) {
+      const existing = await this.prisma.person.findFirst({
+        where: {
+          contact: {
+            some: {
+              value: { equals: email, mode: 'insensitive' },
+              contact_type: { code: { in: ['email', 'EMAIL'] } },
+            },
+          },
+        },
+        select: { id: true },
+      });
+      if (existing) personId = existing.id;
+    }
+
+    if (!personId) {
+      const emailType = email
+        ? await this.prisma.contact_type.findFirst({
+            where: { code: { in: ['email', 'EMAIL'] } },
+            select: { id: true },
+          })
+        : null;
+
+      const created = await this.prisma.person.create({
+        data: { name, type: 'individual', status: 'active' },
+        select: { id: true },
+      });
+      personId = created.id;
+
+      if (email && emailType) {
+        await this.prisma.contact.create({
+          data: {
+            person_id: personId,
+            contact_type_id: emailType.id,
+            value: email,
+            is_primary: true,
+          },
+        });
+      }
+    }
+
+    let esRecord = await this.prisma.enterprise_student.findFirst({
+      where: { enterprise_id: enterpriseId, person_id: personId },
+      select: { id: true },
+    });
+    if (!esRecord) {
+      esRecord = await this.prisma.enterprise_student.create({
+        data: {
+          enterprise_id: enterpriseId,
+          person_id: personId,
+          status: 'active',
+        },
+        select: { id: true },
+      });
+    }
+
+    const existingEnrollment = await this.prisma.course_enrollment.findFirst({
+      where: { course_class_group_id: classGroupId, person_id: personId },
+    });
+    if (existingEnrollment) {
+      if (existingEnrollment.status === 'cancelled') {
+        return this.prisma.course_enrollment.update({
+          where: { id: existingEnrollment.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: classGroup!.course_id,
+        status: 'active',
+        enrolled_at: new Date(),
+      },
+    });
+  }
+
+  // ── Enterprise ID resolution ─────────────────────────────────────────────────
+
+  private async resolveEnterpriseId(userId: number, requestedEnterpriseId?: number): Promise<number> {
+    if (requestedEnterpriseId !== undefined) {
+      const allowed = await this.prisma.enterprise_user.findFirst({
+        where: { user_id: userId, enterprise_id: requestedEnterpriseId, status: 'active' },
+        select: { enterprise_id: true },
+      });
+      if (!allowed) throw new ForbiddenException('Access denied to the requested enterprise');
+      return requestedEnterpriseId;
+    }
+    const enterpriseUser = await this.prisma.enterprise_user.findFirst({
+      where: { user_id: userId, status: 'active' },
+      select: { enterprise_id: true },
+    });
+    if (!enterpriseUser) throw new NotFoundException('No active enterprise found for this user');
+    return enterpriseUser.enterprise_id;
+  }
+
+  // ── Course listing endpoints ──────────────────────────────────────────────────
+
+  async getCourses(
+    userId: number,
+    options: {
+      enterpriseId?: number;
+      page?: number;
+      pageSize?: number;
+      search?: string;
+      level?: string;
+      category?: string;
+    } = {},
+  ) {
+    const enterpriseId = await this.resolveEnterpriseId(userId, options.enterpriseId);
+
+    const page = Math.max(Number(options.page) || 1, 1);
+    const pageSize = Math.max(Number(options.pageSize) || 20, 1);
+    const skip = (page - 1) * pageSize;
+
+    const courseWhere: any = {};
+    if (options.search?.trim()) {
+      courseWhere.title = { contains: options.search.trim(), mode: 'insensitive' };
+    }
+    if (options.level) {
+      courseWhere.level = options.level;
+    }
+    if (options.category?.trim()) {
+      courseWhere.course_category = {
+        some: { category: { slug: { equals: options.category.trim(), mode: 'insensitive' } } },
+      };
+    }
+
+    const [courses, total] = await Promise.all([
+      this.prisma.course.findMany({
+        where: courseWhere,
+        skip,
+        take: pageSize,
+        orderBy: { title: 'asc' },
+        include: {
+          course_module: {
+            select: {
+              id: true,
+              _count: { select: { course_lesson: true } },
+            },
+          },
+          course_instructor: {
+            include: {
+              instructor: {
+                include: { person: { select: { id: true, name: true } } },
+              },
+            },
+          },
+          course_category: {
+            include: { category: { select: { slug: true } } },
+          },
+        },
+      }),
+      this.prisma.course.count({ where: courseWhere }),
+    ]);
+
+    if (courses.length === 0) {
+      return { total, page, pageSize, lastPage: Math.max(1, Math.ceil(total / pageSize)), data: [] };
+    }
+
+    const courseIds = courses.map((c) => c.id);
+
+    const enterpriseStudents = await this.prisma.enterprise_student.findMany({
+      where: { enterprise_id: enterpriseId },
+      select: { person_id: true },
+    });
+    const personIds = enterpriseStudents.map((s) => s.person_id);
+
+    const enrollmentRows =
+      personIds.length > 0
+        ? await this.prisma.course_enrollment.findMany({
+            where: { course_id: { in: courseIds }, person_id: { in: personIds } },
+            select: { course_id: true, status: true, progress_percent: true },
+          })
+        : [];
+
+    const statsMap = new Map<
+      number,
+      { enrolledCount: number; completedCount: number; inProgressCount: number; totalProgress: number }
+    >();
+    for (const row of enrollmentRows) {
+      if (!statsMap.has(row.course_id)) {
+        statsMap.set(row.course_id, {
+          enrolledCount: 0,
+          completedCount: 0,
+          inProgressCount: 0,
+          totalProgress: 0,
+        });
+      }
+      const s = statsMap.get(row.course_id)!;
+      s.enrolledCount++;
+      s.totalProgress += row.progress_percent ?? 0;
+      if (row.status === 'completed') s.completedCount++;
+      if (row.status === 'active') s.inProgressCount++;
+    }
+
+    const data = courses.map((c) => {
+      const stats = statsMap.get(c.id) ?? {
+        enrolledCount: 0,
+        completedCount: 0,
+        inProgressCount: 0,
+        totalProgress: 0,
+      };
+      const moduleCount = c.course_module.length;
+      const lessonCount = c.course_module.reduce((sum, m) => sum + m._count.course_lesson, 0);
+      return {
+        id: c.id,
+        title: c.title,
+        description: c.description ?? null,
+        level: c.level,
+        categories: c.course_category.map((cc) => cc.category?.slug ?? '').filter(Boolean),
+        durationHours: c.duration_hours,
+        moduleCount,
+        lessonCount,
+        instructors: c.course_instructor.map((ci) => ({
+          id: ci.instructor_id,
+          name: ci.instructor?.person?.name ?? '',
+          avatarId: null as number | null,
+        })),
+        createdAt: c.created_at,
+        enrolledCount: stats.enrolledCount,
+        completedCount: stats.completedCount,
+        inProgressCount: stats.inProgressCount,
+        avgProgress:
+          stats.enrolledCount > 0
+            ? this.round(stats.totalProgress / stats.enrolledCount, 1)
+            : 0,
+      };
+    });
+
+    return { total, page, pageSize, lastPage: Math.max(1, Math.ceil(total / pageSize)), data };
+  }
+
+  async getCourseStats(userId: number, enterpriseId?: number) {
+    const resolvedEnterpriseId = await this.resolveEnterpriseId(userId, enterpriseId);
+
+    const enterpriseStudents = await this.prisma.enterprise_student.findMany({
+      where: { enterprise_id: resolvedEnterpriseId },
+      select: { person_id: true },
+    });
+    const personIds = enterpriseStudents.map((s) => s.person_id);
+
+    if (personIds.length === 0) {
+      return { totalCourses: 0, totalEnrolled: 0, totalCompleted: 0, avgCompletion: 0 };
+    }
+
+    const enrollmentRows = await this.prisma.course_enrollment.findMany({
+      where: { person_id: { in: personIds } },
+      select: { course_id: true, status: true, progress_percent: true },
+    });
+
+    const courseSet = new Set(enrollmentRows.map((r) => r.course_id));
+    const totalEnrolled = enrollmentRows.length;
+    const totalCompleted = enrollmentRows.filter((r) => r.status === 'completed').length;
+    const totalProgress = enrollmentRows.reduce((sum, r) => sum + (r.progress_percent ?? 0), 0);
+
+    return {
+      totalCourses: courseSet.size,
+      totalEnrolled,
+      totalCompleted,
+      avgCompletion: totalEnrolled > 0 ? this.round(totalProgress / totalEnrolled, 1) : 0,
+    };
+  }
+
+  async getCourseDetail(userId: number, courseId: number, enterpriseId?: number) {
+    const resolvedEnterpriseId = await this.resolveEnterpriseId(userId, enterpriseId);
+
+    const course = await this.prisma.course.findUnique({
+      where: { id: courseId },
+      include: {
+        course_module: {
+          orderBy: { order: 'asc' },
+          include: {
+            course_lesson: {
+              orderBy: { order: 'asc' },
+              select: {
+                id: true,
+                order: true,
+                title: true,
+                type: true,
+                duration_seconds: true,
+              },
+            },
+          },
+        },
+        course_instructor: {
+          include: {
+            instructor: {
+              include: { person: { select: { id: true, name: true } } },
+            },
+          },
+        },
+        course_category: {
+          include: { category: { select: { slug: true } } },
+        },
+      },
+    });
+
+    if (!course) throw new NotFoundException(`Course #${courseId} not found`);
+
+    const enterpriseStudents = await this.prisma.enterprise_student.findMany({
+      where: { enterprise_id: resolvedEnterpriseId },
+      select: { person_id: true },
+    });
+    const personIds = enterpriseStudents.map((s) => s.person_id);
+
+    const enrollments =
+      personIds.length > 0
+        ? await this.prisma.course_enrollment.findMany({
+            where: { course_id: courseId, person_id: { in: personIds } },
+            include: {
+              person: {
+                select: {
+                  id: true,
+                  name: true,
+                  contact: {
+                    where: {
+                      is_primary: true,
+                      contact_type: { code: { in: ['email', 'EMAIL'] } },
+                    },
+                    select: { value: true },
+                    take: 1,
+                  },
+                },
+              },
+            },
+          })
+        : [];
+
+    const enrolledCount = enrollments.length;
+    const completedCount = enrollments.filter((e) => e.status === 'completed').length;
+    const inProgressCount = enrollments.filter((e) => e.status === 'active').length;
+    const totalProgress = enrollments.reduce((sum, e) => sum + (e.progress_percent ?? 0), 0);
+    const moduleCount = course.course_module.length;
+    const lessonCount = course.course_module.reduce((sum, m) => sum + m.course_lesson.length, 0);
+
+    return {
+      id: course.id,
+      title: course.title,
+      description: course.description ?? null,
+      level: course.level,
+      categories: course.course_category.map((cc) => cc.category?.slug ?? '').filter(Boolean),
+      durationHours: course.duration_hours,
+      moduleCount,
+      lessonCount,
+      instructors: course.course_instructor.map((ci) => ({
+        id: ci.instructor_id,
+        name: ci.instructor?.person?.name ?? '',
+        avatarId: null as number | null,
+      })),
+      createdAt: course.created_at,
+      objectives: course.objectives ?? null,
+      requirements: course.requirements ?? null,
+      enrolledCount,
+      completedCount,
+      inProgressCount,
+      avgProgress: enrolledCount > 0 ? this.round(totalProgress / enrolledCount, 1) : 0,
+      structure: course.course_module.map((m) => ({
+        id: m.id,
+        order: m.order,
+        title: m.title,
+        lessons: m.course_lesson.map((l) => ({
+          id: l.id,
+          order: l.order,
+          title: l.title,
+          type: l.type,
+          durationMinutes: Math.round((l.duration_seconds ?? 0) / 60),
+        })),
+      })),
+      students: enrollments.map((e) => ({
+        id: e.person?.id ?? e.person_id,
+        name: e.person?.name ?? null,
+        email: e.person?.contact?.[0]?.value ?? null,
+        department: null as string | null,
+        status: e.status,
+        progress: e.progress_percent ?? 0,
+        enrolledAt: e.enrolled_at,
+        completedAt: e.completed_at ?? null,
+        lastAccess: null as Date | null,
+      })),
+    };
+  }
+
+  // ── Student listing endpoints ─────────────────────────────────────────────────
+
+  async getStudents(
+    userId: number,
+    options: {
+      enterpriseId?: number;
+      page?: number;
+      pageSize?: number;
+      search?: string;
+      status?: string;
+    } = {},
+  ) {
+    const enterpriseId = await this.resolveEnterpriseId(userId, options.enterpriseId);
+
+    const page = Math.max(Number(options.page) || 1, 1);
+    const pageSize = Math.max(Number(options.pageSize) || 20, 1);
+    const skip = (page - 1) * pageSize;
+
+    const where: any = { enterprise_id: enterpriseId };
+    if (options.status && options.status !== 'all') {
+      where.status = options.status;
+    }
+    if (options.search?.trim()) {
+      where.OR = [
+        { person: { name: { contains: options.search.trim(), mode: 'insensitive' } } },
+        {
+          person: {
+            contact: {
+              some: { value: { contains: options.search.trim(), mode: 'insensitive' } },
+            },
+          },
+        },
+      ];
+    }
+
+    const [rows, total] = await Promise.all([
+      this.prisma.enterprise_student.findMany({
+        where,
+        skip,
+        take: pageSize,
+        orderBy: { person: { name: 'asc' } },
+        include: {
+          person: {
+            select: {
+              id: true,
+              name: true,
+              contact: {
+                where: { is_primary: true, contact_type: { code: { in: ['email', 'EMAIL'] } } },
+                select: { value: true },
+                take: 1,
+              },
+              person_metadata: {
+                where: { key: 'department' },
+                select: { value: true },
+                take: 1,
+              },
+            },
+          },
+        },
+      }),
+      this.prisma.enterprise_student.count({ where }),
+    ]);
+
+    if (rows.length === 0) {
+      return { total, page, pageSize, lastPage: Math.max(1, Math.ceil(total / pageSize)), data: [] };
+    }
+
+    const personIds = rows.map((r) => r.person_id);
+
+    const [enrollmentRows, certificateRows] = await Promise.all([
+      this.prisma.course_enrollment.findMany({
+        where: { person_id: { in: personIds } },
+        select: { person_id: true, course_class_group_id: true, status: true, progress_percent: true },
+      }),
+      this.prisma.certificate.findMany({
+        where: { student_id: { in: personIds } },
+        select: { student_id: true },
+      }),
+    ]);
+
+    const enrollMap = new Map<number, Array<{ course_class_group_id: number | null; status: string; progress_percent: number }>>();
+    for (const e of enrollmentRows) {
+      if (!enrollMap.has(e.person_id)) enrollMap.set(e.person_id, []);
+      enrollMap.get(e.person_id)!.push({
+        course_class_group_id: e.course_class_group_id,
+        status: e.status,
+        progress_percent: e.progress_percent ?? 0,
+      });
+    }
+
+    const certMap = new Map<number, number>();
+    for (const c of certificateRows) {
+      certMap.set(c.student_id, (certMap.get(c.student_id) ?? 0) + 1);
+    }
+
+    const data = rows.map((r) => {
+      const enrollments = enrollMap.get(r.person_id) ?? [];
+      const enrolledClasses = enrollments.filter(
+        (e) => e.course_class_group_id !== null && e.status === 'active',
+      ).length;
+      const completedCourses = enrollments.filter((e) => e.status === 'completed').length;
+      const certificates = certMap.get(r.person_id) ?? 0;
+      const avgProgress =
+        enrollments.length > 0
+          ? this.round(
+              enrollments.reduce((sum, e) => sum + e.progress_percent, 0) / enrollments.length,
+              1,
+            )
+          : 0;
+
+      const rawDept = r.person?.person_metadata?.[0]?.value;
+      const department = typeof rawDept === 'string' ? rawDept : (rawDept as any)?.toString?.() ?? '';
+
+      return {
+        id: r.person_id,
+        personId: r.person_id,
+        name: r.person?.name ?? null,
+        email: r.person?.contact?.[0]?.value ?? null,
+        department,
+        status: r.status,
+        enrolledClasses,
+        completedCourses,
+        certificates,
+        avgProgress,
+        joinedAt: r.created_at,
+      };
+    });
+
+    return { total, page, pageSize, lastPage: Math.max(1, Math.ceil(total / pageSize)), data };
+  }
+
+  async getStudentStats(userId: number, enterpriseId?: number) {
+    const resolvedEnterpriseId = await this.resolveEnterpriseId(userId, enterpriseId);
+
+    const [totalStudents, activeStudents, inactiveStudents, pendingStudents, personRows] =
+      await Promise.all([
+        this.prisma.enterprise_student.count({ where: { enterprise_id: resolvedEnterpriseId } }),
+        this.prisma.enterprise_student.count({ where: { enterprise_id: resolvedEnterpriseId, status: 'active' } }),
+        this.prisma.enterprise_student.count({ where: { enterprise_id: resolvedEnterpriseId, status: 'inactive' } }),
+        this.prisma.enterprise_student.count({ where: { enterprise_id: resolvedEnterpriseId, status: 'pending' } }),
+        this.prisma.enterprise_student.findMany({
+          where: { enterprise_id: resolvedEnterpriseId },
+          select: { person_id: true },
+        }),
+      ]);
+
+    const personIds = personRows.map((r) => r.person_id);
+    let avgProgress = 0;
+    if (personIds.length > 0) {
+      const agg = await this.prisma.course_enrollment.aggregate({
+        where: { person_id: { in: personIds } },
+        _avg: { progress_percent: true },
+      });
+      avgProgress = this.round(agg._avg.progress_percent ?? 0, 1);
+    }
+
+    return { totalStudents, activeStudents, inactiveStudents, pendingStudents, avgProgress };
+  }
+
+  async getStudentDetail(userId: number, personId: number, enterpriseId?: number) {
+    const resolvedEnterpriseId = await this.resolveEnterpriseId(userId, enterpriseId);
+
+    const esRecord = await this.prisma.enterprise_student.findFirst({
+      where: { enterprise_id: resolvedEnterpriseId, person_id: personId },
+      select: { id: true, status: true, created_at: true },
+    });
+    if (!esRecord) throw new NotFoundException('Student not found in your enterprise');
+
+    const [person, enrollments, certificates, examAttempts, personUsers] = await Promise.all([
+      this.prisma.person.findUnique({
+        where: { id: personId },
+        select: {
+          id: true,
+          name: true,
+          contact: {
+            where: { is_primary: true, contact_type: { code: { in: ['email', 'EMAIL'] } } },
+            select: { value: true },
+            take: 1,
+          },
+          person_metadata: {
+            where: { key: 'department' },
+            select: { value: true },
+            take: 1,
+          },
+        },
+      }),
+      this.prisma.course_enrollment.findMany({
+        where: { person_id: personId },
+        include: {
+          course: {
+            select: {
+              id: true,
+              title: true,
+              duration_hours: true,
+              course_category: {
+                include: { category: { select: { slug: true } } },
+              },
+            },
+          },
+          course_class_group: {
+            select: {
+              id: true,
+              title: true,
+              code: true,
+              status: true,
+              start_date: true,
+              end_date: true,
+              instructor: {
+                select: { person: { select: { name: true } } },
+              },
+            },
+          },
+        },
+        orderBy: { enrolled_at: 'desc' },
+      }),
+      this.prisma.certificate.findMany({
+        where: { student_id: personId },
+        select: {
+          id: true,
+          verification_code: true,
+          course_name: true,
+          issued_at: true,
+          certificate_type: true,
+        },
+        orderBy: { issued_at: 'desc' },
+      }),
+      this.prisma.exam_attempt.findMany({
+        where: { student_id: personId },
+        include: { exam: { select: { id: true, title: true } } },
+        orderBy: { started_at: 'desc' },
+      }),
+      this.prisma.person_user.findMany({
+        where: { person_id: personId },
+        select: { user_id: true },
+      }),
+    ]);
+
+    if (!person) throw new NotFoundException(`Person #${personId} not found`);
+
+    const rawDept = person.person_metadata?.[0]?.value;
+    const department = typeof rawDept === 'string' ? rawDept : (rawDept as any)?.toString?.() ?? '';
+
+    const userIds = personUsers.map((pu) => pu.user_id);
+    const acessos =
+      userIds.length > 0
+        ? await this.prisma.user_session.findMany({
+            where: { user_id: { in: userIds } },
+            select: { id: true, ip_address: true, user_agent: true, created_at: true },
+            orderBy: { created_at: 'desc' },
+            take: 20,
+          })
+        : [];
+
+    const turmas = enrollments
+      .filter((e) => e.course_class_group_id !== null)
+      .map((e) => {
+        const cg = e.course_class_group!;
+        return {
+          id: cg.id,
+          code: cg.code,
+          title: cg.title,
+          status: cg.status,
+          progress: e.progress_percent ?? 0,
+          instructorName: (cg as any).instructor?.person?.name ?? null,
+          startDate: cg.start_date,
+          endDate: cg.end_date ?? null,
+        };
+      });
+
+    const cursos = enrollments.map((e) => ({
+      id: e.course?.id ?? e.course_id,
+      title: e.course?.title ?? null,
+      categories:
+        e.course?.course_category?.map((cc) => cc.category?.slug ?? '').filter(Boolean) ?? [],
+      durationHours: e.course?.duration_hours ?? null,
+      status: e.status,
+      progress: e.progress_percent ?? 0,
+      enrolledAt: e.enrolled_at,
+      completedAt: e.completed_at ?? null,
+    }));
+
+    const certificadosList = certificates.map((c) => ({
+      id: c.id,
+      verificationCode: c.verification_code,
+      courseName: c.course_name,
+      issuedAt: c.issued_at,
+      type: c.certificate_type,
+    }));
+
+    const avaliacoes = examAttempts.map((a) => ({
+      id: a.id,
+      title: a.exam?.title ?? null,
+      score: a.score ?? null,
+      status: a.finished_at ? 'graded' : 'pending',
+      submittedAt: a.finished_at ?? a.started_at,
+    }));
+
+    const acessosList = acessos.map((s) => ({
+      id: s.id,
+      ipAddress: s.ip_address,
+      userAgent: s.user_agent,
+      createdAt: s.created_at,
+    }));
+
+    return {
+      id: person.id,
+      name: person.name,
+      email: person.contact?.[0]?.value ?? null,
+      department,
+      status: esRecord.status,
+      joinedAt: esRecord.created_at,
+      enrolledClasses: turmas.length,
+      completedCourses: cursos.filter((c) => c.status === 'completed').length,
+      certificates: certificadosList.length,
+      avgProgress:
+        cursos.length > 0
+          ? this.round(cursos.reduce((sum, c) => sum + c.progress, 0) / cursos.length, 1)
+          : 0,
+      turmas,
+      cursos,
+      certificados: certificadosList,
+      avaliacoes,
+      acessos: acessosList,
+    };
+  }
+
+  // ── Admin management ─────────────────────────────────────────────────────────
+
+  private async resolveEnterpriseIdAsAdmin(userId: number, requestedEnterpriseId?: number): Promise<number> {
+    if (requestedEnterpriseId !== undefined) {
+      const allowed = await this.prisma.enterprise_user.findFirst({
+        where: { user_id: userId, enterprise_id: requestedEnterpriseId, status: 'active', role: 'enterprise_admin' },
+        select: { enterprise_id: true },
+      });
+      if (!allowed) throw new ForbiddenException('Access denied: enterprise admin role required');
+      return requestedEnterpriseId;
+    }
+    const enterpriseUser = await this.prisma.enterprise_user.findFirst({
+      where: { user_id: userId, status: 'active', role: 'enterprise_admin' },
+      select: { enterprise_id: true },
+    });
+    if (!enterpriseUser) throw new ForbiddenException('Enterprise admin role required');
+    return enterpriseUser.enterprise_id;
+  }
+
+  private mapRoleToPermission(role: string): 'admin' | 'hr-manager' | 'viewer' {
+    if (role === 'enterprise_admin') return 'admin';
+    if (role === 'hr_manager') return 'hr-manager';
+    return 'viewer';
+  }
+
+  private mapPermissionToRole(permission: string): 'enterprise_admin' | 'hr_manager' | 'viewer' {
+    if (permission === 'admin') return 'enterprise_admin';
+    if (permission === 'hr-manager') return 'hr_manager';
+    return 'viewer';
+  }
+
+  async getAdminStats(userId: number, enterpriseId?: number) {
+    const resolvedId = await this.resolveEnterpriseIdAsAdmin(userId, enterpriseId);
+    const rows = await this.prisma.enterprise_user.groupBy({
+      by: ['role'],
+      where: { enterprise_id: resolvedId, role: { not: 'instructor' } },
+      _count: { id: true },
+    });
+
+    let adminCount = 0;
+    let hrManagerCount = 0;
+    let viewerCount = 0;
+    let total = 0;
+
+    for (const r of rows) {
+      const count = r._count.id;
+      total += count;
+      if (r.role === 'enterprise_admin') adminCount = count;
+      else if (r.role === 'hr_manager') hrManagerCount = count;
+      else if (r.role === 'viewer') viewerCount = count;
+    }
+
+    return { total, adminCount, hrManagerCount, viewerCount };
+  }
+
+  async getAdmins(
+    userId: number,
+    options: { enterpriseId?: number; page?: number; pageSize?: number; search?: string; role?: string } = {},
+  ) {
+    const resolvedId = await this.resolveEnterpriseIdAsAdmin(userId, options.enterpriseId);
+    const page = Math.max(Number(options.page) || 1, 1);
+    const pageSize = Math.max(Number(options.pageSize) || 20, 1);
+    const skip = (page - 1) * pageSize;
+
+    const where: any = {
+      enterprise_id: resolvedId,
+      role: options.role ? this.mapPermissionToRole(options.role) : { not: 'instructor' },
+    };
+
+    if (options.search?.trim()) {
+      where.OR = [
+        { user: { name: { contains: options.search.trim(), mode: 'insensitive' } } },
+        { person: { name: { contains: options.search.trim(), mode: 'insensitive' } } },
+      ];
+    }
+
+    const [rows, total] = await Promise.all([
+      this.prisma.enterprise_user.findMany({
+        where,
+        skip,
+        take: pageSize,
+        orderBy: { created_at: 'desc' },
+        include: {
+          user: { select: { id: true, name: true, last_login_at: true } },
+          person: {
+            select: {
+              id: true,
+              name: true,
+              person_metadata: { where: { key: 'department' }, select: { value: true }, take: 1 },
+              contact: {
+                where: { contact_type: { code: { in: ['email', 'EMAIL'] } } },
+                select: { value: true },
+                take: 1,
+              },
+            },
+          },
+        },
+      }),
+      this.prisma.enterprise_user.count({ where }),
+    ]);
+
+    const data = rows.map((eu) => {
+      const name = eu.person?.name ?? eu.user.name;
+      const email = eu.person?.contact?.[0]?.value ?? null;
+      const rawDept = eu.person?.person_metadata?.[0]?.value;
+      const department = typeof rawDept === 'string' ? rawDept : (rawDept as any)?.toString?.() ?? '';
+      return {
+        id: eu.id,
+        personId: eu.person_id,
+        name,
+        email,
+        department,
+        permission: this.mapRoleToPermission(eu.role),
+        status: eu.status,
+        addedAt: eu.created_at.toISOString(),
+        lastAccess: eu.user.last_login_at?.toISOString() ?? null,
+      };
+    });
+
+    return { total, page, pageSize, lastPage: Math.max(1, Math.ceil(total / pageSize)), data };
+  }
+
+  async addAdmin(
+    userId: number,
+    dto: { name: string; email?: string; department?: string; role?: string },
+  ) {
+    const enterpriseId = await this.resolveEnterpriseIdAsAdmin(userId);
+    const name = dto.name?.trim();
+    if (!name) throw new BadRequestException('Name is required');
+    const email = dto.email?.trim();
+    const dbRole = this.mapPermissionToRole(dto.role ?? 'viewer');
+
+    let personId: number | undefined;
+    let linkedUserId: number | undefined;
+
+    if (email) {
+      const existingPerson = await this.prisma.person.findFirst({
+        where: {
+          contact: {
+            some: {
+              value: { equals: email, mode: 'insensitive' },
+              contact_type: { code: { in: ['email', 'EMAIL'] } },
+            },
+          },
+        },
+        select: { id: true, person_user: { select: { user_id: true }, take: 1 } },
+      });
+      if (existingPerson) {
+        personId = existingPerson.id;
+        linkedUserId = existingPerson.person_user?.[0]?.user_id;
+      }
+    }
+
+    if (!personId) {
+      const emailType = email
+        ? await this.prisma.contact_type.findFirst({
+            where: { code: { in: ['email', 'EMAIL'] } },
+            select: { id: true },
+          })
+        : null;
+      const created = await this.prisma.person.create({
+        data: { name, type: 'individual', status: 'active' },
+        select: { id: true },
+      });
+      personId = created.id;
+      if (email && emailType) {
+        await this.prisma.contact.create({
+          data: { person_id: personId, contact_type_id: emailType.id, value: email, is_primary: true },
+        });
+      }
+    }
+
+    if (!linkedUserId) {
+      const newUser = await this.prisma.user.create({
+        data: { name },
+        select: { id: true },
+      });
+      linkedUserId = newUser.id;
+      await this.prisma.person_user.create({
+        data: { person_id: personId, user_id: linkedUserId },
+      });
+    }
+
+    const existing = await this.prisma.enterprise_user.findFirst({
+      where: { enterprise_id: enterpriseId, user_id: linkedUserId },
+      select: { id: true },
+    });
+    if (existing) throw new ConflictException('This user already has access to this enterprise');
+
+    return this.prisma.enterprise_user.create({
+      data: {
+        enterprise_id: enterpriseId,
+        user_id: linkedUserId,
+        person_id: personId,
+        role: dbRole,
+        status: 'active',
+      },
+      select: { id: true, role: true, status: true, created_at: true },
+    });
+  }
+
+  async updateAdminRole(userId: number, enterpriseUserId: number, permission: string) {
+    const enterpriseId = await this.resolveEnterpriseIdAsAdmin(userId);
+    const target = await this.prisma.enterprise_user.findFirst({
+      where: { id: enterpriseUserId, enterprise_id: enterpriseId },
+      select: { id: true, user_id: true },
+    });
+    if (!target) throw new NotFoundException('Admin not found in your enterprise');
+    if (target.user_id === userId) throw new ForbiddenException('Cannot change your own role');
+    const dbRole = this.mapPermissionToRole(permission);
+    return this.prisma.enterprise_user.update({
+      where: { id: enterpriseUserId },
+      data: { role: dbRole },
+      select: { id: true, role: true },
+    });
+  }
+
+  async removeAdmin(userId: number, enterpriseUserId: number) {
+    const enterpriseId = await this.resolveEnterpriseIdAsAdmin(userId);
+    const target = await this.prisma.enterprise_user.findFirst({
+      where: { id: enterpriseUserId, enterprise_id: enterpriseId },
+      select: { id: true, user_id: true },
+    });
+    if (!target) throw new NotFoundException('Admin not found in your enterprise');
+    if (target.user_id === userId) throw new ForbiddenException('Cannot remove yourself');
+    await this.prisma.enterprise_user.delete({ where: { id: enterpriseUserId } });
+    return { success: true };
+  }
+
+  // ── Evaluation endpoints ───────────────────────────────────────────────────────
+
+  async getEvaluationStats(userId: number, enterpriseId?: number) {
+    const entId = await this.resolveEnterpriseId(userId, enterpriseId);
+
+    const cgRows = await this.prisma.enterprise_class_group.findMany({
+      where: { enterprise_id: entId },
+      select: { course_class_group_id: true },
+    });
+    const cgIds = cgRows.map((r) => r.course_class_group_id);
+
+    if (cgIds.length === 0) {
+      return { activeClassGroups: 0, totalEvaluations: 0, avgScore: 0, evaluatedStudentCount: 0 };
+    }
+
+    const ratings = await this.prisma.evaluation_rating.findMany({
+      where: {
+        evaluation_topic: {
+          target_type: 'course_class_session',
+          course_class_session: { course_class_group_id: { in: cgIds } },
+        },
+      },
+      select: {
+        score: true,
+        evaluator_id: true,
+        evaluation_topic: {
+          select: {
+            course_class_session_id: true,
+            course_class_session: { select: { course_class_group_id: true } },
+          },
+        },
+      },
+    });
+
+    const evaluatorSet = new Set(ratings.map((r) => r.evaluator_id).filter(Boolean));
+    const ratedCgIds = new Set(
+      ratings
+        .map((r) => r.evaluation_topic.course_class_session?.course_class_group_id)
+        .filter(Boolean),
+    );
+    const evalPairs = new Set(
+      ratings.map((r) => `${r.evaluator_id}-${r.evaluation_topic.course_class_session_id}`),
+    );
+    const totalScore = ratings.reduce((s, r) => s + Number(r.score), 0);
+    const avgScore = ratings.length > 0 ? this.round(totalScore / ratings.length, 2) : 0;
+
+    return {
+      activeClassGroups: ratedCgIds.size,
+      totalEvaluations: evalPairs.size,
+      avgScore,
+      evaluatedStudentCount: evaluatorSet.size,
+    };
+  }
+
+  async getEvaluationClassGroups(
+    userId: number,
+    options: { enterpriseId?: number; page?: number; pageSize?: number; search?: string } = {},
+  ) {
+    const entId = await this.resolveEnterpriseId(userId, options.enterpriseId);
+    const page = Math.max(Number(options.page) || 1, 1);
+    const pageSize = Math.max(Number(options.pageSize) || 20, 1);
+    const skip = (page - 1) * pageSize;
+
+    const where: any = { enterprise_class_group: { some: { enterprise_id: entId } } };
+    if (options.search?.trim()) {
+      where.OR = [
+        { title: { contains: options.search.trim(), mode: 'insensitive' } },
+        { course: { title: { contains: options.search.trim(), mode: 'insensitive' } } },
+      ];
+    }
+
+    const [total, classGroups] = await Promise.all([
+      this.prisma.course_class_group.count({ where }),
+      this.prisma.course_class_group.findMany({
+        where,
+        skip,
+        take: pageSize,
+        orderBy: { start_date: 'desc' },
+        include: {
+          course: { select: { id: true, title: true } },
+          _count: {
+            select: { course_enrollment: { where: { status: { not: 'cancelled' } } } },
+          },
+          course_class_session: {
+            select: {
+              id: true,
+              evaluation_topic: {
+                where: { target_type: 'course_class_session' },
+                select: {
+                  id: true,
+                  evaluation_rating: { select: { evaluator_id: true, score: true } },
+                },
+              },
+            },
+          },
+        },
+      }),
+    ]);
+
+    const data = classGroups.map((cg) => {
+      const allRatings = cg.course_class_session.flatMap((s) =>
+        s.evaluation_topic.flatMap((t) => t.evaluation_rating),
+      );
+      const evaluatorSet = new Set(allRatings.map((r) => r.evaluator_id).filter(Boolean));
+      const evaluatedSessionCount = cg.course_class_session.filter((s) =>
+        s.evaluation_topic.some((t) => t.evaluation_rating.length > 0),
+      ).length;
+      const totalScore = allRatings.reduce((sum, r) => sum + Number(r.score), 0);
+      const avgScore = allRatings.length > 0 ? this.round(totalScore / allRatings.length, 2) : 0;
+
+      return {
+        id: cg.id,
+        title: cg.title,
+        courseId: cg.course?.id ?? null,
+        courseTitle: cg.course?.title ?? null,
+        startDate: cg.start_date,
+        endDate: cg.end_date ?? null,
+        totalStudentCount: cg._count.course_enrollment,
+        sessionCount: cg.course_class_session.length,
+        evaluatedSessionCount,
+        avgScore,
+        evaluatedStudentCount: evaluatorSet.size,
+      };
+    });
+
+    return { total, page, pageSize, lastPage: Math.max(Math.ceil(total / pageSize), 1), data };
+  }
+
+  async getEvaluationClassGroupDetail(
+    userId: number,
+    classGroupId: number,
+    enterpriseId?: number,
+  ) {
+    const entId = await this.resolveEnterpriseId(userId, enterpriseId);
+
+    const cgCheck = await this.prisma.enterprise_class_group.findFirst({
+      where: { enterprise_id: entId, course_class_group_id: classGroupId },
+    });
+    if (!cgCheck) throw new NotFoundException('Class group not found in your enterprise');
+
+    const classGroup = await this.prisma.course_class_group.findUnique({
+      where: { id: classGroupId },
+      include: {
+        course: { select: { id: true, title: true } },
+        course_class_session: {
+          orderBy: { session_date: 'asc' },
+          include: {
+            evaluation_topic: {
+              where: { target_type: 'course_class_session' },
+              orderBy: { order: 'asc' },
+              include: {
+                evaluation_rating: {
+                  include: { person: { select: { id: true, name: true } } },
+                },
+              },
+            },
+          },
+        },
+      },
+    });
+    if (!classGroup) throw new NotFoundException('Class group not found');
+
+    // Course-level topics + rater IDs for evaluatedCourse flag
+    let courseTopics: { id: number; name: string }[] = [];
+    const courseRaterIds = new Set<number>();
+    if (classGroup.course_id) {
+      const cTopics = await this.prisma.evaluation_topic.findMany({
+        where: { course_id: classGroup.course_id, target_type: 'course' },
+        orderBy: { order: 'asc' },
+        include: { evaluation_rating: { select: { evaluator_id: true } } },
+      });
+      courseTopics = cTopics.map((t) => ({ id: t.id, name: t.name }));
+      cTopics.forEach((t) =>
+        t.evaluation_rating.forEach((r) => {
+          if (r.evaluator_id) courseRaterIds.add(r.evaluator_id);
+        }),
+      );
+    }
+
+    // Deduplicate topics across all sessions
+    const topicMap = new Map<number, string>();
+    classGroup.course_class_session.forEach((s) =>
+      s.evaluation_topic.forEach((t) => topicMap.set(t.id, t.name)),
+    );
+
+    const sessions = classGroup.course_class_session.map((session) => {
+      const raterMap = new Map<
+        number,
+        { name: string; topicScores: Record<number, number>; comment: string | null }
+      >();
+      session.evaluation_topic.forEach((topic) => {
+        topic.evaluation_rating.forEach((rating) => {
+          if (!rating.evaluator_id || !rating.person) return;
+          if (!raterMap.has(rating.evaluator_id)) {
+            raterMap.set(rating.evaluator_id, {
+              name: rating.person.name,
+              topicScores: {},
+              comment: null,
+            });
+          }
+          const entry = raterMap.get(rating.evaluator_id)!;
+          entry.topicScores[topic.id] = Number(rating.score);
+          if (rating.comment && !entry.comment) entry.comment = rating.comment;
+        });
+      });
+
+      const allRatings = session.evaluation_topic.flatMap((t) => t.evaluation_rating);
+      const totalScore = allRatings.reduce((s, r) => s + Number(r.score), 0);
+      const avg = allRatings.length > 0 ? this.round(totalScore / allRatings.length, 2) : 0;
+
+      return {
+        id: session.id,
+        title: session.title,
+        date: session.session_date,
+        avg,
+        ratings: Array.from(raterMap.entries()).map(([personId, d]) => ({
+          personId,
+          name: d.name,
+          topicScores: d.topicScores,
+          comment: d.comment,
+          evaluatedCourse: courseRaterIds.has(personId),
+        })),
+      };
+    });
+
+    return {
+      classGroup: {
+        id: classGroup.id,
+        title: classGroup.title,
+        courseId: classGroup.course?.id ?? null,
+        courseTitle: classGroup.course?.title ?? null,
+        startDate: classGroup.start_date,
+        endDate: classGroup.end_date ?? null,
+      },
+      topics: Array.from(topicMap.entries()).map(([id, name]) => ({ id, name })),
+      sessions,
+      courseTopics,
+    };
+  }
+
+  // ── Admin reports endpoint ─────────────────────────────────────────────────────
+
+  async getAdminReports(
+    userId: number,
+    options: { enterpriseId?: number; dateFrom?: string; dateTo?: string } = {},
+  ) {
+    const entId = await this.resolveEnterpriseId(userId, options.enterpriseId);
+
+    const now = new Date();
+    const dateFrom = options.dateFrom
+      ? new Date(`${options.dateFrom}T00:00:00.000Z`)
+      : new Date(Date.UTC(now.getFullYear(), 0, 1));
+    const dateTo = options.dateTo
+      ? new Date(`${options.dateTo}T23:59:59.999Z`)
+      : new Date(Date.UTC(now.getFullYear(), 11, 31, 23, 59, 59));
+
+    const [esRows, ecgRows] = await Promise.all([
+      this.prisma.enterprise_student.findMany({
+        where: { enterprise_id: entId },
+        select: { person_id: true, status: true },
+      }),
+      this.prisma.enterprise_class_group.findMany({
+        where: { enterprise_id: entId },
+        select: { course_class_group_id: true },
+      }),
+    ]);
+
+    const personIds = esRows.map((r) => r.person_id);
+    const cgIds = ecgRows.map((r) => r.course_class_group_id);
+
+    if (personIds.length === 0) {
+      return {
+        kpis: { totalStudents: 0, enrollmentsInPeriod: 0, completedInPeriod: 0, activeClassGroups: 0, avgSatisfaction: 0, certificatesIssued: 0, atRiskStudentsCount: 0, activeCoursesCount: 0 },
+        enrollmentEvents: [] as { enrolledDate: string | null; completedDate: string | null }[],
+        sessionAttendance: [] as { date: string; title: string; totalStudents: number; presentCount: number; pct: number }[],
+        courseStats: [] as { courseId: number; title: string; enrolledCount: number; completedCount: number; completionPct: number; avgSatisfaction: number }[],
+        studentStatusCounts: { active: 0, atRisk: 0, inactive: 0 },
+        evalSessions: [] as { date: string; sessionTitle: string; scores: { topicName: string; avg: number }[]; overallAvg: number }[],
+        evalTopicAverages: [] as { topicName: string; avgScore: number }[],
+        atRiskStudents: [] as { personId: number; name: string; attendancePct: number; lastPresentDate: string | null; classGroupTitle: string | null }[],
+      };
+    }
+
+    const [
+      enrollmentsInPeriodCount,
+      completedInPeriodCount,
+      activeClassGroupsCount,
+      certificatesIssuedCount,
+      allEnrollments,
+      sessionAttendanceRaw,
+      evalRatings,
+      attendanceForRisk,
+    ] = await Promise.all([
+      this.prisma.course_enrollment.count({
+        where: { person_id: { in: personIds }, enrolled_at: { gte: dateFrom, lte: dateTo } },
+      }),
+      this.prisma.course_enrollment.count({
+        where: { person_id: { in: personIds }, completed_at: { gte: dateFrom, lte: dateTo } },
+      }),
+      this.prisma.course_class_group.count({
+        where: { enterprise_class_group: { some: { enterprise_id: entId } }, status: 'ongoing' },
+      }),
+      this.prisma.certificate.count({
+        where: { student_id: { in: personIds }, issued_at: { gte: dateFrom, lte: dateTo } },
+      }),
+      this.prisma.course_enrollment.findMany({
+        where: { person_id: { in: personIds } },
+        select: {
+          course_id: true,
+          status: true,
+          enrolled_at: true,
+          completed_at: true,
+          course: { select: { id: true, title: true } },
+        },
+      }),
+      cgIds.length > 0
+        ? this.prisma.course_class_attendance.findMany({
+            where: {
+              course_class_session: {
+                course_class_group_id: { in: cgIds },
+                session_date: { gte: dateFrom, lte: dateTo },
+              },
+              student_id: { in: personIds },
+            },
+            select: {
+              student_id: true,
+              present: true,
+              course_class_session: { select: { id: true, session_date: true, title: true } },
+            },
+          })
+        : Promise.resolve([] as { student_id: number; present: boolean; course_class_session: { id: number; session_date: Date; title: string } | null }[]),
+      cgIds.length > 0
+        ? this.prisma.evaluation_rating.findMany({
+            where: {
+              evaluation_topic: {
+                course_class_session: {
+                  course_class_group_id: { in: cgIds },
+                  session_date: { gte: dateFrom, lte: dateTo },
+                },
+              },
+            },
+            select: {
+              score: true,
+              evaluation_topic: {
+                select: {
+                  name: true,
+                  course_class_session: {
+                    select: {
+                      session_date: true,
+                      title: true,
+                      course_class_group: { select: { course_id: true } },
+                    },
+                  },
+                },
+              },
+            },
+          })
+        : Promise.resolve([] as { score: any; evaluation_topic: { name: string; course_class_session: { session_date: Date; title: string; course_class_group: { course_id: number } | null } | null } }[]),
+      cgIds.length > 0
+        ? this.prisma.course_class_attendance.findMany({
+            where: {
+              course_class_session: { course_class_group_id: { in: cgIds } },
+              student_id: { in: personIds },
+            },
+            select: {
+              student_id: true,
+              present: true,
+              course_class_session: { select: { session_date: true, course_class_group_id: true } },
+            },
+          })
+        : Promise.resolve([] as { student_id: number; present: boolean; course_class_session: { session_date: Date; course_class_group_id: number } | null }[]),
+    ]);
+
+    // ── Course stats ─────────────────────────────────────────────────────────────
+    const courseMap = new Map<number, { title: string; enrolledCount: number; completedCount: number }>();
+    for (const e of allEnrollments) {
+      if (!courseMap.has(e.course_id)) {
+        courseMap.set(e.course_id, { title: e.course?.title ?? `Curso #${e.course_id}`, enrolledCount: 0, completedCount: 0 });
+      }
+      const cs = courseMap.get(e.course_id)!;
+      cs.enrolledCount++;
+      if (e.status === 'completed') cs.completedCount++;
+    }
+
+    const courseSatisfactionMap = new Map<number, { total: number; count: number }>();
+    for (const r of evalRatings) {
+      const courseId = r.evaluation_topic?.course_class_session?.course_class_group?.course_id;
+      if (!courseId) continue;
+      if (!courseSatisfactionMap.has(courseId)) courseSatisfactionMap.set(courseId, { total: 0, count: 0 });
+      const cs = courseSatisfactionMap.get(courseId)!;
+      cs.total += Number(r.score);
+      cs.count++;
+    }
+
+    const courseStats = Array.from(courseMap.entries())
+      .sort(([, a], [, b]) => b.enrolledCount - a.enrolledCount)
+      .slice(0, 10)
+      .map(([courseId, cs]) => {
+        const sat = courseSatisfactionMap.get(courseId);
+        return {
+          courseId,
+          title: cs.title,
+          enrolledCount: cs.enrolledCount,
+          completedCount: cs.completedCount,
+          completionPct: cs.enrolledCount > 0 ? this.round((cs.completedCount / cs.enrolledCount) * 100, 0) : 0,
+          avgSatisfaction: sat ? this.round(sat.total / sat.count, 2) : 0,
+        };
+      });
+
+    const totalEvalScore = evalRatings.reduce((s, r) => s + Number(r.score), 0);
+    const avgSatisfaction = evalRatings.length > 0 ? this.round(totalEvalScore / evalRatings.length, 2) : 0;
+
+    // ── Enrollment events for time-series chart ───────────────────────────────────
+    const enrollmentEvents = allEnrollments
+      .filter((e) => {
+        const inPeriodEnrolled = e.enrolled_at >= dateFrom && e.enrolled_at <= dateTo;
+        const inPeriodCompleted = e.completed_at != null && e.completed_at >= dateFrom && e.completed_at <= dateTo;
+        return inPeriodEnrolled || inPeriodCompleted;
+      })
+      .map((e) => ({
+        enrolledDate: e.enrolled_at >= dateFrom && e.enrolled_at <= dateTo ? e.enrolled_at.toISOString().slice(0, 10) : null,
+        completedDate: e.completed_at != null && e.completed_at >= dateFrom && e.completed_at <= dateTo ? e.completed_at.toISOString().slice(0, 10) : null,
+      }));
+
+    // ── Session attendance for frequency chart ────────────────────────────────────
+    const sessionAttMap = new Map<number, { title: string; date: Date; total: number; present: number }>();
+    for (const att of sessionAttendanceRaw) {
+      const session = att.course_class_session;
+      if (!session) continue;
+      if (!sessionAttMap.has(session.id)) sessionAttMap.set(session.id, { title: session.title ?? '', date: session.session_date, total: 0, present: 0 });
+      const sm = sessionAttMap.get(session.id)!;
+      sm.total++;
+      if (att.present) sm.present++;
+    }
+    const sessionAttendance = Array.from(sessionAttMap.values())
+      .map((sm) => ({ date: sm.date.toISOString().slice(0, 10), title: sm.title, totalStudents: sm.total, presentCount: sm.present, pct: sm.total > 0 ? this.round((sm.present / sm.total) * 100, 0) : 0 }))
+      .sort((a, b) => a.date.localeCompare(b.date));
+
+    // ── Eval sessions for trend chart ─────────────────────────────────────────────
+    const evalSessionMap = new Map<string, { title: string; topicScores: Map<string, number[]>; allScores: number[] }>();
+    for (const r of evalRatings) {
+      const session = r.evaluation_topic?.course_class_session;
+      if (!session) continue;
+      const key = `${session.session_date.toISOString().slice(0, 10)}|${session.title ?? ''}`;
+      if (!evalSessionMap.has(key)) evalSessionMap.set(key, { title: session.title ?? '', topicScores: new Map(), allScores: [] });
+      const esm = evalSessionMap.get(key)!;
+      if (!esm.topicScores.has(r.evaluation_topic.name)) esm.topicScores.set(r.evaluation_topic.name, []);
+      esm.topicScores.get(r.evaluation_topic.name)!.push(Number(r.score));
+      esm.allScores.push(Number(r.score));
+    }
+    const evalSessions = Array.from(evalSessionMap.entries())
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(([key, esm]) => ({
+        date: key.split('|')[0],
+        sessionTitle: esm.title,
+        scores: Array.from(esm.topicScores.entries()).map(([topicName, scores]) => ({ topicName, avg: this.round(scores.reduce((s, v) => s + v, 0) / scores.length, 2) })),
+        overallAvg: esm.allScores.length > 0 ? this.round(esm.allScores.reduce((s, v) => s + v, 0) / esm.allScores.length, 2) : 0,
+      }));
+
+    // ── Eval topic radar ──────────────────────────────────────────────────────────
+    const topicTotalMap = new Map<string, { total: number; count: number }>();
+    for (const r of evalRatings) {
+      if (!topicTotalMap.has(r.evaluation_topic.name)) topicTotalMap.set(r.evaluation_topic.name, { total: 0, count: 0 });
+      const tt = topicTotalMap.get(r.evaluation_topic.name)!;
+      tt.total += Number(r.score);
+      tt.count++;
+    }
+    const evalTopicAverages = Array.from(topicTotalMap.entries()).map(([topicName, tt]) => ({ topicName, avgScore: this.round(tt.total / tt.count, 2) }));
+
+    // ── At-risk students ──────────────────────────────────────────────────────────
+    const studentRiskMap = new Map<number, { total: number; present: number; lastPresentDate: string | null; cgId: number | null }>();
+    for (const att of attendanceForRisk) {
+      if (!studentRiskMap.has(att.student_id)) studentRiskMap.set(att.student_id, { total: 0, present: 0, lastPresentDate: null, cgId: null });
+      const sa = studentRiskMap.get(att.student_id)!;
+      sa.total++;
+      if (att.present) {
+        sa.present++;
+        const ds = att.course_class_session?.session_date?.toISOString()?.slice(0, 10) ?? null;
+        if (ds && (!sa.lastPresentDate || ds > sa.lastPresentDate)) sa.lastPresentDate = ds;
+      }
+      if (!sa.cgId && att.course_class_session?.course_class_group_id) sa.cgId = att.course_class_session.course_class_group_id;
+    }
+    const atRiskPersonIds: number[] = [];
+    const atRiskAttMap = new Map<number, { pct: number; lastPresentDate: string | null; cgId: number | null }>();
+    for (const [personId, sa] of studentRiskMap.entries()) {
+      if (sa.total === 0) continue;
+      const pct = this.round((sa.present / sa.total) * 100, 0);
+      if (pct < 75) {
+        atRiskPersonIds.push(personId);
+        atRiskAttMap.set(personId, { pct, lastPresentDate: sa.lastPresentDate, cgId: sa.cgId });
+      }
+    }
+
+    let atRiskStudents: { personId: number; name: string; attendancePct: number; lastPresentDate: string | null; classGroupTitle: string | null }[] = [];
+    if (atRiskPersonIds.length > 0) {
+      const cgIdsForRisk = [...new Set(Array.from(atRiskAttMap.values()).map((v) => v.cgId).filter((id): id is number => id !== null))];
+      const [atRiskPersons, cgListForRisk] = await Promise.all([
+        this.prisma.person.findMany({ where: { id: { in: atRiskPersonIds } }, select: { id: true, name: true } }),
+        cgIdsForRisk.length > 0
+          ? this.prisma.course_class_group.findMany({ where: { id: { in: cgIdsForRisk } }, select: { id: true, title: true } })
+          : Promise.resolve([] as { id: number; title: string }[]),
+      ]);
+      const personNameMap = new Map(atRiskPersons.map((p) => [p.id, p.name]));
+      const cgTitleMap = new Map(cgListForRisk.map((c) => [c.id, c.title]));
+      atRiskStudents = atRiskPersonIds
+        .map((pid) => {
+          const att = atRiskAttMap.get(pid)!;
+          return { personId: pid, name: personNameMap.get(pid) ?? `Pessoa #${pid}`, attendancePct: att.pct, lastPresentDate: att.lastPresentDate, classGroupTitle: att.cgId ? (cgTitleMap.get(att.cgId) ?? null) : null };
+        })
+        .sort((a, b) => a.attendancePct - b.attendancePct)
+        .slice(0, 10);
+    }
+
+    const atRiskSet = new Set(atRiskPersonIds);
+    const activeStudents = esRows.filter((r) => r.status === 'active' && !atRiskSet.has(r.person_id)).length;
+    const inactiveStudents = esRows.filter((r) => r.status !== 'active').length;
+    const activeCoursesCount = new Set(allEnrollments.filter((e) => e.status !== 'cancelled').map((e) => e.course_id)).size;
+
+    return {
+      kpis: { totalStudents: esRows.length, enrollmentsInPeriod: enrollmentsInPeriodCount, completedInPeriod: completedInPeriodCount, activeClassGroups: activeClassGroupsCount, avgSatisfaction, certificatesIssued: certificatesIssuedCount, atRiskStudentsCount: atRiskPersonIds.length, activeCoursesCount },
+      enrollmentEvents,
+      sessionAttendance,
+      courseStats,
+      studentStatusCounts: { active: activeStudents, atRisk: atRiskPersonIds.length, inactive: inactiveStudents },
+      evalSessions,
+      evalTopicAverages,
+      atRiskStudents,
+    };
+  }
+
+  // ── Date helpers ──────────────────────────────────────────────────────────────
+
+  private percentChange(current: number, previous: number) {
+    if (previous <= 0) return current > 0 ? 100 : 0;
+    return this.round(((current - previous) / previous) * 100, 1);
+  }
+
+  private round(value: number, digits = 0) {
+    const factor = 10 ** digits;
+    return Math.round(value * factor) / factor;
+  }
+
+  private addMonths(date: Date, months: number) {
+    const result = new Date(date);
+    result.setMonth(result.getMonth() + months);
+    return result;
+  }
+
+  private startOfMonth(date: Date) {
+    return new Date(date.getFullYear(), date.getMonth(), 1, 0, 0, 0, 0);
+  }
+
+  private endOfMonth(date: Date) {
+    return new Date(date.getFullYear(), date.getMonth() + 1, 0, 23, 59, 59, 999);
+  }
+}