feat(entitlements,campaigns): plans/quotas + campanhas, leads, lista de bloqueio

Fecha duas fases: Plans/Entitlements (agente.md secao 56-62), que tinha ficado pra trás desde o inicio, e Campanhas/Leads/Lista de Bloqueio (secao 63-71). ## Plans/Entitlements A ordem de implementacao da propria especificacao (secao 232) coloca Plans/Entitlements logo depois de PostgreSQL RLS, bem antes de FreeSWITCH — mas o build seguiu direto sem essa peca, e toda fase desde entao documentou "quota depende de Plans/Entitlements" como pendencia (EXTENSIONS.md, TRUNKS.md, AGENTS.md, QUEUES.md, agora todas atualizadas). Fechado agora porque Campanhas precisa de max_campaigns e o proximo CPS Limiter vai precisar de max_cps/max_concurrent_calls. - plans: catalogo compartilhado entre tenants (sem RLS, nao e' tenant- scoped) com todos os campos de entitlement da secao 56. Campo de limite null = "sem limite", nunca "sem plano" — tenants.plan_id e' obrigatorio, nunca null (secao 56: nao espalhar `if plan == PRO` pelo codigo). - Migration hand-escrita: cria plans, insere seed "trial", faz backfill de plan_id pros tenants ja existentes, so' depois torna NOT NULL (Postgres nao deixa NOT NULL sem default em tabela nao-vazia). - packages/entitlements (pacote novo): assertQuota/assertFeatureEnabled, erros mapeados pra 403 no DomainExceptionFilter. - Retrofit em Extensions/Trunks/Agents/Queues: contam linhas ativas e checam quota antes de criar. ## Campanhas, Leads, Lista de Bloqueio Deliberadamente so' o modelo/CRUD/maquina de estados — o motor que de fato origina chamadas (PredictiveDialerEngine, secao 72-86: dados em tempo real, EWMA, CPS distribuido, reserva atomica de lead, lock de campanha, bgapi originate, controle de abandono, retry) e' um sistema grande o suficiente pra merecer fase propria (secao 72: "nao e' so' `for lead -> originate`"). - campaigns/leads/suppression_entries (tenant-scoped, RLS). - Maquina de estados da campanha (secao 64-66): start/pause/drain/stop com tabela de transicoes validas — transicao invalida retorna 400, nunca ignora silenciosamente. Apagar bloqueado enquanto RUNNING/DRAINING. - packages/shared/src/phone.ts (secao 70): normalizacao dedicada, preparada pra E.164 completo, so' BR implementado. - Importacao CSV em batches de 1000 (secao 69): detecta duplicado (dentro do CSV + contra leads existentes), checa lista de bloqueio (importa como DO_NOT_CALL, nao descarta), retorna {total, valid, invalid, duplicates, imported, suppressed}. - Lista de bloqueio (secao 71): CRUD tenant-scoped. Verificado ponta a ponta: campanha com queueId/trunkId invalido e pacingMin > pacingMax rejeitados; CSV de 5 linhas (1 invalida, 1 duplicada, 1 bloqueada) importado corretamente; start->pause->drain->stop e transicoes invalidas todas corretas; 3a campanha rejeitada por quota (max_campaigns=2 do plano trial); 6a extensao rejeitada por quota (max_extensions=5). Suites de teste existentes (tenant-isolation, auth) atualizadas pro novo Tenant.planId obrigatorio e passando. typecheck do workspace inteiro limpo. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01X1HxY46WGU4G1zmVDNKcWw
2026-08-28 12:26:47 -03:00
parent f051fe3162
commit 7b62ad3d82
35 changed files with 1674 additions and 13 deletions
--- a/apps/api/src/campaigns/campaigns.controller.ts
+++ b/apps/api/src/campaigns/campaigns.controller.ts
@@ -0,0 +1,223 @@
+import {
+  BadRequestException,
+  Body,
+  Controller,
+  Delete,
+  Get,
+  HttpCode,
+  HttpStatus,
+  NotFoundException,
+  Param,
+  Post,
+  UseGuards,
+} from "@nestjs/common";
+import { getPrismaClient, withTenantContext, type CampaignStatus } from "@b2bcall/database";
+import { recordAuditEvent, type AccessTokenClaims } from "@b2bcall/auth";
+import { assertQuota } from "@b2bcall/entitlements";
+import { JwtAuthGuard } from "../common/guards/jwt-auth.guard";
+import { PermissionGuard } from "../common/guards/permission.guard";
+import { RequirePermission } from "../common/decorators/require-permission.decorator";
+import { CurrentUser } from "../common/decorators/current-user.decorator";
+import { CreateCampaignDto } from "./dto/create-campaign.dto";
+
+/**
+ * Transições de status válidas (agente.md secao 64-66). O motor que de fato
+ * origina chamadas em RUNNING (PredictiveDialerEngine) é uma fase à parte —
+ * aqui só a máquina de estados e o CRUD.
+ */
+const ALLOWED_TRANSITIONS: Record<string, CampaignStatus[]> = {
+  start: ["DRAFT", "READY", "PAUSED", "WAITING_SCHEDULE"],
+  pause: ["RUNNING"],
+  drain: ["RUNNING", "PAUSED"],
+  stop: ["DRAFT", "READY", "WAITING_SCHEDULE", "RUNNING", "PAUSED", "DRAINING"],
+};
+
+const TARGET_STATUS: Record<string, CampaignStatus> = {
+  start: "RUNNING",
+  pause: "PAUSED",
+  drain: "DRAINING",
+  stop: "STOPPED",
+};
+
+@UseGuards(JwtAuthGuard, PermissionGuard)
+@Controller("campaigns")
+export class CampaignsController {
+  @RequirePermission("campaigns.create")
+  @Post()
+  async create(@CurrentUser() user: AccessTokenClaims, @Body() dto: CreateCampaignDto) {
+    const prisma = getPrismaClient();
+    const tenantId = user.tenantId!;
+
+    const activeCount = await withTenantContext(prisma, tenantId, (tx) =>
+      tx.campaign.count({ where: { tenantId, deletedAt: null } }),
+    );
+    await assertQuota(tenantId, "maxCampaigns", activeCount);
+
+    const [queue, trunk] = await withTenantContext(prisma, tenantId, (tx) =>
+      Promise.all([
+        tx.queue.findFirst({ where: { id: dto.queueId, tenantId, deletedAt: null } }),
+        tx.trunk.findFirst({ where: { id: dto.trunkId, tenantId, deletedAt: null } }),
+      ]),
+    );
+    if (!queue) throw new BadRequestException("Fila nao encontrada neste tenant");
+    if (!trunk) throw new BadRequestException("Tronco nao encontrado neste tenant");
+
+    if (dto.pacingMin !== undefined && dto.pacingMax !== undefined && dto.pacingMin > dto.pacingMax) {
+      throw new BadRequestException("pacingMin nao pode ser maior que pacingMax");
+    }
+
+    const campaign = await withTenantContext(prisma, tenantId, (tx) =>
+      tx.campaign.create({
+        data: {
+          tenantId,
+          name: dto.name,
+          description: dto.description,
+          queueId: dto.queueId,
+          trunkId: dto.trunkId,
+          callerIdName: dto.callerIdName,
+          callerIdNumber: dto.callerIdNumber,
+          timezone: dto.timezone ?? "America/Sao_Paulo",
+          startDate: dto.startDate,
+          endDate: dto.endDate,
+          daysOfWeek: dto.daysOfWeek ?? [],
+          startTime: dto.startTime,
+          endTime: dto.endTime,
+          maxCps: dto.maxCps,
+          maxConcurrentCalls: dto.maxConcurrentCalls,
+          pacingInitial: dto.pacingInitial ?? 1.0,
+          pacingMin: dto.pacingMin ?? 1.0,
+          pacingMax: dto.pacingMax ?? 3.0,
+          targetAbandonRate: dto.targetAbandonRate ?? 0.03,
+          ringTimeout: dto.ringTimeout ?? 30,
+          maxAttempts: dto.maxAttempts ?? 3,
+          recordingEnabled: dto.recordingEnabled ?? false,
+          avmdEnabled: dto.avmdEnabled ?? false,
+          aiTranscriptionEnabled: dto.aiTranscriptionEnabled ?? false,
+          aiAnalysisEnabled: dto.aiAnalysisEnabled ?? false,
+        },
+      }),
+    );
+
+    await recordAuditEvent(prisma, {
+      action: "CAMPAIGN_CREATE",
+      tenantId,
+      userId: user.sub,
+      entityType: "campaign",
+      entityId: campaign.id,
+      after: { name: campaign.name },
+    });
+
+    return campaign;
+  }
+
+  @RequirePermission("campaigns.view")
+  @Get()
+  async list(@CurrentUser() user: AccessTokenClaims) {
+    const prisma = getPrismaClient();
+    const tenantId = user.tenantId!;
+    return withTenantContext(prisma, tenantId, (tx) =>
+      tx.campaign.findMany({ where: { deletedAt: null }, orderBy: { name: "asc" } }),
+    );
+  }
+
+  @RequirePermission("campaigns.view")
+  @Get(":id")
+  async get(@CurrentUser() user: AccessTokenClaims, @Param("id") id: string) {
+    const prisma = getPrismaClient();
+    const tenantId = user.tenantId!;
+    const campaign = await withTenantContext(prisma, tenantId, (tx) =>
+      tx.campaign.findFirst({ where: { id, deletedAt: null } }),
+    );
+    if (!campaign) throw new NotFoundException();
+    return campaign;
+  }
+
+  @RequirePermission("campaigns.start")
+  @Post(":id/start")
+  async start(@CurrentUser() user: AccessTokenClaims, @Param("id") id: string) {
+    return this.transition(user, id, "start", "CAMPAIGN_START");
+  }
+
+  @RequirePermission("campaigns.pause")
+  @Post(":id/pause")
+  async pause(@CurrentUser() user: AccessTokenClaims, @Param("id") id: string) {
+    return this.transition(user, id, "pause", "CAMPAIGN_PAUSE");
+  }
+
+  @RequirePermission("campaigns.stop")
+  @Post(":id/drain")
+  async drain(@CurrentUser() user: AccessTokenClaims, @Param("id") id: string) {
+    return this.transition(user, id, "drain", "CAMPAIGN_DRAIN");
+  }
+
+  @RequirePermission("campaigns.stop")
+  @Post(":id/stop")
+  async stop(@CurrentUser() user: AccessTokenClaims, @Param("id") id: string) {
+    return this.transition(user, id, "stop", "CAMPAIGN_STOP");
+  }
+
+  private async transition(
+    user: AccessTokenClaims,
+    id: string,
+    action: keyof typeof TARGET_STATUS,
+    auditAction: string,
+  ) {
+    const prisma = getPrismaClient();
+    const tenantId = user.tenantId!;
+
+    const campaign = await withTenantContext(prisma, tenantId, (tx) =>
+      tx.campaign.findFirst({ where: { id, tenantId, deletedAt: null } }),
+    );
+    if (!campaign) throw new NotFoundException();
+
+    if (!ALLOWED_TRANSITIONS[action].includes(campaign.status)) {
+      throw new BadRequestException(
+        `Nao e' possivel "${action}" uma campanha em status ${campaign.status}`,
+      );
+    }
+
+    const updated = await withTenantContext(prisma, tenantId, (tx) =>
+      tx.campaign.update({ where: { id }, data: { status: TARGET_STATUS[action] } }),
+    );
+
+    await recordAuditEvent(prisma, {
+      action: auditAction,
+      tenantId,
+      userId: user.sub,
+      entityType: "campaign",
+      entityId: id,
+      before: { status: campaign.status },
+      after: { status: updated.status },
+    });
+
+    return { status: updated.status };
+  }
+
+  @RequirePermission("campaigns.update")
+  @Delete(":id")
+  @HttpCode(HttpStatus.NO_CONTENT)
+  async remove(@CurrentUser() user: AccessTokenClaims, @Param("id") id: string) {
+    const prisma = getPrismaClient();
+    const tenantId = user.tenantId!;
+
+    const campaign = await withTenantContext(prisma, tenantId, (tx) =>
+      tx.campaign.findFirst({ where: { id, tenantId, deletedAt: null } }),
+    );
+    if (!campaign) throw new NotFoundException();
+    if (campaign.status === "RUNNING" || campaign.status === "DRAINING") {
+      throw new BadRequestException("Pare a campanha antes de apaga-la");
+    }
+
+    await withTenantContext(prisma, tenantId, (tx) =>
+      tx.campaign.update({ where: { id }, data: { deletedAt: new Date() } }),
+    );
+
+    await recordAuditEvent(prisma, {
+      action: "CAMPAIGN_DELETE",
+      tenantId,
+      userId: user.sub,
+      entityType: "campaign",
+      entityId: id,
+    });
+  }
+}
--- a/apps/api/src/campaigns/campaigns.module.ts
+++ b/apps/api/src/campaigns/campaigns.module.ts
@@ -0,0 +1,7 @@
+import { Module } from "@nestjs/common";
+import { CampaignsController } from "./campaigns.controller";
+
+@Module({
+  controllers: [CampaignsController],
+})
+export class CampaignsModule {}
--- a/apps/api/src/campaigns/dto/create-campaign.dto.ts
+++ b/apps/api/src/campaigns/dto/create-campaign.dto.ts
@@ -0,0 +1,138 @@
+import {
+  ArrayMaxSize,
+  IsArray,
+  IsBoolean,
+  IsDateString,
+  IsInt,
+  IsNumber,
+  IsOptional,
+  IsString,
+  IsUUID,
+  Matches,
+  Max,
+  MaxLength,
+  Min,
+} from "class-validator";
+
+export class CreateCampaignDto {
+  @IsString()
+  @MaxLength(120)
+  name!: string;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(500)
+  description?: string;
+
+  @IsUUID()
+  queueId!: string;
+
+  @IsUUID()
+  trunkId!: string;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(80)
+  callerIdName?: string;
+
+  @IsOptional()
+  @IsString()
+  @Matches(/^[0-9]{2,20}$/)
+  callerIdNumber?: string;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(64)
+  timezone?: string;
+
+  @IsOptional()
+  @IsDateString()
+  startDate?: string;
+
+  @IsOptional()
+  @IsDateString()
+  endDate?: string;
+
+  // 1=segunda ... 7=domingo (ISO-8601).
+  @IsOptional()
+  @IsArray()
+  @ArrayMaxSize(7)
+  @IsInt({ each: true })
+  @Min(1, { each: true })
+  @Max(7, { each: true })
+  daysOfWeek?: number[];
+
+  @IsOptional()
+  @IsString()
+  @Matches(/^([01]\d|2[0-3]):[0-5]\d$/)
+  startTime?: string;
+
+  @IsOptional()
+  @IsString()
+  @Matches(/^([01]\d|2[0-3]):[0-5]\d$/)
+  endTime?: string;
+
+  @IsOptional()
+  @IsInt()
+  @Min(1)
+  @Max(1000)
+  maxCps?: number;
+
+  @IsOptional()
+  @IsInt()
+  @Min(1)
+  @Max(100000)
+  maxConcurrentCalls?: number;
+
+  @IsOptional()
+  @IsNumber()
+  @Min(0.1)
+  @Max(10)
+  pacingInitial?: number;
+
+  @IsOptional()
+  @IsNumber()
+  @Min(0.1)
+  @Max(10)
+  pacingMin?: number;
+
+  @IsOptional()
+  @IsNumber()
+  @Min(0.1)
+  @Max(10)
+  pacingMax?: number;
+
+  @IsOptional()
+  @IsNumber()
+  @Min(0)
+  @Max(1)
+  targetAbandonRate?: number;
+
+  @IsOptional()
+  @IsInt()
+  @Min(5)
+  @Max(120)
+  ringTimeout?: number;
+
+  @IsOptional()
+  @IsInt()
+  @Min(1)
+  @Max(20)
+  maxAttempts?: number;
+
+  @IsOptional()
+  @IsBoolean()
+  recordingEnabled?: boolean;
+
+  @IsOptional()
+  @IsBoolean()
+  avmdEnabled?: boolean;
+
+  @IsOptional()
+  @IsBoolean()
+  aiTranscriptionEnabled?: boolean;
+
+  @IsOptional()
+  @IsBoolean()
+  aiAnalysisEnabled?: boolean;
+}