@hed-hog/lms 0.0.364 → 0.0.366

package/src/lesson-xp-map/lesson-xp-ai-calculation.service.ts

@@ -24,6 +24,13 @@ type XpSegmentAiResult = {
   learningTypes: { xpLearningTypeId: number; weightPercent: number }[];
 };
 
+type LessonMeta = {
+  type: 'video' | 'text' | 'quiz';
+  content: string | null;
+  description: string | null;
+  durationSeconds: number;
+};
+
 @Injectable()
 export class LessonXpAiCalculationService implements OnModuleInit, IJobHandler {
   private readonly logger = new Logger(LessonXpAiCalculationService.name);
@@ -45,15 +52,45 @@ export class LessonXpAiCalculationService implements OnModuleInit, IJobHandler {
   }
 
   async triggerCalculation(lessonId: number, userId: number) {
-    const segments = await this.prisma.$queryRawUnsafe<{ id: number }[]>(
-      `SELECT id FROM course_lesson_transcription_segment WHERE course_lesson_id = $1::int LIMIT 1`,
-      lessonId,
-    );
+    const lesson = await this.fetchLessonMeta(lessonId);
 
-    if (!segments.length) {
-      throw new BadRequestException(
-        'Esta aula ainda não possui transcrição. Gere ou importe a transcrição antes de calcular o XP.',
+    if (!lesson) {
+      throw new BadRequestException('Aula não encontrada.');
+    }
+
+    if (lesson.type === 'video') {
+      const segments = await this.prisma.$queryRawUnsafe<{ id: number }[]>(
+        `SELECT id FROM course_lesson_transcription_segment WHERE course_lesson_id = $1::int LIMIT 1`,
+        lessonId,
+      );
+      if (!segments.length) {
+        throw new BadRequestException(
+          'Esta aula ainda não possui transcrição. Gere ou importe a transcrição antes de calcular o XP.',
+        );
+      }
+    } else if (lesson.type === 'text') {
+      if (!lesson.durationSeconds || lesson.durationSeconds <= 0) {
+        throw new BadRequestException(
+          'Esta aula do tipo post precisa ter uma duração prevista configurada antes de calcular o XP.',
+        );
+      }
+      let parsed: any = {};
+      try { parsed = JSON.parse(lesson.content ?? '{}'); } catch { /* ignore */ }
+      if (!parsed.conteudoPost && !lesson.description) {
+        throw new BadRequestException(
+          'Esta aula do tipo post não possui conteúdo nem descrição pública. Adicione o conteúdo antes de calcular o XP.',
+        );
+      }
+    } else if (lesson.type === 'quiz') {
+      const questions = await this.prisma.$queryRawUnsafe<{ id: number }[]>(
+        `SELECT id FROM course_lesson_question WHERE course_lesson_id = $1::int LIMIT 1`,
+        lessonId,
       );
+      if (!questions.length) {
+        throw new BadRequestException(
+          'Esta aula do tipo questão não possui questões vinculadas. Adicione questões antes de calcular o XP.',
+        );
+      }
     }
 
     const existing = await this.prisma.$queryRawUnsafe<{ id: number }[]>(
@@ -129,18 +166,53 @@ export class LessonXpAiCalculationService implements OnModuleInit, IJobHandler {
     this.logger.log(`Starting XP calculation for lesson ${lessonId}, map ${mapId}`);
 
     try {
-      const transcriptionRows = await this.prisma.$queryRawUnsafe<
-        { startSeconds: number; endSeconds: number; text: string }[]
-      >(
-        `SELECT start_seconds::float AS "startSeconds", end_seconds::float AS "endSeconds", text
-           FROM course_lesson_transcription_segment
-          WHERE course_lesson_id = $1
-          ORDER BY start_seconds ASC`,
-        lessonId,
-      );
+      const lesson = await this.fetchLessonMeta(lessonId);
 
-      if (!transcriptionRows.length) {
-        await this.markError(mapId, 'Aula sem segmentos de transcrição.');
+      if (!lesson) {
+        await this.markError(mapId, 'Aula não encontrada.');
+        return;
+      }
+
+      let contentText: string;
+      const durationSeconds = lesson.durationSeconds ?? 0;
+
+      if (lesson.type === 'video') {
+        const transcriptionRows = await this.prisma.$queryRawUnsafe<
+          { startSeconds: number; endSeconds: number; text: string }[]
+        >(
+          `SELECT start_seconds::float AS "startSeconds", end_seconds::float AS "endSeconds", text
+             FROM course_lesson_transcription_segment
+            WHERE course_lesson_id = $1
+            ORDER BY start_seconds ASC`,
+          lessonId,
+        );
+
+        if (!transcriptionRows.length) {
+          await this.markError(mapId, 'Aula sem segmentos de transcrição.');
+          return;
+        }
+
+        contentText = transcriptionRows
+          .map((s) => {
+            const start = this.formatSeconds(s.startSeconds);
+            const end = this.formatSeconds(s.endSeconds);
+            return `[${start} - ${end}] ${s.text}`;
+          })
+          .join('\n');
+      } else if (lesson.type === 'text') {
+        contentText = this.buildPostContentText(lesson.content, lesson.description);
+        if (!contentText.trim()) {
+          await this.markError(mapId, 'Aula do tipo post sem conteúdo disponível para análise.');
+          return;
+        }
+      } else if (lesson.type === 'quiz') {
+        contentText = await this.buildQuizContentText(lessonId);
+        if (!contentText.trim()) {
+          await this.markError(mapId, 'Aula do tipo questão sem questões disponíveis para análise.');
+          return;
+        }
+      } else {
+        await this.markError(mapId, `Tipo de aula não suportado: ${(lesson as any).type}`);
         return;
       }
 
@@ -191,15 +263,7 @@ export class LessonXpAiCalculationService implements OnModuleInit, IJobHandler {
 
       const aiConfig = buildAiConfigFromIntegration(profile.integration_provider.slug, profile.config);
 
-      const transcriptionText = transcriptionRows
-        .map((s) => {
-          const start = this.formatSeconds(s.startSeconds);
-          const end = this.formatSeconds(s.endSeconds);
-          return `[${start} - ${end}] ${s.text}`;
-        })
-        .join('\n');
-
-      const prompt = this.buildPrompt(transcriptionText, areas, skills, learningTypes);
+      const prompt = this.buildPrompt(contentText, areas, skills, learningTypes, lesson.type, durationSeconds);
 
       const response = await axios.post(
         'https://api.openai.com/v1/chat/completions',
@@ -330,6 +394,85 @@ export class LessonXpAiCalculationService implements OnModuleInit, IJobHandler {
     }
   }
 
+  private async fetchLessonMeta(lessonId: number): Promise<LessonMeta | null> {
+    const rows = await this.prisma.$queryRawUnsafe<LessonMeta[]>(
+      `SELECT type::text AS type, content, description, duration_seconds AS "durationSeconds"
+         FROM course_lesson WHERE id = $1`,
+      lessonId,
+    );
+    return rows[0] ?? null;
+  }
+
+  private buildPostContentText(content: string | null, description: string | null): string {
+    const parts: string[] = [];
+
+    if (description?.trim()) {
+      parts.push(`Descrição pública:\n${description.trim()}`);
+    }
+
+    let postContent = '';
+    try {
+      const parsed = JSON.parse(content ?? '{}');
+      postContent = String(parsed.conteudoPost ?? '').trim();
+    } catch { /* ignore */ }
+
+    if (postContent) {
+      parts.push(`Conteúdo do post:\n${this.stripHtml(postContent)}`);
+    }
+
+    return parts.join('\n\n');
+  }
+
+  private async buildQuizContentText(lessonId: number): Promise<string> {
+    const questions = await this.prisma.$queryRawUnsafe<{
+      statement: string;
+      explanation: string | null;
+      options: { text: string; isCorrect: boolean; feedback: string | null }[] | null;
+    }[]>(
+      `SELECT
+          q.statement,
+          q.explanation,
+          COALESCE(
+            json_agg(
+              json_build_object('text', o.option_text, 'isCorrect', o.is_correct, 'feedback', o.feedback)
+              ORDER BY o.position ASC
+            ) FILTER (WHERE o.id IS NOT NULL),
+            '[]'
+          ) AS options
+        FROM course_lesson_question clq
+        JOIN question q ON q.id = clq.question_id
+        LEFT JOIN exam_option o ON o.question_id = q.id
+       WHERE clq.course_lesson_id = $1
+       GROUP BY clq.order, q.statement, q.explanation
+       ORDER BY clq.order ASC`,
+      lessonId,
+    );
+
+    if (!questions.length) return '';
+
+    return questions.map((q, i) => {
+      const lines: string[] = [`Questão ${i + 1}:`];
+      lines.push(`Enunciado: ${q.statement}`);
+
+      const opts = Array.isArray(q.options) ? q.options : [];
+      if (opts.length) {
+        const labels = 'abcdefghijklmnopqrstuvwxyz';
+        lines.push(
+          'Alternativas: ' +
+            opts
+              .map((o, idx) => `${labels[idx] ?? idx + 1}) ${o.text}${o.isCorrect ? ' [CORRETA]' : ''}`)
+              .join('; '),
+        );
+      }
+
+      if (q.explanation?.trim()) {
+        lines.push(`Explicação: ${q.explanation.trim()}`);
+      }
+
+      return lines.join('\n');
+    }).join('\n\n');
+  }
+
   private async markError(mapId: number, message: string) {
     await this.prisma.$executeRawUnsafe(
       `UPDATE lesson_xp_map
@@ -343,12 +486,30 @@ export class LessonXpAiCalculationService implements OnModuleInit, IJobHandler {
   }
 
   private buildPrompt(
-    transcription: string,
+    content: string,
     areas: { id: number; slug: string; name: string }[],
     skills: { id: number; slug: string; name: string; areaId: number | null }[],
     learningTypes: { id: number; slug: string; name: string; multiplier: number }[],
+    lessonType: 'video' | 'text' | 'quiz',
+    durationSeconds: number,
   ): string {
-    return `Analise a transcrição abaixo e mapeie as competências técnicas de cada segmento de ~60 segundos.
+    const totalMinutes = Math.max(Math.ceil(durationSeconds / 60), 1);
+
+    const contentHeader =
+      lessonType === 'video'
+        ? 'TRANSCRIÇÃO DA AULA'
+        : lessonType === 'text'
+          ? 'CONTEÚDO DO POST'
+          : 'QUESTÕES DA AULA';
+
+    const segmentInstruction =
+      lessonType === 'video'
+        ? 'Analise a transcrição abaixo e mapeie as competências técnicas de cada segmento de ~60 segundos.'
+        : lessonType === 'text'
+          ? `Analise o conteúdo do post abaixo (duração estimada: ${totalMinutes} minutos) e mapeie as competências técnicas. Divida o conteúdo em segmentos de ~60 segundos cobrindo a duração total. Os valores de startSeconds e endSeconds devem cobrir de 0 até ${durationSeconds} segundos.`
+          : `Analise as questões da aula abaixo (duração estimada: ${totalMinutes} minutos). Cada questão representa um segmento; distribua o tempo total de ${durationSeconds} segundos igualmente entre as questões. Os valores de startSeconds e endSeconds devem cobrir de 0 até ${durationSeconds} segundos.`;
+
+    return `${segmentInstruction}
 
 CATÁLOGO DE ÁREAS MACRO (use APENAS estes IDs):
 ${JSON.stringify(areas.map((a) => ({ id: a.id, slug: a.slug, name: a.name })))}
@@ -359,8 +520,8 @@ ${JSON.stringify(skills.map((s) => ({ id: s.id, slug: s.slug, name: s.name, area
 CATÁLOGO DE TIPOS DE APRENDIZADO (use APENAS estes IDs):
 ${JSON.stringify(learningTypes.map((l) => ({ id: l.id, slug: l.slug, name: l.name, multiplier: l.multiplier })))}
 
-TRANSCRIÇÃO DA AULA:
-${transcription}
+${contentHeader}:
+${content}
 
 Retorne um JSON com a chave "segments" contendo um array onde cada item representa um segmento de ~60s:
 {
@@ -388,6 +549,19 @@ Regras obrigatórias:
 - aiConfidence: 0 a 1, indica certeza do mapeamento.`;
   }
 
+  private stripHtml(html: string): string {
+    return html
+      .replace(/<[^>]+>/g, ' ')
+      .replace(/&amp;/g, '&')
+      .replace(/&lt;/g, '<')
+      .replace(/&gt;/g, '>')
+      .replace(/&quot;/g, '"')
+      .replace(/&#39;/g, "'")
+      .replace(/&nbsp;/g, ' ')
+      .replace(/\s{2,}/g, ' ')
+      .trim();
+  }
+
   private formatSeconds(s: number): string {
     const m = Math.floor(s / 60);
     const sec = Math.floor(s % 60);

package/src/lms-commerce-access.subscriber.ts

@@ -0,0 +1,88 @@
+import { IntegrationDeveloperApiService } from '@hed-hog/core';
+import { Injectable, Logger, OnModuleInit } from '@nestjs/common';
+
+type SubscriptionActivatedPayload = {
+  subscription_id?: number | null;
+  customer_id?: number | null;
+  user_id?: number | null;
+  product_id?: number | null;
+  plan_version_id?: number | null;
+  price_id?: number | null;
+  current_period_start?: string | null;
+  current_period_end?: string | null;
+};
+
+type SubscriptionCanceledPayload = {
+  subscription_id?: number | null;
+  reason?: string | null;
+  canceled_at?: string | null;
+  entitlement_revoked?: boolean | null;
+};
+
+@Injectable()
+export class LmsCommerceAccessSubscriber implements OnModuleInit {
+  private readonly logger = new Logger(LmsCommerceAccessSubscriber.name);
+
+  constructor(
+    private readonly integrationApi: IntegrationDeveloperApiService,
+  ) {}
+
+  onModuleInit(): void {
+    this.integrationApi.subscribeMany([
+      {
+        eventName: 'commerce.subscription.activated',
+        consumerName: 'lms.commerce-subscription-activated',
+        priority: 0,
+        handler: async (event) => this.onSubscriptionActivated(event),
+      },
+      {
+        eventName: 'commerce.subscription.canceled',
+        consumerName: 'lms.commerce-subscription-canceled',
+        priority: 0,
+        handler: async (event) => this.onSubscriptionCanceled(event),
+      },
+    ]);
+  }
+
+  private async onSubscriptionActivated(event: any): Promise<void> {
+    const payload = (event.payload ?? {}) as SubscriptionActivatedPayload;
+    const userId = Number(payload.user_id ?? 0);
+    const productId = Number(payload.product_id ?? 0);
+    const subscriptionId = Number(payload.subscription_id ?? 0);
+
+    if (!userId || !productId) {
+      this.logger.warn(
+        `commerce.subscription.activated: missing user_id or product_id (subscription ${subscriptionId}) — skipping LMS side effects`,
+      );
+      return;
+    }
+
+    this.logger.log(
+      `LMS access granted: subscription ${subscriptionId} activated for user ${userId} / product ${productId}`,
+    );
+
+    // Extension point: look up integration links product_id → lms course/plan
+    // and auto-enroll the student in the corresponding class group.
+    // Example shape of what would go here:
+    //
+    // const links = await this.integrationApi.findLinksBySource({
+    //   module: 'commerce',
+    //   entityType: 'product',
+    //   entityId: String(productId),
+    // });
+    // for (const link of links.filter(l => l.targetModule === 'lms' && l.targetEntityType === 'course')) {
+    //   await this.classGroupService.enrollStudent(Number(link.targetEntityId), userId);
+    // }
+  }
+
+  private async onSubscriptionCanceled(event: any): Promise<void> {
+    const payload = (event.payload ?? {}) as SubscriptionCanceledPayload;
+    const subscriptionId = Number(payload.subscription_id ?? 0);
+
+    this.logger.log(
+      `LMS access revoked: subscription ${subscriptionId} canceled (reason: ${payload.reason ?? 'none'}, entitlement_revoked: ${payload.entitlement_revoked})`,
+    );
+
+    // Extension point: remove student from active class groups linked to this subscription.
+  }
+}

package/src/lms.module.ts

@@ -2,6 +2,7 @@ import { LocaleModule } from '@hed-hog/api-locale';
 import { PaginationModule } from '@hed-hog/api-pagination';
 import { PrismaModule } from '@hed-hog/api-prisma';
 import { CoreModule } from '@hed-hog/core';
+import { CommerceModule } from '@hed-hog/commerce';
 import { QueueModule } from '@hed-hog/queue';
 import { forwardRef, Module } from '@nestjs/common';
 import { ConfigModule } from '@nestjs/config';
@@ -11,8 +12,8 @@ import { LmsCertificateModule } from './certificate/certificate.module';
 import { ClassGroupModule } from './class-group/class-group.module';
 import { CourseLessonDiscussionModule } from './course-lesson-discussion/course-lesson-discussion.module';
 import { CourseLessonNoteModule } from './course-lesson-note/course-lesson-note.module';
+import { LmsCommerceAccessSubscriber } from './lms-commerce-access.subscriber';
 import { CourseAudioTranscriptionService } from './course/course-audio-transcription.service';
-import { LmsBulkUploadAutomationService } from './course/lms-bulk-upload-automation.service';
 import { CourseModule } from './course/course.module';
 import { LmsDashboardModule } from './dashboard/dashboard.module';
 import { EnterpriseModule } from './enterprise/enterprise.module';
@@ -21,14 +22,19 @@ import { EvaluationModule } from './evaluation/evaluation.module';
 import { ExamModule } from './exam/exam.module';
 import { InstructorModule } from './instructor/instructor.module';
 import { LessonXpMapModule } from './lesson-xp-map/lesson-xp-map.module';
+import { EmitCertificateHandler } from './platforma/handlers/emit-certificate.handler';
+import { LessonHeartbeatHandler } from './platforma/handlers/lesson-heartbeat.handler';
 import { PlataformaController } from './platforma/platforma.controller';
+import { PlatformaHeartbeatService } from './platforma/platforma-heartbeat.service';
+import { PlatformaPerformanceService } from './platforma/platforma-performance.service';
+import { PlatformaSearchService } from './platforma/platforma-search.service';
+import { PlatformaVideoService } from './platforma/platforma-video.service';
 import { StudentXpModule } from './student-xp/student-xp.module';
 import { XpCatalogModule } from './xp-catalog/xp-catalog.module';
 import { PlatformaService } from './platforma/platforma.service';
 import { LmsRealtimeModule } from './realtime/lms-realtime.module';
 import { LmsReportsModule } from './reports/reports.module';
 import { TrainingModule } from './training/training.module';
-import { VideoResolutionProfileModule } from './video-resolution-profile/video-resolution-profile.module';
 
 @Module({
   imports: [
@@ -37,6 +43,7 @@ import { VideoResolutionProfileModule } from './video-resolution-profile/video-r
     forwardRef(() => PrismaModule),
     forwardRef(() => CoreModule),
     forwardRef(() => QueueModule),
+    forwardRef(() => CommerceModule),
     forwardRef(() => LocaleModule),
     forwardRef(() => AchievementModule),
     forwardRef(() => BitcodeWalletModule),
@@ -54,7 +61,6 @@ import { VideoResolutionProfileModule } from './video-resolution-profile/video-r
     forwardRef(() => LmsRealtimeModule),
     forwardRef(() => LmsReportsModule),
     forwardRef(() => TrainingModule),
-    forwardRef(() => VideoResolutionProfileModule),
     forwardRef(() => XpCatalogModule),
     forwardRef(() => LessonXpMapModule),
     forwardRef(() => StudentXpModule),
@@ -62,8 +68,14 @@ import { VideoResolutionProfileModule } from './video-resolution-profile/video-r
   controllers: [PlataformaController],
   providers: [
     CourseAudioTranscriptionService,
-    LmsBulkUploadAutomationService,
     PlatformaService,
+    PlatformaVideoService,
+    PlatformaHeartbeatService,
+    PlatformaPerformanceService,
+    PlatformaSearchService,
+    LessonHeartbeatHandler,
+    EmitCertificateHandler,
+    LmsCommerceAccessSubscriber,
   ],
   exports: [
     forwardRef(() => AchievementModule),
@@ -82,7 +94,6 @@ import { VideoResolutionProfileModule } from './video-resolution-profile/video-r
     forwardRef(() => LmsRealtimeModule),
     forwardRef(() => LmsReportsModule),
     forwardRef(() => TrainingModule),
-    forwardRef(() => VideoResolutionProfileModule),
     forwardRef(() => XpCatalogModule),
     forwardRef(() => LessonXpMapModule),
     forwardRef(() => StudentXpModule),

package/src/platforma/dto/heartbeat.dto.ts

@@ -0,0 +1,30 @@
+import { IsBoolean, IsInt, IsOptional, IsString, Max, Min } from 'class-validator';
+
+export class HeartbeatDto {
+  @IsInt()
+  lessonId: number;
+
+  @IsInt()
+  @Min(0)
+  positionSeconds: number;
+
+  @IsOptional()
+  @IsString()
+  sessionId?: string;
+
+  @IsOptional()
+  @IsInt()
+  @Min(1)
+  @Max(10000)
+  screenWidth?: number;
+
+  @IsOptional()
+  @IsInt()
+  @Min(1)
+  @Max(10000)
+  screenHeight?: number;
+
+  @IsOptional()
+  @IsBoolean()
+  isTouch?: boolean;
+}

package/src/platforma/handlers/emit-certificate.handler.ts

@@ -0,0 +1,117 @@
+import { PrismaService } from '@hed-hog/api-prisma';
+import { IJobHandler, QueueHandlerRegistry } from '@hed-hog/queue';
+import { Inject, Injectable, Logger, OnModuleInit, forwardRef } from '@nestjs/common';
+import { randomBytes } from 'crypto';
+
+export const EMIT_CERTIFICATE_JOB = 'lms.emit_certificate';
+
+@Injectable()
+export class EmitCertificateHandler implements OnModuleInit, IJobHandler {
+  private readonly logger = new Logger(EmitCertificateHandler.name);
+
+  constructor(
+    @Inject(forwardRef(() => PrismaService))
+    private readonly prisma: PrismaService,
+    @Inject(forwardRef(() => QueueHandlerRegistry))
+    private readonly registry: QueueHandlerRegistry,
+  ) {}
+
+  onModuleInit() {
+    this.registry.register(EMIT_CERTIFICATE_JOB, this);
+    this.logger.log(`Registered handler for "${EMIT_CERTIFICATE_JOB}"`);
+  }
+
+  async handle(job: { payload: Record<string, any> }) {
+    const { enrollmentId, courseId, personId } = job.payload as {
+      enrollmentId: number;
+      courseId: number;
+      personId: number;
+    };
+
+    // Idempotency guard — re-entrancy safe
+    const enrollment = await (this.prisma as any).course_enrollment.findUnique({
+      where: { id: enrollmentId },
+      select: { certificate_issued_at: true, completed_at: true, final_score: true },
+    });
+
+    if (!enrollment) {
+      this.logger.warn(`Enrollment ${enrollmentId} not found, skipping certificate`);
+      return { skipped: true };
+    }
+
+    if (enrollment.certificate_issued_at) {
+      this.logger.log(`Certificate already issued for enrollment ${enrollmentId}`);
+      return { skipped: true, alreadyIssued: true };
+    }
+
+    const [person, course] = await Promise.all([
+      this.prisma.person.findUnique({
+        where: { id: personId },
+        select: { name: true },
+      }),
+      (this.prisma as any).course.findUnique({
+        where: { id: courseId },
+        select: {
+          title: true,
+          certificate_workload: true,
+          has_certificate: true,
+          certificate_template_id: true,
+        },
+      }),
+    ]);
+
+    if (!person || !course) {
+      this.logger.warn(`Person or course not found (enrollment ${enrollmentId})`);
+      return { skipped: true };
+    }
+
+    if (!course.has_certificate || !course.certificate_template_id) {
+      this.logger.log(`Course ${courseId} does not issue certificates`);
+      return { skipped: true };
+    }
+
+    // Compute workload hours from lesson durations when not set on the course
+    let workloadHours: number = course.certificate_workload ?? 0;
+    if (!workloadHours) {
+      const agg = await (this.prisma as any).course_lesson.aggregate({
+        where: { published: true, course_module: { course_id: courseId } },
+        _sum: { duration_seconds: true },
+      });
+      const totalSeconds = (agg._sum?.duration_seconds as number) ?? 0;
+      workloadHours = Math.max(1, Math.ceil(totalSeconds / 3600));
+    }
+
+    const issuedAt = new Date();
+    const verificationCode = randomBytes(12).toString('hex').toUpperCase();
+
+    await (this.prisma as any).certificate.create({
+      data: {
+        verification_code: verificationCode,
+        student_id: personId,
+        course_enrollment_id: enrollmentId,
+        course_id: courseId,
+        certificate_template_id: course.certificate_template_id,
+        certificate_type: 'course',
+        student_name: person.name ?? '',
+        course_name: course.title ?? '',
+        workload_hours: workloadHours,
+        issued_at: issuedAt,
+        completed_at: enrollment.completed_at ?? issuedAt,
+        final_score: enrollment.final_score ?? null,
+        public_access: false,
+      },
+    });
+
+    // Mark enrollment as issued — prevents duplicate certificates on any future re-run
+    await (this.prisma as any).course_enrollment.update({
+      where: { id: enrollmentId },
+      data: { certificate_issued_at: issuedAt },
+    });
+
+    this.logger.log(
+      `Certificate issued — enrollment=${enrollmentId} course=${courseId} code=${verificationCode}`,
+    );
+
+    return { verificationCode };
+  }
+}