SeConectai_Vendas/Etapas/01-setup-projeto.md

Etapa 1/8 — Setup do Projeto

Contexto do projeto

Estou construindo o SeConectai Vendas: um CRM/controle de vendas multi-tenant. Existe um painel master (eu, dono da plataforma, que vendo o acesso ao sistema) e painéis de tenant (meus clientes, que usam o sistema para cadastrar os próprios clientes/vendas).

Stack definida:

• Node.js 20+ / TypeScript
• NestJS (organizado em módulos por domínio)
• PostgreSQL 16 + Prisma ORM
• Redis (usado a partir de uma etapa futura, mas já deve subir no compose)
• Docker + Docker Compose para todo o ambiente (dev e produção)
• Multi-tenancy: banco único, isolamento por tenant_id + Row Level Security (RLS) do Postgres

Esta é a Etapa 1 de 8 de um build faseado. Cada etapa será entregue separadamente. Nesta etapa, quero apenas a fundação do projeto — nenhuma feature de negócio ainda.

Objetivo desta etapa

Criar a estrutura base do repositório, ambiente Docker funcional, conexão com banco de dados via Prisma, e o schema inicial do banco já migrado.

Tarefas

1. Estrutura do projeto NestJS

   • Criar projeto NestJS em TypeScript com estrutura modular: src/modules/<dominio>/... (os domínios virão nas próximas etapas — por ora, criar só src/modules/health/ com um endpoint GET /health que retorna status da API e status da conexão com o banco).
   • Configurar ESLint + Prettier com regras razoáveis para TypeScript.
   • Configurar variáveis de ambiente via .env (usar @nestjs/config), com um .env.example documentando todas as chaves necessárias.

2. Docker Compose

   • Criar docker-compose.yml com os serviços:
     • app (build a partir de um Dockerfile multi-stage — stage de build e stage de produção enxuto)
     • postgres (Postgres 16, volume nomeado para persistência, healthcheck)
     • redis (Redis 7, volume nomeado, healthcheck) — não será usado ainda, mas deixar disponível
   • Criar docker-compose.override.yml (ou perfil dev) com hot-reload do backend para desenvolvimento local.
   • Garantir que docker compose up sobe tudo e a API responde em GET /health com status 200.

3. Banco de dados e Prisma

   • Inicializar Prisma (prisma/schema.prisma) e traduzir exatamente o schema SQL abaixo para o formato Prisma, preservando nomes de tabelas/campos, tipos, enums, defaults, unique constraints e índices.
   • Não implemente ainda a lógica de RLS na aplicação (isso é da Etapa 2) — mas a migration gerada deve incluir os comandos ALTER TABLE ... ENABLE ROW LEVEL SECURITY e as CREATE POLICY definidos no schema, via uma migration SQL raw do Prisma (Prisma não suporta RLS nativamente, então usar prisma migrate dev seguido de uma migration manual .sql para as policies).
   • Rodar a migration inicial e confirmar que todas as tabelas, enums, views e policies foram criadas corretamente no Postgres do docker-compose.

   Schema de referência (colar aqui o conteúdo completo do arquivo seconectai-vendas-schema.sql fornecido separadamente — use-o como fonte de verdade).

4. Scripts utilitários

   • package.json com scripts: dev, build, start:prod, lint, test, prisma:migrate, prisma:generate, prisma:studio.
   • README.md inicial explicando como subir o projeto localmente (docker compose up, variáveis de ambiente necessárias, como rodar migrations).

5. Testes

   • Configurar Jest (já vem com NestJS) e criar um teste simples do endpoint /health.

Estrutura de pastas esperada

seconectai-vendas/
├── docker-compose.yml
├── docker-compose.override.yml
├── Dockerfile
├── .env.example
├── package.json
├── prisma/
│   ├── schema.prisma
│   └── migrations/
├── src/
│   ├── main.ts
│   ├── app.module.ts
│   ├── config/
│   └── modules/
│       └── health/
│           ├── health.module.ts
│           ├── health.controller.ts
│           └── health.service.ts
└── test/

Critérios de aceite

• docker compose up sobe app, postgres e redis sem erro
• GET /health retorna 200 com status da API e status da conexão com o banco
• Todas as tabelas, enums, views e índices do schema fornecido existem no banco após a migration (conferir com \dt e \dv no psql)
• As policies de RLS estão criadas (\d+ customers mostra a policy)
• .env.example documenta todas as variáveis necessárias
• npm run lint e npm run test rodam sem erro
• README explica como subir o ambiente do zero