SeConectai_Vendas/README.md

SeConectai Vendas

CRM/controle de vendas multi-tenant. Um painel master (dono da plataforma) administra tenants (clientes), que por sua vez cadastram seus próprios clientes ("customers"), produtos/serviços e vendas.

Stack: Node.js 20 + TypeScript, NestJS, PostgreSQL 16 + Prisma, Redis, Docker/Docker Compose. Multi-tenancy via banco único, isolado por tenant_id + Row Level Security (RLS) do Postgres.

Subindo o ambiente do zero

1. Copie o arquivo de variáveis de ambiente e ajuste se necessário:

   cp .env.example .env
   

2. Suba os containers (Postgres, Redis e a API com hot-reload em modo dev):

   docker compose up
   

   Isso builda a imagem app (stage dev), sobe postgres e redis com healthcheck, e só inicia a API depois que as duas dependências estiverem saudáveis. docker-compose.override.yml é aplicado automaticamente e monta o código-fonte local no container, então alterações em src/ reiniciam a API sozinhas (npm run dev / nest start --watch). O mesmo docker compose up já sobe o serviço worker (motor de alertas — ver seção própria abaixo) lado a lado com a API.

3. Rode as migrations do Prisma (tabelas, enums, índices) e a migration manual de RLS/views/checks:

   docker compose exec app npx prisma migrate deploy
   

   Em desenvolvimento, para criar uma nova migration a partir de mudanças no schema.prisma:

   docker compose exec app npx prisma migrate dev
   

4. Confirme que a API está de pé:

   curl http://localhost:3000/health
   

   Deve retornar 200 com {"status":"ok","database":"up",...}.

Rodando sem Docker (opcional)

Requer Node.js 20+, um Postgres 16 e um Redis acessíveis localmente.

npm install
npm run prisma:generate
npm run prisma:migrate
npm run dev

Variáveis de ambiente

Veja .env.example — todas as chaves usadas pela aplicação e pelo docker-compose.yml (credenciais do Postgres, DATABASE_URL e variantes, Redis, JWT_SECRET e demais parâmetros de autenticação) estão documentadas lá.

Autenticação

src/modules/auth/ implementa login/refresh/logout/reset de senha para os dois tipos de usuário:

• POST /auth/master/login e POST /auth/tenant/login — e-mail+senha → access token (JWT, 15 min por padrão) + refresh token opaco (rotacionado a cada uso, guardado só como hash sha256 em auth_refresh_tokens).
• POST /auth/refresh — rotaciona o refresh token; reuso de um token já rotacionado é tratado como indício de roubo e revoga toda a família de tokens do usuário.
• POST /auth/logout — revoga o refresh token informado.
• POST /auth/password/forgot / POST /auth/password/reset — gera token de reset (hash, expiração curta, uso único); por ora o token é só logado no console (envio de e-mail real é da Etapa 4).
• Senhas com argon2id (parâmetros OWASP 2024). Bloqueio de força bruta por e-mail após LOGIN_MAX_ATTEMPTS falhas em LOGIN_LOCKOUT_WINDOW_MINUTES (tabela login_attempts), mais um rate limit por IP nas rotas de login (@nestjs/throttler).
• JwtAuthGuard, MasterGuard, TenantGuard, RolesGuard (+ @Roles(...)) e o decorator @CurrentUser() — ver GET /auth/me, GET /auth/master/admins e GET /auth/tenant/users em auth.controller.ts para exemplos de uso de cada guard.

Migrations e RLS

O schema em prisma/schema.prisma é a tradução 1:1 de Etapas/seconectai-vendas-schema.sql (fonte de verdade). Construtos que o Prisma DSL não expressa nativamente — views de dashboard, CHECK constraints e as CREATE POLICY de Row Level Security — vivem numa migration manual em prisma/migrations/<timestamp>_rls_views_constraints/, aplicada junto com as migrations geradas automaticamente pelo Prisma (prisma migrate deploy roda todas em ordem).

Uma segunda migration manual (prisma/migrations/20260813120000_auth_app_roles/) cria duas roles de banco usadas em runtime:

• app_master (LOGIN + BYPASSRLS, conectada via DATABASE_URL_MASTER) — usada pelo painel master, que precisa enxergar dados de todos os tenants.
• app_tenant (LOGIN comum, sem BYPASSRLS, conectada via DATABASE_URL_TENANT) — usada por toda query autenticada como tenant_user.

Isso é necessário porque a role de DATABASE_URL (seconectai, dona das tabelas) é a superuser bootstrap do Postgres criada pelo POSTGRES_USER do docker-compose — e superusers sempre ignoram Row Level Security, mesmo com as policies criadas. Sem uma role não-superuser dedicada, o isolamento por tenant seria só decorativo.

Por request, o TenantRlsInterceptor (registrado globalmente) identifica requests autenticadas como tenant_user e, via TenantContextService, abre uma transação na conexão app_tenant executando:

SELECT set_config('app.current_tenant_id', '<uuid-do-tenant-logado>', true); -- equivalente a SET LOCAL

sempre usando o tenant_id do JWT da sessão — nunca um valor vindo de input do usuário (body/query). Serviços que precisam rodar dentro desse contexto usam TenantContextService.getTx() (ver AuthController.listTenantUsers como exemplo). Requests master usam PrismaMasterService (conexão app_master, sem passar pelas policies).

Motor de alertas (worker)

O disparo automatizado de alertas (mensalidade do tenant, cobrança de parcelas do customer) roda num processo separado do processo web:

• src/main.ts (processo app) — só HTTP. Não importa ScheduleModule nem processa nenhuma fila.
• src/worker.ts (processo worker) — sem HTTP. Sobe via NestFactory.createApplicationContext(WorkerModule), que inicializa os dois crons diários (AlertSchedulerService, @nestjs/schedule) e os dois processors do BullMQ (MensalidadeProcessor/CobrancaProcessor, filas alertas-mensalidade/alertas-cobranca no Redis já usado pelo docker-compose).

Essa separação existe para poder escalar os dois processos de forma independente sem duplicar o disparo do cron: se o app rodar em várias réplicas (comum atrás de um load balancer), um @Cron() registrado nele dispararia o mesmo job uma vez por réplica. Como os crons vivem só no worker, escalar worker (docker compose up --scale worker=3) paraleliza o processamento das filas, não a geração dos jobs.

docker compose up já sobe os dois processos (serviço worker no docker-compose.yml/docker-compose.override.yml, mesma imagem do app, command diferente: node dist/worker em produção, npm run worker:dev em desenvolvimento). Para rodar só o worker manualmente:

docker compose up worker

Horário dos crons, antecedência do alerta e política de retry são configuráveis via ALERT_CRON_MENSALIDADE/ALERT_CRON_COBRANCA, ALERT_DIAS_ANTECEDENCIA_MENSALIDADE/ALERT_DIAS_ANTECEDENCIA_COBRANCA e ALERT_JOB_MAX_ATTEMPTS/ALERT_JOB_BACKOFF_MS (ver .env.example).

Scripts

Script	Descrição
npm run dev	Inicia a API em modo watch
npm run build	Compila TypeScript para dist/
npm run start:prod	Roda a build de produção (dist/main.js)
npm run worker:dev	Inicia o worker de alertas em modo watch
npm run worker:prod	Roda a build de produção do worker (dist/worker.js)
npm run lint	ESLint (com --fix)
npm run test	Testes unitários (Jest)
npm run test:e2e	Testes end-to-end (Jest + Supertest)
npm run prisma:generate	Gera o Prisma Client
npm run prisma:migrate	Cria/aplica migration em desenvolvimento
npm run prisma:migrate:deploy	Aplica migrations pendentes (produção/CI)
npm run prisma:studio	Abre o Prisma Studio

Estrutura do projeto

src/
├── main.ts           # processo web (HTTP)
├── worker.ts          # processo worker (crons + filas BullMQ, sem HTTP)
├── app.module.ts       # módulos do processo web
├── config/            # ConfigModule, validação de env, PrismaService/PrismaMasterService/
│                      # PrismaTenantService, TenantContextService (mecanismo de RLS por request)
├── worker/            # WorkerModule, AlertSchedulerService (crons), processors do BullMQ
└── modules/
    ├── health/        # GET /health
    ├── auth/          # login/refresh/logout/reset, guards, decorators, JwtStrategy
    └── alerts/         # CRUD de alert_templates, GET .../alertas/logs, resolver de fallback
                        # e placeholders (usado pelo módulo web e pelo worker)
prisma/
├── schema.prisma
└── migrations/
Etapas/                # Prompts e controle de progresso do build faseado

Progresso do build

Este projeto é construído em etapas. O estado oficial de cada etapa (o que já foi concluído, o que falta, decisões tomadas) fica em Etapas/09-controle-de-progresso.md.