Documentação Completa — Sistema IGR REURB

Objetivo: Guia de referência para novos desenvolvedores. Contém a visão geral do sistema, arquitetura, todas as entidades, regras de negócio, padrões técnicos e endpoints da API.

1. Visão Geral

O IGR REURB é um ERP Territorial e Jurídico multi-tenant voltado à gestão de projetos de Regularização Fundiária Urbana (Reurb). O sistema transforma dados de geolocalização e cadastros sociais em processos jurídicos robustos, culminando na emissão da CRF (Certidão de Regularização Fundiária) e no registro cartorário.

Stack Tecnológica

Princípios Fundamentais

• Mobile First obrigatório
• Multi-tenant com isolamento por empresaId
• Soft delete via campo ativo (nunca DELETE físico)
• Migrations aditivas (nunca DROP TABLE/COLUMN em produção)
• Mensagens em pt-BR em toda interface e APIs
• Valores monetários em formato R$ #.##0,00

2. Arquitetura Multi-tenant

Hierarquia

Gestor (Root)
  └── Empresa (Tenant)
        ├── Projetos
        ├── Núcleos
        ├── Lotes
        ├── Titulares
        ├── Documentos
        ├── Cobranças
        ├── Notificações
        └── ... (todas as entidades de negócio)

Tipos de Usuário

Regras de Isolamento

1. Todo WHERE em queries Prisma deve incluir empresaId
2. Acesso cross-tenant retorna 403/404 sem revelar existência do registro
3. Gestor em modo impersonação: leitura permitida, escrita bloqueada (403)
4. Se gestorId e empresaId ambos preenchidos → trata como Empresa

3. Diagrama de Camadas

┌─────────────────────────────────────────────────┐
│  Frontend (Next.js App Router)                  │
│  ├── Componentes React                          │
│  ├── Formulários + Zod                          │
│  └── fetchApi (HTTP Client)                     │
├─────────────────────────────────────────────────┤
│  API Layer (Route Handlers)                     │
│  ├── /api/{entidade}/route.ts                   │
│  ├── AuthGuard + Tenant Context                 │
│  └── Swagger/OpenAPI Docs                       │
├─────────────────────────────────────────────────┤
│  Service Layer (Business Logic)                 │
│  ├── src/lib/{entidade}Service.ts  (domínio)    │
│  ├── src/services/{entidade}Service.ts (aux)    │
│  └── auditService                               │
├─────────────────────────────────────────────────┤
│  Data Layer                                     │
│  ├── Prisma Client                              │
│  └── MySQL                                      │
├─────────────────────────────────────────────────┤
│  Shared                                         │
│  ├── src/lib/validators/*.schema.ts             │
│  └── src/lib/utils (dateUtils, csvBuilder...)   │
└─────────────────────────────────────────────────┘

Fluxo de Autenticação

1. Cliente faz login via NextAuth (Credentials ou Microsoft OAuth)
2. Recebe JWT com id, empresaId, gestorId
3. Cada requisição passa pelo AuthGuard que:
   • Valida o token
   • Resolve o TenantContext (tipo de usuário)
   • Extrai empresaId efetivo (direto ou via impersonação)
4. Service recebe empresaId e filtra todas as queries

4. Mapa de Entidades (Banco de Dados)

4.1 Módulo: Gestão e Multi-tenant

4.2 Módulo: Estrutura Territorial

Hierarquia: Projeto → Núcleo → Lote → Edificação

Lote contém:

• Enums geomorfológicos: SituacaoQuadra, Localizacao, Pedologia, Topografia, Testada, Posicao
• Infraestrutura (strings): esgotamento, agua, energia, lixo, iluminacao, calcamento, passeio, drenagem, muro, acesso
• Dados topográficos: memorialDescritivo, coordenadas (GeoJSON), confrontantes

4.3 Módulo: Estrutura Socioeconômica

Titular suporta:

• Pessoa Física: CPF (único por empresa), RG, nome, data nascimento, gênero, filiação, escolaridade, profissão, estado civil, endereço, renda
• Pessoa Jurídica: CNPJ (único por empresa), razão social, nome fantasia, sócio majoritário (auto-referência a PF)

Regras de estado civil:

• Permite cônjuge: CASADO_PARCIAL, CASADO_TOTAL, CASADO_SEPARACAO, UNIAO_ESTAVEL
• Bloqueia cônjuge: SOLTEIRO, DIVORCIADO, VIUVO, SEPARADO

4.4 Módulo: Fluxo Jurídico e Pipeline

Máquina de estados do ProcessoAdministrativo:

ABERTO → EM_ANALISE → APROVADO
                    → REPROVADO → EM_ANALISE
                    → ARQUIVADO → EM_ANALISE

StatusLote e FaseWorkflow:

• slug e ordem são únicos por empresa
• Limite de 30 registros ativos por empresa em StatusLote

4.5 Módulo: Financeiro

Enums:

• StatusCobranca: PENDENTE, PAGO, VENCIDO, CANCELADO
• StatusComissao: PENDENTE, PAGO, CANCELADO
• FormaPagamento: BOLETO, PIX, CARTAO, DINHEIRO, TRANSFERENCIA

Regras de imutabilidade:

• Cobrança com status PAGO ou CANCELADO → não pode alterar valor, dataVencimento, formaPagamento
• Comissão com status PAGO ou CANCELADO → não pode alterar valor, percentual

4.6 Módulo: Notificações

Máquina de estados da Notificação:

RASCUNHO → PUBLICADO → PRAZO_ENCERRADO → CONCLUIDO
                     → IMPUGNADO → CONCLUIDO

Regras:

• Publicação exige dataPublicacao e dataLimiteImpugnacao (limite > publicação)
• Impugnação (impugnou = true) exige dataCiencia preenchida
• Tipos: EDITAL, NOTIFICACAO_PESSOAL, NOTIFICACAO_POSTAL
• Destinatários: CONFRONTANTE, TERCEIRO_INTERESSADO, PROPRIETARIO_REGISTRAL

4.7 Módulo: Documentos (FK Polimórfica)

FK polimórfica — exatamente UM campo preenchido por registro:

• titularId, loteId, municipioId, cidadeId, conjugeId, dependenteId, nucleoId

CategoriaDocumento (24 valores): FOTO, CPF, RG, CONTRATO, CROQUI, IPTU, PROCURACAO, CERTIDAO, PLANTA, MEMORIAL, OUTRO, COMPROVANTE_ENDERECO, COMPROVANTE_RENDA, CERTIDAO_NASCIMENTO, CERTIDAO_CASAMENTO, CERTIDAO_DIVORCIO, CERTIDAO_OBITO, ASSINATURA, DECLARACAO, CNH, COMPROVANTE_AQUISICAO_AREA, FOTO_FRENTE, FOTO_LATERAL_ESQUERDA, FOTO_LATERAL_DIREITA, OUTROS_LOTE

Metadados: nome original (255 chars), caminho storage (500 chars), tipo MIME, tamanho (máx 100MB)

4.8 Módulo: Institucional

4.9 Módulo: Agenda e Logística

Regras:

• Se tipoDeAtivo = COLABORADOR → colaboradorId obrigatório
• Se tipoDeAtivo = VEICULO → veiculoId obrigatório
• dataFim não pode ser anterior a dataInicio

4.10 Módulo: Workflow e Fluxograma

Cascades: Remover macroprocesso remove microtarefas+KPIs. Remover fluxograma remove fases.

4.11 Módulo: Segurança e Auditoria

AuditLog registra:

• action: CREATE, UPDATE, DELETE, REACTIVATE
• entity: nome da entidade afetada
• entityId: ID do registro
• changes: JSON com diff (campo anterior → novo)
• ipAddress: IPv4/IPv6 (max 45 chars)
• userEmail, userId, empresaId

LinkCadastro:

• Token UUID único, indexado
• Uso único (utilizado = true após consumo)
• Link inativo ou utilizado → acesso negado

5. Enums do Sistema

6. Diagrama de Relacionamentos

GESTOR 1───N EMPRESA
EMPRESA 1───N PROJETO
EMPRESA 1───N TITULAR
EMPRESA 1───N LOTE
EMPRESA 1───N NOTIFICACAO
EMPRESA 1───N COBRANCA
EMPRESA 1───N DOCUMENTO

PROJETO 1───N NUCLEO
PROJETO 1───N GLEBA
PROJETO 1───N MACROPROCESSO

NUCLEO 1───N LOTE
NUCLEO 1───N NOTIFICACAO (opcional)

LOTE 1───N EDIFICACAO (cascade)
LOTE 1───N LOTETITULAR
LOTE 1───N CRONOGRAMA_ETAPA
LOTE 1───N COBRANCA (opcional)
LOTE 1───N PROCESSO_ADMINISTRATIVO

TITULAR 1───1 CONJUGE (cascade)
TITULAR 1───N DEPENDENTE (cascade)
TITULAR 1───N CONTATO_TITULAR (cascade)
TITULAR 1───N LOTETITULAR
TITULAR 1───N PROCESSO_ADMINISTRATIVO

MACROPROCESSO 1───N MICROTAREFA (cascade)
MACROPROCESSO 1───N KPI (cascade)

FLUXOGRAMA_GERADO 1───N FLUXOGRAMA_FASE (cascade)

NOTIFICACAO 1───N NOTIFICACAO_DESTINATARIO (cascade)
COBRANCA 1───N COMISSAO (opcional)

7. Organização do Código

Estrutura de Diretórios

src/
├── app/                          # Next.js App Router
│   ├── api/                      # Route Handlers (API)
│   │   ├── agenda/
│   │   ├── cartorios/
│   │   ├── cidades/
│   │   ├── colaboradores/
│   │   ├── cronograma/
│   │   ├── documentos/
│   │   ├── export/
│   │   ├── fases-workflow/
│   │   ├── financeiro/
│   │   ├── fluxogramas/
│   │   ├── gestor/              # APIs do painel Gestor
│   │   ├── grupos/
│   │   ├── lotes/
│   │   ├── macroprocessos/
│   │   ├── me/
│   │   ├── microsoft/           # Integração Microsoft (x-api-key)
│   │   ├── municipios/
│   │   ├── notificacoes/
│   │   ├── nucleos/
│   │   ├── relatorios/
│   │   ├── status-lotes/
│   │   ├── titulares/
│   │   └── usuarios/
│   └── (pages)/                  # Páginas do frontend
├── lib/                          # Serviços de domínio + utilitários
│   ├── authGuard.ts              # AuthGuard central
│   ├── auditService.ts
│   ├── {entidade}Service.ts      # Um service por entidade
│   ├── validators/               # Schemas Zod por entidade
│   │   └── {entidade}.schema.ts
│   └── utils/                    # Utilitários (dateUtils, csvBuilder, etc)
├── services/                     # Serviços auxiliares
│   ├── conjugeService.ts
│   ├── dependenteService.ts
│   └── familiaService.ts
└── tests/
    ├── properties/               # Property-based tests (fast-check)
    └── security/                 # Testes de bypass

Serviços de Domínio (src/lib/)

Nomenclatura: {entidade}Service.ts (camelCase)

Utilitários (src/lib/)

8. Padrões de Código

AuthGuard (src/lib/authGuard.ts)

interface TenantContext {
  type: 'gestor' | 'empresa' | 'prefeitura' | 'sem_vinculo';
  gestorId?: string;
  empresaId?: string;
  municipioId?: string;
  cidadeId?: number;
  userId: string;
}

// Funções exportadas:
getTenantContext(): Promise<TenantContext | null>
getEmpresaIdFromSession(): Promise<string | null>
getGestorIdFromSession(): Promise<string | null>
getEffectiveEmpresaId(request, context): Promise<string | null>
blockWriteDuringImpersonation(request, context): NextResponse | null
unauthorizedResponse(): NextResponse
forbiddenResponse(message?: string): NextResponse

Padrão de Service

interface ServicePattern<T> {
  listar(empresaId: string, filtros?: FiltrosPaginacao): Promise<PaginatedResult<T>>
  buscarPorId(id: string, empresaId: string): Promise<T | null>
  criar(data: CreateDTO, empresaId: string): Promise<T>
  atualizar(id: string, data: UpdateDTO, empresaId: string): Promise<T>
  inativar(id: string, empresaId: string): Promise<T>   // soft delete
  reativar(id: string, empresaId: string): Promise<T>
}

Padrão de Route Handler

export async function GET(request: NextRequest) {
  const context = await getTenantContext();
  if (!context) return unauthorizedResponse();

  const empresaId = await getEffectiveEmpresaId(request, context);
  if (!empresaId) return forbiddenResponse();

  const params = listQuerySchema.safeParse(searchParams);
  if (!params.success) return NextResponse.json({ error: params.error }, { status: 400 });

  const resultado = await entidadeService.listar(empresaId, params.data);
  return NextResponse.json(resultado);
}

Padrão de Validador Zod

// src/lib/validators/{entidade}.schema.ts
import { z } from 'zod';

export const entidadeCreateSchema = z.object({
  nome: z.string().min(1).max(200).transform(v => v.trim()),
  // ... campos
});

export const entidadeUpdateSchema = entidadeCreateSchema.partial();

export type EntidadeCreateDTO = z.infer<typeof entidadeCreateSchema>;
export type EntidadeUpdateDTO = z.infer<typeof entidadeUpdateSchema>;

9. Endpoints da API

APIs Protegidas por JWT (filtro empresaId obrigatório)

APIs do Painel Gestor (JWT + gestorId)

APIs de Integração Microsoft (header x-api-key)

APIs Públicas (sem autenticação)

APIs de Arquivos Estáticos (JWT)

10. Tratamento de Erros

Padrão de Respostas HTTP

Regras

1. Nunca expor nomes de tabelas, campos ou stack traces ao frontend
2. Mensagens amigáveis sempre em português (pt-BR)
3. Logs detalhados apenas no servidor (console.error)
4. Frontend exibe mensagens via toast (Sonner) — nunca usar alert()
5. Auditoria de falhas não quebra a operação principal (try/catch)

11. Regras de Segurança

Autenticação

• NextAuth com JWT (Credentials + Microsoft OAuth)
• Expiração configurável via variável de ambiente
• Rotas não-públicas retornam 401 sem token válido

Proteção Multi-tenant

• Todo WHERE inclui empresaId
• UPDATE/DELETE valida propriedade do registro
• Acesso cross-tenant → 403/404 sem revelar existência

Impersonação (Gestor → Empresa)

• Via cookie impersonateEmpresaId ou header x-impersonate-empresa
• Valida que empresa pertence ao gestor
• GET permitido, POST/PATCH/DELETE bloqueado (403)

Integração Microsoft

• Protegida por header x-api-key = variável MICROSOFT_API_KEY
• Sem token válido → 401

Sanitização

• Validação Zod no frontend E backend (mesmo schema)
• trim(), toLowerCase() para emails, replace(/\D/g, "") para dígitos
• Nunca usar dangerouslySetInnerHTML sem sanitizador
• Headers de segurança (CSP, HSTS, X-Content-Type-Options)

Testes de Segurança Obrigatórios

Para cada nova rota:

1. Sem token → 401
2. Token de outro tenant → 403/404
3. Campos sensíveis no payload (role, empresaId) → ignorados
4. Payload malicioso (scripts, SQL) → rejeitado pelo Zod

12. Padrões Técnicos Transversais

13. Diretrizes para o Novo Desenvolvedor

Ao criar uma nova entidade:

1. Definir model no schema.prisma com CUID, empresaId, ativo, createdAt, updatedAt
2. Gerar migration aditiva (npx prisma migrate dev --name descricao)
3. Criar schema Zod em src/lib/validators/{entidade}.schema.ts
4. Criar service em src/lib/{entidade}Service.ts com CRUD + filtro empresaId
5. Criar route handler em src/app/api/{entidade}/route.ts
6. Adicionar testes Vitest (unit + segurança)

Ao modificar uma entidade existente:

1. Migration aditiva (ADD COLUMN, ALTER COLUMN — nunca DROP)
2. Atualizar schema Zod correspondente
3. Atualizar service se necessário
4. Verificar Omit/Partial nos DTOs que referenciam a entidade
5. Rodar testes

Regras de ouro:

• Todo WHERE inclui empresaId
• Nunca usar prisma.$queryRaw com strings dinâmicas
• Soft delete sempre (campo ativo)
• Toast (Sonner) para mensagens — nunca alert()
• Mobile first em toda UI
• Formato monetário pt-BR com máscara em campos de valor
• Datas no formato dd/mm/yyyy
• Tabelas com paginação (primeiro, anterior, nro página, próximo, último)
• Tabelas reordenáveis ao clicar no título da coluna
• Listas com filtro ativo/inativo/todos (padrão: Ativos)
• Ações inline em tabelas: Editar (Pencil), Inativar (Ban), Reativar (Play)

14. Variáveis de Ambiente

⚠️ Nunca comitar valores reais. Preencher localmente.

15. Comandos Úteis

# Instalar dependências
npm install

# Rodar em desenvolvimento
npm run dev

# Gerar Prisma Client
npx prisma generate

# Criar migration
npx prisma migrate dev --name descricao_da_alteracao

# Rodar testes
npx vitest --run

# Build
npm run build

# Docker (produção)
docker compose up -d

Documento gerado em 30/06/2026 — Referência completa do sistema IGR REURB para onboarding de desenvolvedores.