From 6971037608092ddf715f031e825e17be83a4593f Mon Sep 17 00:00:00 2001 From: "leonardo.santos" Date: Thu, 30 Jul 2026 14:17:50 -0300 Subject: [PATCH 1/2] fix(gamificacao): separa contribuicao de comunidade de progresso de trilha MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit O selo "Primeira Missao" (e afins) contava qualquer Submission com status APPROVED, incluindo test-out de marco de trilha (0 XP, sem nenhuma ajuda real). Isso concedia o selo de "contribuicao" so por pular uma prova. - nova coluna Submission.contributionKind (COMMUNITY_ACTIVITY | TRACK_PROGRESS), formalizando o que antes so existia implicitamente via trackItemId nulo - badge-evaluator so conta submissoes COMMUNITY_ACTIVITY aprovadas e isTestOut=false pros selos de contribuicao - migracao revoga "Primeira Missao"/"Colaborador"/"Herói da Comunidade" dos 5 perfis que nao tinham contribuicao real por tras da concessao - novo endpoint publico GET /gamification-profiles/:id/course-reviews pra timeline do perfil mostrar avaliacoes de curso como categoria propria Co-Authored-By: Claude Sonnet 5 --- docs/data-model.md | 14 ++++- src/badges/badge-evaluator.service.ts | 16 ++++- ...424960820-AddSubmissionContributionKind.ts | 59 +++++++++++++++++++ .../gamification-profiles.controller.ts | 40 +++++++++++++ .../submission-contribution-kind.enum.ts | 8 +++ src/submissions/domain/submission.ts | 8 +++ .../relational/entities/submission.entity.ts | 11 ++++ .../relational/mappers/submission.mapper.ts | 2 + .../submissions.controller.spec.ts | 2 + src/submissions/submissions.service.spec.ts | 2 + src/submissions/submissions.service.ts | 5 ++ 11 files changed, 162 insertions(+), 5 deletions(-) create mode 100644 src/database/migrations/1785424960820-AddSubmissionContributionKind.ts create mode 100644 src/submissions/domain/submission-contribution-kind.enum.ts diff --git a/docs/data-model.md b/docs/data-model.md index 121ccee..3a761ba 100644 --- a/docs/data-model.md +++ b/docs/data-model.md @@ -93,6 +93,8 @@ erDiagram int reviewerId FK "Nullable -> User" datetime reviewedAt "Nullable" uuid trackItemId FK "Nullable - marco de trilha vinculado" + boolean isTestOut "Default: false - pulou o marco autodeclarando dominio" + enum contributionKind "COMMUNITY_ACTIVITY | TRACK_PROGRESS" datetime createdAt datetime updatedAt } @@ -400,13 +402,20 @@ Atividades pré-mapeadas disponíveis para submissão. --- ### `Submission` (Solicitação de Pontos do Usuário) -Quando o usuário executa uma `Activity` e solicita reconhecimento. +Quando o usuário executa uma `Activity` e solicita reconhecimento. A mesma +tabela também registra provas/test-out de marcos de trilha (`trackItemId` +preenchido) — o pipeline de moderação é compartilhado, mas as duas coisas +são semanticamente diferentes (ver `contributionKind` abaixo). - `description` (String, Nullable) — markdown sanitizado (max 2000 chars); aceita apenas ASCII imprimível + Latin Extended (sem emojis/Unicode especial) - `awardedXp` (Int) — XP concedido (geralmente herda de `Activity.fixedReward`, mas o moderador pode sobrescrever) - `reviewerId` (Int, FK -> User) — ID do moderador que revisou - `trackItemId` (UUID, FK -> TrackItem, Nullable) — quando a submissão é feita no contexto de um marco de trilha -- Ao **aprovar**: gera `Transaction(XP_REWARD)` para o submitter, credita XP no perfil, gera `Transaction(AUDITOR_REWARD)` para o moderador +- `isTestOut` (Boolean) — `true` quando o usuário pulou o marco autodeclarando domínio (nunca gera XP, sempre `status = APPROVED` imediatamente, sem moderação) +- `contributionKind` (Enum `SubmissionContributionKind`) — formaliza a distinção que antes só existia implicitamente pela nulidade de `trackItemId`: + - `COMMUNITY_ACTIVITY` — contribuição real à comunidade (`trackItemId` nulo). Conta para selos de contribuição (ex: "Primeira Missão") e aparece na categoria "Voluntariado" do perfil público. + - `TRACK_PROGRESS` — progresso pessoal de uma trilha de aprendizado (prova aprovada ou test-out). XP é para o próprio usuário, **não** é contribuição para a comunidade — nunca deve contar para selos de contribuição, mesmo quando `status = APPROVED`. +- Ao **aprovar** uma submissão `COMMUNITY_ACTIVITY`: gera `Transaction(XP_REWARD)` para o submitter, credita XP no perfil, gera `Transaction(AUDITOR_REWARD)` para o moderador --- @@ -442,6 +451,7 @@ Motor financeiro dos pontos. Toda mutação no perfil gera uma Transaction. { "type": "total_xp", "threshold": 500 } { "type": "monthly_ranking_top", "threshold": 3 } ``` + - `submissions_approved` conta **apenas** `Submission` com `status = APPROVED`, `isTestOut = false` **e** `contributionKind = COMMUNITY_ACTIVITY` (`badge-evaluator.service.ts`). Test-out e provas de trilha aprovadas nunca contam para esse critério — não são contribuição para a comunidade, mesmo que gerem XP pessoal. --- diff --git a/src/badges/badge-evaluator.service.ts b/src/badges/badge-evaluator.service.ts index 5280965..31681ad 100644 --- a/src/badges/badge-evaluator.service.ts +++ b/src/badges/badge-evaluator.service.ts @@ -6,6 +6,7 @@ import { GamificationProfileBadgeRepository } from './infrastructure/persistence import { BadgeCriteriaTypeEnum } from './domain/badge-criteria-type.enum'; import { SubmissionEntity } from '../submissions/infrastructure/persistence/relational/entities/submission.entity'; import { SubmissionStatus } from '../submissions/domain/submission-status.enum'; +import { SubmissionContributionKind } from '../submissions/domain/submission-contribution-kind.enum'; import { TransactionEntity } from '../transactions/infrastructure/persistence/relational/entities/transaction.entity'; import { TransactionCategoryEnum } from '../transactions/domain/transaction-category.enum'; import { GamificationProfileEntity } from '../gamification-profiles/infrastructure/persistence/relational/entities/gamification-profile.entity'; @@ -89,13 +90,22 @@ export class BadgeEvaluatorService { } } + // Só conta submissões que são contribuição real à comunidade — nunca + // progresso pessoal de trilha (nem prova aprovada nem test-out), mesmo que + // status seja APPROVED. Um test-out chega a criar uma submission APPROVED + // com 0 XP; sem esse filtro, pular uma prova já "conta" como contribuição. private async checkSubmissionsApproved( profileId: string, threshold: number, ): Promise { - const count = await this.dataSource - .getRepository(SubmissionEntity) - .count({ where: { profileId, status: SubmissionStatus.APPROVED } }); + const count = await this.dataSource.getRepository(SubmissionEntity).count({ + where: { + profileId, + status: SubmissionStatus.APPROVED, + isTestOut: false, + contributionKind: SubmissionContributionKind.COMMUNITY_ACTIVITY, + }, + }); return count >= threshold; } diff --git a/src/database/migrations/1785424960820-AddSubmissionContributionKind.ts b/src/database/migrations/1785424960820-AddSubmissionContributionKind.ts new file mode 100644 index 0000000..db4959e --- /dev/null +++ b/src/database/migrations/1785424960820-AddSubmissionContributionKind.ts @@ -0,0 +1,59 @@ +import { MigrationInterface, QueryRunner } from 'typeorm'; + +export class AddSubmissionContributionKind1785424960820 + implements MigrationInterface +{ + name = 'AddSubmissionContributionKind1785424960820'; + + public async up(queryRunner: QueryRunner): Promise { + await queryRunner.query( + `CREATE TYPE "public"."submission_contributionkind_enum" AS ENUM('COMMUNITY_ACTIVITY', 'TRACK_PROGRESS')`, + ); + await queryRunner.query( + `ALTER TABLE "submission" ADD "contributionKind" "public"."submission_contributionkind_enum"`, + ); + + // Backfill: até aqui, a única forma de saber o tipo era a nulidade de + // trackItemId — formalizamos isso como coluna explícita para não + // depender mais dessa inferência implícita em regras de negócio. + await queryRunner.query( + `UPDATE "submission" SET "contributionKind" = CASE WHEN "trackItemId" IS NULL THEN 'COMMUNITY_ACTIVITY' ELSE 'TRACK_PROGRESS' END`, + ); + + await queryRunner.query( + `ALTER TABLE "submission" ALTER COLUMN "contributionKind" SET NOT NULL`, + ); + await queryRunner.query( + `ALTER TABLE "submission" ALTER COLUMN "contributionKind" SET DEFAULT 'COMMUNITY_ACTIVITY'`, + ); + + // Limpeza: o selo "Primeira Missão" (e por extensão "Colaborador" / + // "Herói da Comunidade") contava qualquer submission com status + // APPROVED, incluindo test-out de marcos de trilha (0 XP, não é + // contribuição). Revoga concessões que não têm nenhuma submissão real + // de comunidade aprovada por trás — usuários voltam a poder ganhá-lo + // legitimamente na próxima avaliação de moderação. + await queryRunner.query(` + DELETE FROM "gamification_profile_badge" gpb + USING "badge" b + WHERE gpb."badgeId" = b.id + AND b.name IN ('Primeira Missão', 'Colaborador', 'Herói da Comunidade') + AND ( + SELECT COUNT(*) FROM "submission" s + WHERE s."profileId" = gpb."profileId" + AND s.status = 'APPROVED' + AND s."isTestOut" = false + AND s."contributionKind" = 'COMMUNITY_ACTIVITY' + ) < (b."criteriaConfig"->>'threshold')::int + `); + } + + public async down(queryRunner: QueryRunner): Promise { + await queryRunner.query( + `ALTER TABLE "submission" DROP COLUMN "contributionKind"`, + ); + await queryRunner.query( + `DROP TYPE "public"."submission_contributionkind_enum"`, + ); + } +} diff --git a/src/gamification-profiles/gamification-profiles.controller.ts b/src/gamification-profiles/gamification-profiles.controller.ts index 4d17d67..1c67d1f 100644 --- a/src/gamification-profiles/gamification-profiles.controller.ts +++ b/src/gamification-profiles/gamification-profiles.controller.ts @@ -38,6 +38,9 @@ import { FindAllGamificationProfilesDto } from './dto/find-all-gamification-prof import { UpdateMyGamificationProfileDto } from './dto/update-my-gamification-profile.dto'; import { SubmissionRepository } from '../submissions/infrastructure/persistence/submission.repository'; import { Submission } from '../submissions/domain/submission'; +import { InjectDataSource } from '@nestjs/typeorm'; +import { DataSource } from 'typeorm'; +import { CourseReviewEntity } from '../course-reviews/infrastructure/persistence/relational/entities/course-review.entity'; @ApiTags('Gamification Profiles') @Controller({ @@ -48,6 +51,7 @@ export class GamificationProfilesController { constructor( private readonly gamificationProfilesService: GamificationProfilesService, private readonly submissionRepository: SubmissionRepository, + @InjectDataSource() private readonly dataSource: DataSource, ) {} @Post() @@ -214,6 +218,42 @@ export class GamificationProfilesController { ); } + // Feed enxuto de avaliações de curso feitas pelo perfil, pra timeline + // pública mostrar como categoria própria e discreta ("avaliou o curso X"). + // Consulta direto via DataSource (padrão já usado em profile-portfolio) + // pra não criar uma dependência de módulo circular com CourseReviewsModule + // (que já depende de GamificationProfilesModule). + @Get(':id/course-reviews') + @ApiParam({ + name: 'id', + type: String, + required: true, + }) + async findCourseReviews(@Param('id') id: string) { + const rows = await this.dataSource + .getRepository(CourseReviewEntity) + .createQueryBuilder('review') + .innerJoin('review.course', 'course') + .select([ + 'review.id AS id', + 'review.courseId AS "courseId"', + 'course.title AS "courseTitle"', + 'review.rating AS rating', + 'review.createdAt AS "createdAt"', + ]) + .where('review.profileId = :id', { id }) + .orderBy('review.createdAt', 'DESC') + .getRawMany(); + + return rows.map((r) => ({ + id: r.id, + courseId: r.courseId, + courseTitle: r.courseTitle, + rating: Number(r.rating), + createdAt: r.createdAt, + })); + } + @Post(':id/penalty') @ApiBearerAuth() @UseGuards(AuthGuard('jwt'), RolesGuard) diff --git a/src/submissions/domain/submission-contribution-kind.enum.ts b/src/submissions/domain/submission-contribution-kind.enum.ts new file mode 100644 index 0000000..ca375fe --- /dev/null +++ b/src/submissions/domain/submission-contribution-kind.enum.ts @@ -0,0 +1,8 @@ +export enum SubmissionContributionKind { + // Ajuda real prestada à comunidade (atividade de voluntariado), conta para + // selos de "contribuição" e para o extrato público de contribuições. + COMMUNITY_ACTIVITY = 'COMMUNITY_ACTIVITY', + // Marco de trilha de aprendizado (prova ou test-out) — XP pessoal, não é + // contribuição para a comunidade e não deve contar para selos desse tipo. + TRACK_PROGRESS = 'TRACK_PROGRESS', +} diff --git a/src/submissions/domain/submission.ts b/src/submissions/domain/submission.ts index bc45fc3..fc90a10 100644 --- a/src/submissions/domain/submission.ts +++ b/src/submissions/domain/submission.ts @@ -1,5 +1,6 @@ import { ApiProperty } from '@nestjs/swagger'; import { SubmissionStatus } from './submission-status.enum'; +import { SubmissionContributionKind } from './submission-contribution-kind.enum'; import { EffortLevel } from '../../activities/domain/effort-level.enum'; export class Submission { @@ -36,6 +37,13 @@ export class Submission { }) isTestOut: boolean; + @ApiProperty({ + enum: SubmissionContributionKind, + description: + 'Se é uma contribuição real à comunidade (COMMUNITY_ACTIVITY) ou progresso pessoal de trilha (TRACK_PROGRESS)', + }) + contributionKind: SubmissionContributionKind; + @ApiProperty({ type: String, nullable: true, diff --git a/src/submissions/infrastructure/persistence/relational/entities/submission.entity.ts b/src/submissions/infrastructure/persistence/relational/entities/submission.entity.ts index f216e94..3507c18 100644 --- a/src/submissions/infrastructure/persistence/relational/entities/submission.entity.ts +++ b/src/submissions/infrastructure/persistence/relational/entities/submission.entity.ts @@ -9,6 +9,7 @@ import { } from 'typeorm'; import { EntityRelationalHelper } from '../../../../../utils/relational-entity-helper'; import { SubmissionStatus } from '../../../../domain/submission-status.enum'; +import { SubmissionContributionKind } from '../../../../domain/submission-contribution-kind.enum'; import { GamificationProfileEntity } from '../../../../../gamification-profiles/infrastructure/persistence/relational/entities/gamification-profile.entity'; import { ActivityEntity } from '../../../../../activities/infrastructure/persistence/relational/entities/activity.entity'; import { UserEntity } from '../../../../../users/infrastructure/persistence/relational/entities/user.entity'; @@ -46,6 +47,16 @@ export class SubmissionEntity extends EntityRelationalHelper { @Column({ type: 'boolean', default: false }) isTestOut: boolean; + // Distingue contribuição real à comunidade de progresso pessoal de trilha — + // não pode ser inferido só pela nulidade de trackItemId em regras de + // negócio (selo "Primeira Missão" já contou test-out por isso). + @Column({ + type: 'enum', + enum: SubmissionContributionKind, + default: SubmissionContributionKind.COMMUNITY_ACTIVITY, + }) + contributionKind: SubmissionContributionKind; + @Column({ type: 'varchar', nullable: true, default: null }) proofUrl: string | null; diff --git a/src/submissions/infrastructure/persistence/relational/mappers/submission.mapper.ts b/src/submissions/infrastructure/persistence/relational/mappers/submission.mapper.ts index bc73f11..98c4366 100644 --- a/src/submissions/infrastructure/persistence/relational/mappers/submission.mapper.ts +++ b/src/submissions/infrastructure/persistence/relational/mappers/submission.mapper.ts @@ -9,6 +9,7 @@ export class SubmissionMapper { domainEntity.activityId = raw.activityId; domainEntity.trackItemId = raw.trackItemId; domainEntity.isTestOut = raw.isTestOut; + domainEntity.contributionKind = raw.contributionKind; domainEntity.proofUrl = raw.proofUrl; domainEntity.description = raw.description; domainEntity.customTitle = raw.customTitle; @@ -33,6 +34,7 @@ export class SubmissionMapper { persistenceEntity.activityId = domainEntity.activityId; persistenceEntity.trackItemId = domainEntity.trackItemId; persistenceEntity.isTestOut = domainEntity.isTestOut; + persistenceEntity.contributionKind = domainEntity.contributionKind; persistenceEntity.proofUrl = domainEntity.proofUrl; persistenceEntity.description = domainEntity.description; persistenceEntity.customTitle = domainEntity.customTitle; diff --git a/src/submissions/submissions.controller.spec.ts b/src/submissions/submissions.controller.spec.ts index cfe3761..7257832 100644 --- a/src/submissions/submissions.controller.spec.ts +++ b/src/submissions/submissions.controller.spec.ts @@ -3,6 +3,7 @@ import { SubmissionsController } from './submissions.controller'; import { SubmissionsService } from './submissions.service'; import { Submission } from './domain/submission'; import { SubmissionStatus } from './domain/submission-status.enum'; +import { SubmissionContributionKind } from './domain/submission-contribution-kind.enum'; import { CreateSubmissionDto } from './dto/create-submission.dto'; import { UpdateSubmissionDto } from './dto/update-submission.dto'; import { FindAllSubmissionsDto } from './dto/find-all-submissions.dto'; @@ -16,6 +17,7 @@ const mockSubmission: Submission = { activityId: 'activity-uuid-0001', trackItemId: null, isTestOut: false, + contributionKind: SubmissionContributionKind.COMMUNITY_ACTIVITY, proofUrl: null, description: null, customTitle: null, diff --git a/src/submissions/submissions.service.spec.ts b/src/submissions/submissions.service.spec.ts index 987b9c4..cc2920e 100644 --- a/src/submissions/submissions.service.spec.ts +++ b/src/submissions/submissions.service.spec.ts @@ -15,6 +15,7 @@ import { LearningTracksService } from '../learning-tracks/learning-tracks.servic import { AuditLogsService } from '../audit-logs/audit-logs.service'; import { Submission } from './domain/submission'; import { SubmissionStatus } from './domain/submission-status.enum'; +import { SubmissionContributionKind } from './domain/submission-contribution-kind.enum'; import { GamificationProfile } from '../gamification-profiles/domain/gamification-profile'; import { Activity } from '../activities/domain/activity'; import { EffortLevel } from '../activities/domain/effort-level.enum'; @@ -101,6 +102,7 @@ function makeSubmission(overrides: Partial = {}): Submission { activityId: 'activity-1', trackItemId: null, isTestOut: false, + contributionKind: SubmissionContributionKind.COMMUNITY_ACTIVITY, proofUrl: null, description: null, customTitle: null, diff --git a/src/submissions/submissions.service.ts b/src/submissions/submissions.service.ts index e97b72a..99f6a94 100644 --- a/src/submissions/submissions.service.ts +++ b/src/submissions/submissions.service.ts @@ -16,6 +16,7 @@ import { SubmissionRepository } from './infrastructure/persistence/submission.re import { IPaginationOptions } from '../utils/types/pagination-options'; import { Submission } from './domain/submission'; import { SubmissionStatus } from './domain/submission-status.enum'; +import { SubmissionContributionKind } from './domain/submission-contribution-kind.enum'; import { GamificationProfilesService } from '../gamification-profiles/gamification-profiles.service'; import { ActivitiesService } from '../activities/activities.service'; import { BadgeEvaluatorService } from '../badges/badge-evaluator.service'; @@ -222,6 +223,9 @@ export class SubmissionsService { activityId: activity.id, trackItemId: createSubmissionDto.trackItemId ?? null, isTestOut, + contributionKind: trackItem + ? SubmissionContributionKind.TRACK_PROGRESS + : SubmissionContributionKind.COMMUNITY_ACTIVITY, proofUrl: createSubmissionDto.proofUrl ?? null, description: createSubmissionDto.description ?? null, customTitle: createSubmissionDto.customTitle ?? null, @@ -737,6 +741,7 @@ export class SubmissionsService { activityId: activity.id, trackItemId: null, isTestOut: false, + contributionKind: SubmissionContributionKind.COMMUNITY_ACTIVITY, proofUrl: null, description: null, customTitle: null, From 0472e4001a5b82a2c0e94f1fa4272ceea5376005 Mon Sep 17 00:00:00 2001 From: "leonardo.santos" Date: Thu, 30 Jul 2026 14:21:28 -0300 Subject: [PATCH 2/2] fix(migration): cast explicito pro enum contributionKind no backfill CI pegou: Postgres nao faz cast implicito de texto pra enum num UPDATE ... CASE, mesmo com os literais batendo com os valores do enum. Co-Authored-By: Claude Sonnet 5 --- .../migrations/1785424960820-AddSubmissionContributionKind.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/database/migrations/1785424960820-AddSubmissionContributionKind.ts b/src/database/migrations/1785424960820-AddSubmissionContributionKind.ts index db4959e..ed86ca3 100644 --- a/src/database/migrations/1785424960820-AddSubmissionContributionKind.ts +++ b/src/database/migrations/1785424960820-AddSubmissionContributionKind.ts @@ -17,7 +17,7 @@ export class AddSubmissionContributionKind1785424960820 // trackItemId — formalizamos isso como coluna explícita para não // depender mais dessa inferência implícita em regras de negócio. await queryRunner.query( - `UPDATE "submission" SET "contributionKind" = CASE WHEN "trackItemId" IS NULL THEN 'COMMUNITY_ACTIVITY' ELSE 'TRACK_PROGRESS' END`, + `UPDATE "submission" SET "contributionKind" = (CASE WHEN "trackItemId" IS NULL THEN 'COMMUNITY_ACTIVITY' ELSE 'TRACK_PROGRESS' END)::"public"."submission_contributionkind_enum"`, ); await queryRunner.query(