@hed-hog/lms 0.0.361 → 0.0.365

package/src/platforma/platforma.service.ts

@@ -0,0 +1,268 @@
+import { PrismaService } from '@hed-hog/api-prisma';
+import { Injectable } from '@nestjs/common';
+import { UpdatePlatformaProfileDto } from './dto/update-profile.dto';
+
+function mapGenderToDb(
+  gender?: string | null,
+): 'male' | 'female' | 'other' | null {
+  if (!gender) return null;
+  if (gender === 'Masculino') return 'male';
+  if (gender === 'Feminino') return 'female';
+  return 'other';
+}
+
+function mapGenderToDisplay(gender?: string | null): string | null {
+  if (!gender) return null;
+  if (gender === 'male') return 'Masculino';
+  if (gender === 'female') return 'Feminino';
+  return 'Prefiro nao dizer';
+}
+
+function buildLine1(street?: string | null, number?: string | null): string {
+  if (!street && !number) return '';
+  if (!number) return street ?? '';
+  if (!street) return number;
+  return `${street}, ${number}`;
+}
+
+function buildLine2(
+  neighborhood?: string | null,
+  complement?: string | null,
+): string {
+  const parts = [neighborhood, complement].filter(Boolean);
+  return parts.join('; ');
+}
+
+function parseAddressLine1(line1?: string | null): [string, string] {
+  if (!line1) return ['', ''];
+  const idx = line1.lastIndexOf(', ');
+  if (idx === -1) return [line1, ''];
+  return [line1.slice(0, idx), line1.slice(idx + 2)];
+}
+
+function parseAddressLine2(line2?: string | null): [string, string] {
+  if (!line2) return ['', ''];
+  const idx = line2.indexOf('; ');
+  if (idx === -1) return [line2, ''];
+  return [line2.slice(0, idx), line2.slice(idx + 2)];
+}
+
+@Injectable()
+export class PlatformaService {
+  constructor(private readonly prisma: PrismaService) {}
+
+  async getProfile(userId: number) {
+    const [user, personUser] = await Promise.all([
+      this.prisma.user.findUnique({ where: { id: userId } }),
+      this.prisma.person_user.findFirst({
+        where: { user_id: userId },
+        select: { person_id: true },
+      }),
+    ]);
+
+    const personId = personUser?.person_id;
+
+    const [individual, contacts, documents, personAddresses] =
+      await Promise.all([
+        personId
+          ? this.prisma.person_individual.findUnique({
+              where: { id: personId },
+            })
+          : Promise.resolve(null),
+        personId
+          ? this.prisma.contact.findMany({
+              where: { person_id: personId },
+              include: { contact_type: true },
+            })
+          : Promise.resolve([]),
+        personId
+          ? this.prisma.document.findMany({
+              where: { person_id: personId },
+              include: { document_type: true },
+            })
+          : Promise.resolve([]),
+        personId
+          ? this.prisma.person_address.findMany({
+              where: { person_id: personId },
+              include: { address: true },
+              orderBy: { address: { is_primary: 'desc' } },
+            })
+          : Promise.resolve([]),
+      ]);
+
+    const phoneContact = contacts.find((c) => c.contact_type.code === 'PHONE');
+    const cpfDoc = documents.find((d) => d.document_type.code === 'CPF');
+    const primaryAddress =
+      personAddresses.find((pa) => pa.address.is_primary)?.address ??
+      personAddresses[0]?.address;
+
+    const [street, number] = parseAddressLine1(primaryAddress?.line1);
+    const [neighborhood, complement] = parseAddressLine2(primaryAddress?.line2);
+
+    return {
+      id: user?.id,
+      name: user?.name ?? null,
+      cpf: cpfDoc?.value ?? null,
+      dob: individual?.birth_date
+        ? individual.birth_date.toISOString().slice(0, 10)
+        : null,
+      gender: mapGenderToDisplay(individual?.gender as string | null),
+      country: primaryAddress?.country_code ?? null,
+      city: primaryAddress?.city ?? null,
+      state: primaryAddress?.state ?? null,
+      neighborhood,
+      street,
+      number,
+      complement,
+      zip: primaryAddress?.postal_code ?? null,
+      phone: phoneContact?.value ?? null,
+      profession: individual?.job_title ?? null,
+    };
+  }
+
+  async updateProfile(userId: number, dto: UpdatePlatformaProfileDto) {
+    await this.prisma.$transaction(async (tx) => {
+      if (dto.name) {
+        await tx.user.update({
+          where: { id: userId },
+          data: { name: dto.name },
+        });
+      }
+
+      let personUser = await tx.person_user.findFirst({
+        where: { user_id: userId },
+      });
+      let personId: number;
+
+      if (!personUser) {
+        const user = await tx.user.findUnique({ where: { id: userId } });
+        const newPerson = await tx.person.create({
+          data: {
+            name: dto.name ?? user?.name ?? '',
+            type: 'individual',
+            status: 'active',
+          } as any,
+        });
+        await tx.person_user.create({
+          data: { person_id: newPerson.id, user_id: userId },
+        });
+        personId = newPerson.id;
+      } else {
+        personId = personUser.person_id;
+        if (dto.name) {
+          await tx.person.update({
+            where: { id: personId },
+            data: { name: dto.name },
+          });
+        }
+      }
+
+      const individualData: Record<string, unknown> = {};
+      if (dto.dob !== undefined) {
+        individualData.birth_date = dto.dob ? new Date(dto.dob) : null;
+      }
+      if (dto.gender !== undefined) {
+        individualData.gender = mapGenderToDb(dto.gender);
+      }
+      if (dto.profession !== undefined) {
+        individualData.job_title = dto.profession || null;
+      }
+
+      await (tx as any).person_individual.upsert({
+        where: { id: personId },
+        create: { id: personId, ...individualData },
+        update: individualData,
+      });
+
+      const phoneType = await tx.contact_type.findFirst({
+        where: { code: 'PHONE' },
+      });
+      if (phoneType && dto.phone !== undefined) {
+        const existingPhone = await tx.contact.findFirst({
+          where: { person_id: personId, contact_type_id: phoneType.id },
+        });
+        if (dto.phone) {
+          if (existingPhone) {
+            await tx.contact.update({
+              where: { id: existingPhone.id },
+              data: { value: dto.phone },
+            });
+          } else {
+            await tx.contact.create({
+              data: {
+                person_id: personId,
+                contact_type_id: phoneType.id,
+                value: dto.phone,
+                is_primary: true,
+              },
+            });
+          }
+        } else if (existingPhone) {
+          await tx.contact.delete({ where: { id: existingPhone.id } });
+        }
+      }
+
+      const cpfType = await tx.document_type.findFirst({
+        where: { code: 'CPF' },
+      });
+      if (cpfType && dto.cpf !== undefined) {
+        const existingCpf = await tx.document.findFirst({
+          where: { person_id: personId, document_type_id: cpfType.id },
+        });
+        if (dto.cpf) {
+          if (existingCpf) {
+            await tx.document.update({
+              where: { id: existingCpf.id },
+              data: { value: dto.cpf },
+            });
+          } else {
+            await tx.document.create({
+              data: {
+                person_id: personId,
+                document_type_id: cpfType.id,
+                value: dto.cpf,
+              },
+            });
+          }
+        } else if (existingCpf) {
+          await tx.document.delete({ where: { id: existingCpf.id } });
+        }
+      }
+
+      const hasAddressData =
+        dto.street || dto.city || dto.state || dto.zip || dto.country;
+      if (hasAddressData) {
+        const existingPersonAddress = await tx.person_address.findFirst({
+          where: { person_id: personId },
+          include: { address: true },
+          orderBy: { address: { is_primary: 'desc' } },
+        });
+
+        const addressData = {
+          country_code: dto.country ?? '',
+          state: dto.state ?? '',
+          city: dto.city ?? '',
+          postal_code: (dto.zip ?? '').replace(/\D/g, ''),
+          line1: buildLine1(dto.street, dto.number),
+          line2: buildLine2(dto.neighborhood, dto.complement),
+          is_primary: true,
+          address_type: 'residential' as const,
+        };
+
+        if (existingPersonAddress) {
+          await tx.address.update({
+            where: { id: existingPersonAddress.address_id },
+            data: addressData,
+          });
+        } else {
+          const newAddress = await tx.address.create({ data: addressData });
+          await tx.person_address.create({
+            data: { person_id: personId, address_id: newAddress.id },
+          });
+        }
+      }
+    });
+
+    return { success: true };
+  }
+}

package/src/student-xp/dto/grant-skill-card-xp.dto.ts

@@ -0,0 +1,10 @@
+import { IsInt, IsString, Min } from 'class-validator';
+
+export class GrantSkillCardXpDto {
+  @IsString()
+  skillCardSlug: string;
+
+  @IsInt()
+  @Min(1)
+  xpEarned: number;
+}

package/src/student-xp/student-xp.controller.ts

@@ -0,0 +1,92 @@
+import { NoRole, Role, User } from '@hed-hog/api';
+import { Body, Controller, Get, Param, ParseIntPipe, Post, Query } from '@nestjs/common';
+import { GrantSkillCardXpDto } from './dto/grant-skill-card-xp.dto';
+import { StudentXpService } from './student-xp.service';
+
+@Role()
+@Controller('lms/xp')
+export class StudentXpController {
+  constructor(private readonly studentXpService: StudentXpService) {}
+
+  @Get('events')
+  listEvents(
+    @Query('page') page?: string,
+    @Query('pageSize') pageSize?: string,
+    @Query('personId') personId?: string,
+    @Query('courseLessonId') courseLessonId?: string,
+    @Query('source') source?: string,
+  ) {
+    return this.studentXpService.listEvents({
+      page: Number(page) || 1,
+      pageSize: Number(pageSize) || 20,
+      personId: personId ? Number(personId) : undefined,
+      courseLessonId: courseLessonId ? Number(courseLessonId) : undefined,
+      source,
+    });
+  }
+
+  @Get('balances/areas')
+  listAreaBalances(
+    @Query('page') page?: string,
+    @Query('pageSize') pageSize?: string,
+    @Query('personId') personId?: string,
+    @Query('areaId') areaId?: string,
+  ) {
+    return this.studentXpService.listAreaBalances({
+      page: Number(page) || 1,
+      pageSize: Number(pageSize) || 20,
+      personId: personId ? Number(personId) : undefined,
+      areaId: areaId ? Number(areaId) : undefined,
+    });
+  }
+
+  @Get('balances/skills')
+  listSkillBalances(
+    @Query('page') page?: string,
+    @Query('pageSize') pageSize?: string,
+    @Query('personId') personId?: string,
+    @Query('skillId') skillId?: string,
+  ) {
+    return this.studentXpService.listSkillBalances({
+      page: Number(page) || 1,
+      pageSize: Number(pageSize) || 20,
+      personId: personId ? Number(personId) : undefined,
+      skillId: skillId ? Number(skillId) : undefined,
+    });
+  }
+
+  @Get('balances/learning-types')
+  listLearningTypeBalances(
+    @Query('page') page?: string,
+    @Query('pageSize') pageSize?: string,
+    @Query('personId') personId?: string,
+    @Query('learningTypeId') learningTypeId?: string,
+  ) {
+    return this.studentXpService.listLearningTypeBalances({
+      page: Number(page) || 1,
+      pageSize: Number(pageSize) || 20,
+      personId: personId ? Number(personId) : undefined,
+      learningTypeId: learningTypeId ? Number(learningTypeId) : undefined,
+    });
+  }
+
+  @Get('balances/person/:personId')
+  getPersonBalanceSummary(@Param('personId', ParseIntPipe) personId: number) {
+    return this.studentXpService.getPersonBalanceSummary(personId);
+  }
+
+  @Get('my-balance')
+  @NoRole()
+  getMyBalance(@User('id') userId: number) {
+    return this.studentXpService.getMyBalance(userId);
+  }
+
+  @Post('skill-card')
+  @NoRole()
+  grantSkillCardXp(
+    @User('id') userId: number,
+    @Body() dto: GrantSkillCardXpDto,
+  ) {
+    return this.studentXpService.grantSkillCardXp(userId, dto);
+  }
+}

package/src/student-xp/student-xp.module.ts

@@ -0,0 +1,12 @@
+import { PrismaModule } from '@hed-hog/api-prisma';
+import { forwardRef, Module } from '@nestjs/common';
+import { StudentXpController } from './student-xp.controller';
+import { StudentXpService } from './student-xp.service';
+
+@Module({
+  imports: [forwardRef(() => PrismaModule)],
+  controllers: [StudentXpController],
+  providers: [StudentXpService],
+  exports: [StudentXpService],
+})
+export class StudentXpModule {}

package/src/student-xp/student-xp.service.ts

@@ -0,0 +1,318 @@
+import { PrismaService } from '@hed-hog/api-prisma';
+import {
+  BadRequestException,
+  Injectable,
+  NotFoundException,
+} from '@nestjs/common';
+import { GrantSkillCardXpDto } from './dto/grant-skill-card-xp.dto';
+
+@Injectable()
+export class StudentXpService {
+  constructor(private readonly prisma: PrismaService) {}
+
+  async listEvents(params: {
+    page?: number;
+    pageSize?: number;
+    personId?: number;
+    courseLessonId?: number;
+    source?: string;
+  }) {
+    const page = Math.max(Number(params.page) || 1, 1);
+    const pageSize = Math.max(Number(params.pageSize) || 20, 1);
+    const offset = (page - 1) * pageSize;
+
+    const values: unknown[] = [];
+    const where: string[] = ['1 = 1'];
+
+    if (params.personId) {
+      where.push(`ce.person_id = ${this.param(values, params.personId)}`);
+    }
+    if (params.courseLessonId) {
+      where.push(`m.course_lesson_id = ${this.param(values, params.courseLessonId)}`);
+    }
+    if (params.source?.trim()) {
+      where.push(`e.source::text = ${this.param(values, params.source.trim())}`);
+    }
+
+    const whereClause = where.join(' AND ');
+
+    const totalRow = await this.querySingle<{ total: string }>(
+      `SELECT COUNT(*)::text AS total
+         FROM student_xp_event e
+         JOIN course_enrollment ce ON ce.id = e.course_enrollment_id
+         JOIN lesson_xp_segment s ON s.id = e.lesson_xp_segment_id
+         JOIN lesson_xp_map m ON m.id = s.lesson_xp_map_id
+        WHERE ${whereClause}`,
+      values,
+    );
+
+    const q = [...values];
+    const rows = await this.queryRows<any>(
+      `SELECT
+          e.id,
+          e.course_enrollment_id AS "courseEnrollmentId",
+          ce.person_id AS "personId",
+          e.lesson_xp_segment_id AS "lessonXpSegmentId",
+          m.course_lesson_id AS "courseLessonId",
+          e.xp_earned AS "xpEarned",
+          e.watch_percent::float AS "watchPercent",
+          e.granted_at::text AS "grantedAt",
+          e.source::text AS source,
+          e.created_at::text AS "createdAt"
+        FROM student_xp_event e
+        JOIN course_enrollment ce ON ce.id = e.course_enrollment_id
+        JOIN lesson_xp_segment s ON s.id = e.lesson_xp_segment_id
+        JOIN lesson_xp_map m ON m.id = s.lesson_xp_map_id
+       WHERE ${whereClause}
+       ORDER BY e.granted_at DESC
+       LIMIT ${this.param(q, pageSize)} OFFSET ${this.param(q, offset)}`,
+      q,
+    );
+
+    const total = Number(totalRow?.total ?? 0);
+    return { data: rows, total, page, pageSize, lastPage: Math.ceil(total / pageSize) };
+  }
+
+  async listAreaBalances(params: { page?: number; pageSize?: number; personId?: number; areaId?: number }) {
+    const page = Math.max(Number(params.page) || 1, 1);
+    const pageSize = Math.max(Number(params.pageSize) || 20, 1);
+    const offset = (page - 1) * pageSize;
+
+    const values: unknown[] = [];
+    const where: string[] = ['1 = 1'];
+    if (params.personId) where.push(`b.person_id = ${this.param(values, params.personId)}`);
+    if (params.areaId) where.push(`b.xp_area_id = ${this.param(values, params.areaId)}`);
+    const whereClause = where.join(' AND ');
+
+    const totalRow = await this.querySingle<{ total: string }>(
+      `SELECT COUNT(*)::text AS total FROM student_area_xp b WHERE ${whereClause}`,
+      values,
+    );
+
+    const q = [...values];
+    const rows = await this.queryRows<any>(
+      `SELECT
+          b.id, b.person_id AS "personId", b.xp_area_id AS "xpAreaId",
+          COALESCE(l.name, a.slug) AS "areaName",
+          b.total_xp AS "totalXp", b.event_count AS "eventCount",
+          b.last_updated_at::text AS "lastUpdatedAt"
+        FROM student_area_xp b
+        JOIN xp_area a ON a.id = b.xp_area_id
+        LEFT JOIN xp_area_locale l ON l.xp_area_id = a.id
+          AND l.locale_id = (SELECT id FROM locale WHERE code = 'pt' LIMIT 1)
+       WHERE ${whereClause}
+       ORDER BY b.total_xp DESC
+       LIMIT ${this.param(q, pageSize)} OFFSET ${this.param(q, offset)}`,
+      q,
+    );
+
+    const total = Number(totalRow?.total ?? 0);
+    return { data: rows, total, page, pageSize, lastPage: Math.ceil(total / pageSize) };
+  }
+
+  async listSkillBalances(params: { page?: number; pageSize?: number; personId?: number; skillId?: number }) {
+    const page = Math.max(Number(params.page) || 1, 1);
+    const pageSize = Math.max(Number(params.pageSize) || 20, 1);
+    const offset = (page - 1) * pageSize;
+
+    const values: unknown[] = [];
+    const where: string[] = ['1 = 1'];
+    if (params.personId) where.push(`b.person_id = ${this.param(values, params.personId)}`);
+    if (params.skillId) where.push(`b.xp_skill_id = ${this.param(values, params.skillId)}`);
+    const whereClause = where.join(' AND ');
+
+    const totalRow = await this.querySingle<{ total: string }>(
+      `SELECT COUNT(*)::text AS total FROM student_skill_xp b WHERE ${whereClause}`,
+      values,
+    );
+
+    const q = [...values];
+    const rows = await this.queryRows<any>(
+      `SELECT
+          b.id, b.person_id AS "personId", b.xp_skill_id AS "xpSkillId",
+          COALESCE(l.name, s.slug) AS "skillName",
+          b.total_xp AS "totalXp", b.event_count AS "eventCount",
+          b.last_updated_at::text AS "lastUpdatedAt"
+        FROM student_skill_xp b
+        JOIN xp_skill s ON s.id = b.xp_skill_id
+        LEFT JOIN xp_skill_locale l ON l.xp_skill_id = s.id
+          AND l.locale_id = (SELECT id FROM locale WHERE code = 'pt' LIMIT 1)
+       WHERE ${whereClause}
+       ORDER BY b.total_xp DESC
+       LIMIT ${this.param(q, pageSize)} OFFSET ${this.param(q, offset)}`,
+      q,
+    );
+
+    const total = Number(totalRow?.total ?? 0);
+    return { data: rows, total, page, pageSize, lastPage: Math.ceil(total / pageSize) };
+  }
+
+  async listLearningTypeBalances(params: { page?: number; pageSize?: number; personId?: number; learningTypeId?: number }) {
+    const page = Math.max(Number(params.page) || 1, 1);
+    const pageSize = Math.max(Number(params.pageSize) || 20, 1);
+    const offset = (page - 1) * pageSize;
+
+    const values: unknown[] = [];
+    const where: string[] = ['1 = 1'];
+    if (params.personId) where.push(`b.person_id = ${this.param(values, params.personId)}`);
+    if (params.learningTypeId) where.push(`b.xp_learning_type_id = ${this.param(values, params.learningTypeId)}`);
+    const whereClause = where.join(' AND ');
+
+    const totalRow = await this.querySingle<{ total: string }>(
+      `SELECT COUNT(*)::text AS total FROM student_learning_type_xp b WHERE ${whereClause}`,
+      values,
+    );
+
+    const q = [...values];
+    const rows = await this.queryRows<any>(
+      `SELECT
+          b.id, b.person_id AS "personId", b.xp_learning_type_id AS "xpLearningTypeId",
+          COALESCE(l.name, t.slug) AS "learningTypeName",
+          b.total_xp AS "totalXp", b.event_count AS "eventCount",
+          b.last_updated_at::text AS "lastUpdatedAt"
+        FROM student_learning_type_xp b
+        JOIN xp_learning_type t ON t.id = b.xp_learning_type_id
+        LEFT JOIN xp_learning_type_locale l ON l.xp_learning_type_id = t.id
+          AND l.locale_id = (SELECT id FROM locale WHERE code = 'pt' LIMIT 1)
+       WHERE ${whereClause}
+       ORDER BY b.total_xp DESC
+       LIMIT ${this.param(q, pageSize)} OFFSET ${this.param(q, offset)}`,
+      q,
+    );
+
+    const total = Number(totalRow?.total ?? 0);
+    return { data: rows, total, page, pageSize, lastPage: Math.ceil(total / pageSize) };
+  }
+
+  async getPersonBalanceSummary(personId: number) {
+    const [areas, skills, learningTypes, totalRow] = await Promise.all([
+      this.queryRows<any>(
+        `SELECT b.xp_area_id AS "xpAreaId", COALESCE(l.name, a.slug) AS name, b.total_xp AS "totalXp", b.event_count AS "eventCount"
+           FROM student_area_xp b
+           JOIN xp_area a ON a.id = b.xp_area_id
+           LEFT JOIN xp_area_locale l ON l.xp_area_id = a.id AND l.locale_id = (SELECT id FROM locale WHERE code = 'pt' LIMIT 1)
+          WHERE b.person_id = $1 ORDER BY b.total_xp DESC`,
+        [personId],
+      ),
+      this.queryRows<any>(
+        `SELECT b.xp_skill_id AS "xpSkillId", COALESCE(l.name, s.slug) AS name, b.total_xp AS "totalXp", b.event_count AS "eventCount"
+           FROM student_skill_xp b
+           JOIN xp_skill s ON s.id = b.xp_skill_id
+           LEFT JOIN xp_skill_locale l ON l.xp_skill_id = s.id AND l.locale_id = (SELECT id FROM locale WHERE code = 'pt' LIMIT 1)
+          WHERE b.person_id = $1 ORDER BY b.total_xp DESC`,
+        [personId],
+      ),
+      this.queryRows<any>(
+        `SELECT b.xp_learning_type_id AS "xpLearningTypeId", COALESCE(l.name, t.slug) AS name, b.total_xp AS "totalXp", b.event_count AS "eventCount"
+           FROM student_learning_type_xp b
+           JOIN xp_learning_type t ON t.id = b.xp_learning_type_id
+           LEFT JOIN xp_learning_type_locale l ON l.xp_learning_type_id = t.id AND l.locale_id = (SELECT id FROM locale WHERE code = 'pt' LIMIT 1)
+          WHERE b.person_id = $1 ORDER BY b.total_xp DESC`,
+        [personId],
+      ),
+      this.querySingle<{ total: string }>(
+        `SELECT GREATEST(
+          (SELECT COALESCE(SUM(total_xp), 0) FROM student_area_xp WHERE person_id = $1),
+          (SELECT COALESCE(SUM(total_xp), 0) FROM student_skill_xp WHERE person_id = $1),
+          (SELECT COALESCE(SUM(total_xp), 0) FROM student_learning_type_xp WHERE person_id = $1)
+        )::text AS total`,
+        [personId],
+      ),
+    ]);
+
+    return {
+      personId,
+      totalXp: Number(totalRow?.total ?? 0),
+      areas,
+      skills,
+      learningTypes,
+    };
+  }
+
+  private param(values: unknown[], value: unknown) {
+    values.push(value);
+    return `$${values.length}`;
+  }
+
+  private async queryRows<T>(query: string, values: unknown[] = []) {
+    return this.prisma.$queryRawUnsafe<T[]>(query, ...values);
+  }
+
+  private async querySingle<T>(query: string, values: unknown[] = []) {
+    const rows = await this.prisma.$queryRawUnsafe<T[]>(query, ...values);
+    return rows[0] ?? null;
+  }
+
+  private async resolvePersonId(userId: number): Promise<number> {
+    const row = await this.querySingle<{ personId: number }>(
+      `SELECT person_id AS "personId" FROM person_user WHERE user_id = $1 LIMIT 1`,
+      [userId],
+    );
+
+    if (!row) {
+      throw new NotFoundException('No person profile found for this user');
+    }
+
+    return Number(row.personId);
+  }
+
+  async getMyBalance(userId: number) {
+    const personId = await this.resolvePersonId(userId);
+    return this.getPersonBalanceSummary(personId);
+  }
+
+  async grantSkillCardXp(userId: number, dto: GrantSkillCardXpDto) {
+    const skillCardSlug = String(dto.skillCardSlug ?? '').trim();
+
+    if (!skillCardSlug) {
+      throw new BadRequestException('Skill card slug is required');
+    }
+
+    const parsedXpEarned = Math.trunc(Number(dto.xpEarned));
+    const xpEarned = Number.isFinite(parsedXpEarned)
+      ? Math.max(1, parsedXpEarned)
+      : 1;
+    const personId = await this.resolvePersonId(userId);
+
+    const skill = await this.querySingle<{ id: number; xpAreaId: number | null }>(
+      `SELECT id, xp_area_id AS "xpAreaId" FROM xp_skill WHERE slug = $1 LIMIT 1`,
+      [skillCardSlug],
+    );
+
+    if (!skill) {
+      throw new NotFoundException('XP skill not found');
+    }
+
+    await this.prisma.$transaction(async (tx) => {
+      await tx.$executeRawUnsafe(
+        `INSERT INTO student_skill_xp (person_id, xp_skill_id, total_xp, event_count, last_updated_at, created_at, updated_at)
+         VALUES ($1, $2, $3, 1, now(), now(), now())
+         ON CONFLICT (person_id, xp_skill_id) DO UPDATE
+           SET total_xp        = student_skill_xp.total_xp + EXCLUDED.total_xp,
+               event_count     = student_skill_xp.event_count + 1,
+               last_updated_at = now(),
+               updated_at      = now()`,
+        personId,
+        skill.id,
+        xpEarned,
+      );
+
+      if (skill.xpAreaId) {
+        await tx.$executeRawUnsafe(
+          `INSERT INTO student_area_xp (person_id, xp_area_id, total_xp, event_count, last_updated_at, created_at, updated_at)
+           VALUES ($1, $2, $3, 1, now(), now(), now())
+           ON CONFLICT (person_id, xp_area_id) DO UPDATE
+             SET total_xp        = student_area_xp.total_xp + EXCLUDED.total_xp,
+                 event_count     = student_area_xp.event_count + 1,
+                 last_updated_at = now(),
+                 updated_at      = now()`,
+          personId,
+          skill.xpAreaId,
+          xpEarned,
+        );
+      }
+    });
+
+    return this.getPersonBalanceSummary(personId);
+  }
+}