@hed-hog/lms 0.0.364 → 0.0.366

package/src/platforma/handlers/lesson-heartbeat.handler.ts

@@ -0,0 +1,343 @@
+import { PrismaService } from '@hed-hog/api-prisma';
+import { IJobHandler, QueueHandlerRegistry, QueueJobService } from '@hed-hog/queue';
+import { Inject, Injectable, Logger, OnModuleInit, forwardRef } from '@nestjs/common';
+import { LmsRealtimeService } from '../../realtime/lms-realtime.service';
+
+export const LESSON_HEARTBEAT_JOB = 'lms.lesson_heartbeat';
+
+@Injectable()
+export class LessonHeartbeatHandler implements OnModuleInit, IJobHandler {
+  private readonly logger = new Logger(LessonHeartbeatHandler.name);
+
+  constructor(
+    @Inject(forwardRef(() => PrismaService))
+    private readonly prisma: PrismaService,
+    @Inject(forwardRef(() => QueueHandlerRegistry))
+    private readonly registry: QueueHandlerRegistry,
+    @Inject(forwardRef(() => QueueJobService))
+    private readonly queueJob: QueueJobService,
+    @Inject(forwardRef(() => LmsRealtimeService))
+    private readonly realtime: LmsRealtimeService,
+  ) {}
+
+  onModuleInit() {
+    this.registry.register(LESSON_HEARTBEAT_JOB, this);
+    this.logger.log(`Registered handler for "${LESSON_HEARTBEAT_JOB}"`);
+  }
+
+  async handle(job: { payload: Record<string, any> }) {
+    const {
+      userId,
+      ip,
+      userAgent,
+      lessonId,
+      positionSeconds,
+      sessionId,
+      screenWidth,
+      screenHeight,
+      isTouch,
+    } = job.payload;
+
+    const { browser, os, deviceType } = this.parseUA(String(userAgent ?? ''));
+    const geo = await this.resolveGeo(ip);
+
+    const lesson = await (this.prisma as any).course_lesson.findUnique({
+      where: { id: lessonId },
+      select: {
+        id: true,
+        duration_seconds: true,
+        published: true,
+        course_module: { select: { course_id: true } },
+      },
+    });
+
+    if (!lesson?.published) {
+      return { skipped: true, reason: 'lesson not published' };
+    }
+
+    const courseId: number = lesson.course_module?.course_id;
+
+    let enrollmentId: number | null = null;
+    let personId: number | null = null;
+
+    if (userId && courseId) {
+      const personUser = await this.prisma.person_user.findFirst({
+        where: { user_id: userId },
+        select: { person_id: true },
+      });
+
+      if (personUser) {
+        personId = personUser.person_id;
+        const enrollment = await (this.prisma as any).course_enrollment.findFirst({
+          where: {
+            person_id: personId,
+            course_id: courseId,
+            status: { in: ['active', 'completed'] },
+          },
+          select: { id: true },
+        });
+        enrollmentId = enrollment?.id ?? null;
+      }
+    }
+
+    // Record raw view event
+    await (this.prisma as any).lesson_view_event.create({
+      data: {
+        user_id: userId ?? null,
+        course_lesson_id: lessonId,
+        course_enrollment_id: enrollmentId,
+        session_id: sessionId ?? null,
+        video_position_seconds: positionSeconds ?? 0,
+        ip: ip ?? null,
+        country: geo?.country ?? null,
+        city: geo?.city ?? null,
+        browser,
+        os,
+        device_type: deviceType,
+        screen_width: screenWidth ?? null,
+        screen_height: screenHeight ?? null,
+        is_touch: isTouch ?? false,
+      },
+    });
+
+    // Update lesson progress if enrolled
+    if (enrollmentId) {
+      const wasLessonCompleted = await this.updateLessonProgress(
+        enrollmentId,
+        lessonId,
+        positionSeconds ?? 0,
+        lesson.duration_seconds ?? 0,
+      );
+
+      if (wasLessonCompleted) {
+        await this.syncEnrollmentProgress(enrollmentId, courseId, personId);
+      }
+    }
+
+    // Publish to admin real-time monitor
+    this.realtime.publish({
+      domain: 'lesson_view',
+      type: 'created',
+      entityId: lessonId,
+      actorId: userId ?? null,
+      payload: {
+        ip,
+        country: geo?.country ?? null,
+        city: geo?.city ?? null,
+        browser,
+        os,
+        deviceType,
+        positionSeconds,
+        enrollmentId,
+      },
+    });
+
+    return { ok: true };
+  }
+
+  private async updateLessonProgress(
+    enrollmentId: number,
+    lessonId: number,
+    positionSeconds: number,
+    durationSeconds: number,
+  ): Promise<boolean> {
+    const progressPercent =
+      durationSeconds > 0
+        ? Math.min(100, Math.round((positionSeconds / durationSeconds) * 100))
+        : positionSeconds > 0
+          ? 100
+          : 0;
+
+    const isCompleted = progressPercent >= 95;
+
+    const existing = await (this.prisma as any).course_lesson_progress.findUnique({
+      where: {
+        course_enrollment_id_course_lesson_id: {
+          course_enrollment_id: enrollmentId,
+          course_lesson_id: lessonId,
+        },
+      },
+      select: { status: true },
+    });
+
+    const wasAlreadyCompleted = existing?.status === 'completed';
+
+    const newStatus = isCompleted
+      ? 'completed'
+      : positionSeconds > 0
+        ? 'in_progress'
+        : 'not_started';
+
+    await (this.prisma as any).course_lesson_progress.upsert({
+      where: {
+        course_enrollment_id_course_lesson_id: {
+          course_enrollment_id: enrollmentId,
+          course_lesson_id: lessonId,
+        },
+      },
+      create: {
+        course_enrollment_id: enrollmentId,
+        course_lesson_id: lessonId,
+        status: newStatus,
+        progress_percent: progressPercent,
+        video_progress_seconds: positionSeconds,
+        started_at: new Date(),
+        completed_at: isCompleted ? new Date() : null,
+        time_spent_seconds: 0,
+      },
+      update: {
+        video_progress_seconds: positionSeconds,
+        progress_percent: wasAlreadyCompleted ? 100 : progressPercent,
+        // Never regress status from completed
+        status: wasAlreadyCompleted ? 'completed' : newStatus,
+        ...(!wasAlreadyCompleted && isCompleted ? { completed_at: new Date() } : {}),
+      },
+    });
+
+    // Returns true when the lesson just became completed for the first time
+    return isCompleted && !wasAlreadyCompleted;
+  }
+
+  private async syncEnrollmentProgress(
+    enrollmentId: number,
+    courseId: number,
+    personId: number | null,
+  ) {
+    const [totalLessons, completedLessons] = await Promise.all([
+      (this.prisma as any).course_lesson.count({
+        where: { published: true, course_module: { course_id: courseId } },
+      }),
+      (this.prisma as any).course_lesson_progress.count({
+        where: {
+          course_enrollment_id: enrollmentId,
+          status: 'completed',
+          course_lesson: { published: true, course_module: { course_id: courseId } },
+        },
+      }),
+    ]);
+
+    const progressPercent =
+      totalLessons > 0 ? Math.round((completedLessons / totalLessons) * 100) : 0;
+
+    const isCourseComplete = progressPercent === 100;
+
+    await (this.prisma as any).course_enrollment.update({
+      where: { id: enrollmentId },
+      data: {
+        progress_percent: progressPercent,
+        ...(isCourseComplete
+          ? { status: 'completed', completed_at: new Date() }
+          : {}),
+      },
+    });
+
+    if (isCourseComplete && personId) {
+      await this.maybeTriggerCertificate(enrollmentId, courseId, personId);
+    }
+  }
+
+  private async maybeTriggerCertificate(
+    enrollmentId: number,
+    courseId: number,
+    personId: number,
+  ) {
+    const enrollment = await (this.prisma as any).course_enrollment.findUnique({
+      where: { id: enrollmentId },
+      select: { certificate_issued_at: true },
+    });
+
+    if (enrollment?.certificate_issued_at) return;
+
+    const course = await (this.prisma as any).course.findUnique({
+      where: { id: courseId },
+      select: { has_certificate: true, certificate_template_id: true },
+    });
+
+    if (!course?.has_certificate || !course.certificate_template_id) return;
+
+    await this.queueJob.enqueue({
+      type: 'lms.emit_certificate',
+      queueName: 'lms.certificate',
+      payload: { enrollmentId, courseId, personId },
+      maxAttempts: 3,
+      sourceModule: 'lms',
+    });
+  }
+
+  private parseUA(ua: string): { browser: string; os: string; deviceType: string } {
+    const browser =
+      /Chrome\//.test(ua) && !/Edg\/|OPR\//.test(ua)
+        ? 'Chrome'
+        : /Firefox\//.test(ua)
+          ? 'Firefox'
+          : /Safari\//.test(ua) && !/Chrome\//.test(ua)
+            ? 'Safari'
+            : /Edg\//.test(ua)
+              ? 'Edge'
+              : /OPR\//.test(ua)
+                ? 'Opera'
+                : 'Other';
+
+    const os =
+      /Android/.test(ua)
+        ? 'Android'
+        : /iPhone|iPad/.test(ua)
+          ? 'iOS'
+          : /Windows/.test(ua)
+            ? 'Windows'
+            : /Mac OS X/.test(ua)
+              ? 'macOS'
+              : /Linux/.test(ua)
+                ? 'Linux'
+                : 'Other';
+
+    const deviceType =
+      /Mobile|Android|iPhone/.test(ua)
+        ? 'mobile'
+        : /iPad|Tablet/.test(ua)
+          ? 'tablet'
+          : 'desktop';
+
+    return { browser, os, deviceType };
+  }
+
+  private async resolveGeo(ip?: string): Promise<{ country: string; city: string } | null> {
+    if (
+      !ip ||
+      ip === '127.0.0.1' ||
+      ip === '::1' ||
+      ip.startsWith('192.168.') ||
+      ip.startsWith('10.') ||
+      ip.startsWith('172.')
+    ) {
+      return null;
+    }
+
+    try {
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), 2000);
+      const res = await fetch(
+        `http://ip-api.com/json/${ip}?fields=status,countryCode,city`,
+        { signal: controller.signal },
+      );
+      clearTimeout(timeout);
+
+      if (!res.ok) return null;
+
+      const data = (await res.json()) as {
+        status: string;
+        countryCode?: string;
+        city?: string;
+      };
+
+      if (data.status !== 'success') return null;
+
+      return {
+        country: (data.countryCode ?? '').slice(0, 2),
+        city: (data.city ?? '').slice(0, 100),
+      };
+    } catch {
+      return null;
+    }
+  }
+}

package/src/platforma/platforma-heartbeat.service.ts

@@ -0,0 +1,33 @@
+import { QueueJobService } from '@hed-hog/queue';
+import { Inject, Injectable, forwardRef } from '@nestjs/common';
+import { HeartbeatDto } from './dto/heartbeat.dto';
+
+@Injectable()
+export class PlatformaHeartbeatService {
+  constructor(
+    @Inject(forwardRef(() => QueueJobService))
+    private readonly queueJob: QueueJobService,
+  ) {}
+
+  async enqueue(userId: number, ip: string, userAgent: string, dto: HeartbeatDto) {
+    await this.queueJob.enqueue({
+      type: 'lms.lesson_heartbeat',
+      queueName: 'lms.heartbeat',
+      payload: {
+        userId,
+        ip,
+        userAgent,
+        lessonId: dto.lessonId,
+        positionSeconds: dto.positionSeconds,
+        sessionId: dto.sessionId ?? null,
+        screenWidth: dto.screenWidth ?? null,
+        screenHeight: dto.screenHeight ?? null,
+        isTouch: dto.isTouch ?? false,
+      },
+      maxAttempts: 2,
+      sourceModule: 'lms',
+    });
+
+    return { ok: true };
+  }
+}