Mapa de Implementação - Contrasync API

Documento técnico de decisões e roadmap de implementação do backend NestJS

---

1. Decisões Técnicas

1.1 Stack Tecnológico

Componente	Tecnologia	Versão	Justificativa
Framework	NestJS	10.x	Framework enterprise-ready com DI nativo
Linguagem	TypeScript	5.x	Type-safety e melhor DX
ORM	Prisma	5.x	Type-safe queries, migrations automáticas
Database	PostgreSQL	15+	Robusto, suporte a JSON, full-text search
Cache / Broker	Redis	7+	Cache distribuído, locks, backend BullMQ
Filas	BullMQ	5.x	Processamento assíncrono com retry e DLQ
Logs	nestjs-pino (Pino)	4.x	Logs estruturados em JSON
Tracing / Métricas	OpenTelemetry SDK	1.x	Traces distribuídos e métricas
Circuit Breaker	cockatiel	3.x	Retry, timeout, circuit breaker
Cache HTTP	@nestjs/cache-manager	2.x	Cache em endpoints de leitura
Health Checks	@nestjs/terminus	10.x	Health checks profundos
Validação	class-validator	0.14.x	Decorators integrados com Swagger
Documentação	Swagger/OpenAPI	3.0	Auto-gerado via decorators
Auth	Passport.js	0.7.x	Estratégias OAuth prontas

1.2 Autenticação Social (OAuth 2.0)

┌─────────────────────────────────────────────────────────────────┐
│                    FLUXO DE AUTENTICAÇÃO                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  [Frontend]                    [Backend]           [Provider]   │
│      │                            │                    │        │
│      │  GET /auth/:provider/url   │                    │        │
│      │ ─────────────────────────► │                    │        │
│      │                            │                    │        │
│      │  ◄───── OAuth URL ──────── │                    │        │
│      │                            │                    │        │
│      │  ═══════ Redirect ═══════════════════════════► │        │
│      │                            │                    │        │
│      │  ◄═══════ Callback + Code ═════════════════════│        │
│      │                            │                    │        │
│      │  POST /auth/:provider/callback                  │        │
│      │ ─────────────────────────► │                    │        │
│      │                            │  Exchange Code     │        │
│      │                            │ ─────────────────► │        │
│      │                            │                    │        │
│      │                            │ ◄── Access Token ──│        │
│      │                            │                    │        │
│      │                            │  Get User Info     │        │
│      │                            │ ─────────────────► │        │
│      │                            │                    │        │
│      │                            │ ◄── Profile ───────│        │
│      │                            │                    │        │
│      │  ◄─── JWT + Companies ──── │                    │        │
│      │                            │                    │        │
│      │  POST /auth/select-company │                    │        │
│      │ ─────────────────────────► │                    │        │
│      │                            │                    │        │
│      │  ◄─── JWT (with company) ──│                    │        │
│      │                            │                    │        │
└─────────────────────────────────────────────────────────────────┘

Providers Suportados:

Provider	Scopes	Dados Obtidos
LinkedIn	openid profile email	name, email, picture, locale
Google	openid profile email	name, email, picture, verified
Microsoft	openid profile email User.Read	name, email, picture
GitHub	read:user user:email	name, email, avatar_url, login

Variáveis de Ambiente (preparar):

# LinkedIn
LINKEDIN_CLIENT_ID=
LINKEDIN_CLIENT_SECRET=
LINKEDIN_CALLBACK_URL=http://localhost:8011/api/v1/auth/linkedin/callback

# Google
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
GOOGLE_CALLBACK_URL=http://localhost:8011/api/v1/auth/google/callback

# Microsoft
MICROSOFT_CLIENT_ID=
MICROSOFT_CLIENT_SECRET=
MICROSOFT_CALLBACK_URL=http://localhost:8011/api/v1/auth/microsoft/callback

# GitHub
AUTH_GITHUB_CLIENT_ID=
AUTH_GITHUB_CLIENT_SECRET=
GITHUB_CALLBACK_URL=http://localhost:8011/api/v1/auth/github/callback

# JWT
JWT_SECRET=
JWT_EXPIRES_IN=7d

1.3 Multi-Tenancy

┌───────────────────────────────────────────────────────────┐
│                  MODELO MULTI-TENANT                      │
├───────────────────────────────────────────────────────────┤
│                                                           │
│   User ◄────────► UserCompany ◄────────► Company         │
│    │                  │                      │            │
│    │              (role, status)             │            │
│    │                  │                      │            │
│    └──────────────────┼──────────────────────┘            │
│                       │                                   │
│                       ▼                                   │
│              ┌────────────────┐                           │
│              │ Current Tenant │                           │
│              │  (via JWT)     │                           │
│              └────────────────┘                           │
│                       │                                   │
│         ┌─────────────┼─────────────┐                     │
│         ▼             ▼             ▼                     │
│    Contracts     Templates      User                     │
│    (companyId)   (companyId)   (companyId)                │
│                                                           │
└───────────────────────────────────────────────────────────┘

Regras:

• Usuário pode pertencer a múltiplas empresas
• JWT contém companyId selecionado após login
• Todas as queries filtram por companyId automaticamente
• Troca de empresa requer novo POST /auth/select-company

1.4 Versionamento da API

Base URL: /api/v1

Exemplos:
  GET  /api/v1/contracts
  POST /api/v1/auth/google/callback
  GET  /api/v1/dashboard

1.5 Soft Delete

Todas as entidades principais possuem:

{
  createdAt: DateTime
  updatedAt: DateTime
  deletedAt: DateTime?  // null = ativo, preenchido = deletado
}

Comportamento:

• DELETE /resource/:id → Define deletedAt = now()
• Queries padrão filtram deletedAt = null
• Dados nunca são removidos fisicamente

---

2. Arquitetura Clean Code

2.1 Estrutura de Diretórios

src/
│
├── common/                         # Camada compartilhada
│   ├── decorators/
│   │   ├── current-user.decorator.ts
│   │   ├── current-company.decorator.ts
│   │   └── public.decorator.ts
│   ├── filters/
│   │   ├── http-exception.filter.ts
│   │   └── prisma-exception.filter.ts
│   ├── guards/
│   │   ├── jwt-auth.guard.ts
│   │   └── company.guard.ts
│   ├── interceptors/
│   │   ├── transform.interceptor.ts
│   │   └── logging.interceptor.ts
│   ├── pipes/
│   │   └── validation.pipe.ts
│   └── types/
│       ├── api-response.type.ts
│       └── pagination.type.ts
│
├── config/
│   ├── app.config.ts
│   ├── database.config.ts
│   ├── auth.config.ts
│   └── swagger.config.ts
│
├── modules/
│   │
│   ├── auth/                       # Módulo de Autenticação
│   │   ├── domain/
│   │   │   ├── entities/
│   │   │   │   ├── user.entity.ts
│   │   │   │   └── company.entity.ts
│   │   │   ├── interfaces/
│   │   │   │   ├── auth-provider.interface.ts
│   │   │   │   └── jwt-payload.interface.ts
│   │   │   └── enums/
│   │   │       └── auth-provider.enum.ts
│   │   ├── data/
│   │   │   ├── dto/
│   │   │   │   ├── login.dto.ts
│   │   │   │   ├── select-company.dto.ts
│   │   │   │   └── create-company.dto.ts
│   │   │   └── mappers/
│   │   │       └── user.mapper.ts
│   │   ├── repository/
│   │   │   ├── user.repository.ts
│   │   │   └── company.repository.ts
│   │   ├── services/
│   │   │   ├── auth.service.ts
│   │   │   ├── jwt.service.ts
│   │   │   └── providers/
│   │   │       ├── linkedin.strategy.ts
│   │   │       ├── google.strategy.ts
│   │   │       ├── microsoft.strategy.ts
│   │   │       └── github.strategy.ts
│   │   ├── controllers/
│   │   │   └── auth.controller.ts
│   │   └── auth.module.ts
│   │
│   ├── contracts/                  # Módulo de Contratos
│   │   ├── domain/
│   │   │   ├── entities/
│   │   │   │   ├── contract.entity.ts
│   │   │   │   ├── contract-part.entity.ts
│   │   │   │   └── contract-step.entity.ts
│   │   │   ├── interfaces/
│   │   │   │   └── contract-repository.interface.ts
│   │   │   ├── enums/
│   │   │   │   ├── contract-status.enum.ts
│   │   │   │   └── part-role.enum.ts
│   │   │   └── value-objects/
│   │   │       └── progress.vo.ts
│   │   ├── data/
│   │   │   ├── dto/
│   │   │   │   ├── create-contract.dto.ts
│   │   │   │   ├── update-contract.dto.ts
│   │   │   │   ├── search-contract.dto.ts
│   │   │   │   └── add-part.dto.ts
│   │   │   └── mappers/
│   │   │       ├── contract.mapper.ts
│   │   │       └── part.mapper.ts
│   │   ├── repository/
│   │   │   ├── contract.repository.ts
│   │   │   └── contract-part.repository.ts
│   │   ├── services/
│   │   │   ├── contract.service.ts
│   │   │   ├── contract-part.service.ts
│   │   │   └── contract-step.service.ts
│   │   ├── controllers/
│   │   │   ├── contract.controller.ts
│   │   │   └── contract-detail.controller.ts
│   │   └── contracts.module.ts
│   │
│   ├── templates/                  # Módulo de Templates
│   │   ├── domain/
│   │   ├── data/
│   │   ├── repository/
│   │   ├── services/
│   │   ├── controllers/
│   │   └── templates.module.ts
│   │
│   ├── dashboard/                  # Módulo Dashboard
│   │   ├── domain/
│   │   ├── data/
│   │   ├── services/
│   │   ├── controllers/
│   │   └── dashboard.module.ts
│   │
│   ├── monitoring/                 # Módulo Monitoramento
│   │   ├── domain/
│   │   ├── data/
│   │   ├── repository/
│   │   ├── services/
│   │   ├── controllers/
│   │   └── monitoring.module.ts
│   │
│   ├── provider/                   # Módulo Prestador (área do prestador)
│   │   ├── domain/
│   │   ├── data/
│   │   ├── repository/
│   │   ├── services/
│   │   ├── controllers/
│   │   └── provider.module.ts
│   │
│   ├── user/                      # Módulo User
│   │   ├── domain/
│   │   ├── data/
│   │   ├── repository/
│   │   ├── services/
│   │   ├── controllers/
│   │   └── user.module.ts
│   │
│   ├── prestadores/                # Módulo Prestadores (gestão)
│   │   ├── domain/
│   │   ├── data/
│   │   ├── repository/
│   │   ├── services/
│   │   ├── controllers/
│   │   └── prestadores.module.ts
│   │
│   ├── reports/                    # Módulo Relatórios
│   │   ├── domain/
│   │   ├── data/
│   │   ├── repository/
│   │   ├── services/
│   │   ├── controllers/
│   │   └── reports.module.ts
│   │
│   └── settings/                   # Módulo Configurações
│       ├── domain/
│       ├── data/
│       ├── repository/
│       ├── services/
│       ├── controllers/
│       └── settings.module.ts
│
├── prisma/
│   ├── schema/                       ← multi-file schema (Prisma 5.15+)
│   │   ├── base.prisma               ← generator + datasource
│   │   ├── users.prisma
│   │   ├── addresses.prisma
│   │   ├── company.prisma
│   │   ├── permission-profiles.prisma
│   │   ├── uploads.prisma
│   │   ├── templates.prisma
│   │   ├── workflows.prisma
│   │   ├── contracts.prisma
│   │   ├── signing.prisma
│   │   ├── onboarding.prisma
│   │   ├── contract-review.prisma
│   │   ├── compliance.prisma
│   │   ├── reports.prisma
│   │   ├── notifications.prisma
│   │   ├── history.prisma
│   │   ├── invoices.prisma
│   │   ├── contact-leads.prisma
│   │   ├── plans.prisma
│   │   └── subscriptions.prisma
│   ├── migrations/
│   └── seed.ts
│
└── docs/
    ├── business.md
    ├── architecture.md
    └── implementation-map.md

2.2 Camadas e Responsabilidades

┌─────────────────────────────────────────────────────────────────┐
│                        CLEAN ARCHITECTURE                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │                    CONTROLLERS                            │  │
│  │  - Recebe HTTP requests                                   │  │
│  │  - Valida DTOs via class-validator                        │  │
│  │  - Delega para Services                                   │  │
│  │  - Retorna HTTP responses                                 │  │
│  │  - Documentação Swagger                                   │  │
│  └─────────────────────────┬─────────────────────────────────┘  │
│                            │                                    │
│                            ▼                                    │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │                      SERVICES                             │  │
│  │  - Use Cases / Business Logic                             │  │
│  │  - Orquestra operações                                    │  │
│  │  - Regras de negócio                                      │  │
│  │  - Transações                                             │  │
│  └─────────────────────────┬─────────────────────────────────┘  │
│                            │                                    │
│                            ▼                                    │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │                    REPOSITORIES                           │  │
│  │  - Abstração de acesso a dados                            │  │
│  │  - Queries Prisma                                         │  │
│  │  - Filtros e paginação                                    │  │
│  │  - Soft delete handling                                   │  │
│  └─────────────────────────┬─────────────────────────────────┘  │
│                            │                                    │
│                            ▼                                    │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │                       DATA                                │  │
│  │  - DTOs (Data Transfer Objects)                           │  │
│  │  - Mappers (Entity ↔ DTO)                                 │  │
│  │  - Validações com decorators                              │  │
│  └─────────────────────────┬─────────────────────────────────┘  │
│                            │                                    │
│                            ▼                                    │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │                      DOMAIN                               │  │
│  │  - Entities (representação do negócio)                    │  │
│  │  - Interfaces (contratos)                                 │  │
│  │  - Enums (constantes tipadas)                             │  │
│  │  - Value Objects (objetos imutáveis)                      │  │
│  │  - SEM dependência de frameworks                          │  │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

---

3. Mapa de Endpoints

3.1 Auth Module

Método	Endpoint	Descrição	Auth
GET	/auth/:provider/url	Retorna URL OAuth do provider	Public
POST	/auth/:provider/callback	Processa callback OAuth	Public
POST	/auth/select-company	Seleciona empresa ativa	JWT
POST	/auth/create-company	Cria nova empresa	JWT
GET	/auth/me	Retorna usuário + empresa atual	JWT
POST	/auth/logout	Invalida sessão	JWT

Providers: linkedin, google, microsoft, github

3.2 Contracts Module

Método	Endpoint	Descrição	Auth
GET	/contracts	Lista contratos (filtros: search, status, progress)	JWT
GET	/contracts/:id	Busca contrato por ID	JWT
POST	/contracts	Cria novo contrato	JWT
PUT	/contracts/:id	Atualiza contrato	JWT
DELETE	/contracts/:id	Remove contrato (soft delete)	JWT
PATCH	/contracts/:id/status	Atualiza status do contrato	JWT

3.3 Contract Details Module

Método	Endpoint	Descrição	Auth
GET	/contracts/:id/toolbar	Info da toolbar (nome, status, progresso)	JWT
GET	/contracts/:id/steps	Lista steps do contrato	JWT
GET	/contracts/:id/parts	Lista partes do contrato	JWT
POST	/contracts/:id/parts	Adiciona parte ao contrato	JWT
DELETE	/contracts/:id/parts/:partId	Remove parte do contrato	JWT
PATCH	/contracts/:id/steps/:stepKey/complete	Marca step como completo	JWT
GET	/contract-resources	Lista templates e flows disponíveis	JWT

3.4 Dashboard Module

Método	Endpoint	Descrição	Auth
GET	/dashboard	Stats, contratos recentes, atividades	JWT

3.5 Templates Module

Método	Endpoint	Descrição	Auth
GET	/templates	Lista templates (filtros: search, status)	JWT
GET	/templates/:id	Busca template por ID	JWT
POST	/templates	Cria novo template	JWT
PUT	/templates/:id	Atualiza template	JWT
DELETE	/templates/:id	Remove template (soft delete)	JWT
PATCH	/templates/:id/status	Atualiza status do template	JWT
POST	/templates/:id/duplicate	Duplica template	JWT

3.6 Monitoring Module

Método	Endpoint	Descrição	Auth
GET	/monitoring/parts	Lista partes com horas	JWT
GET	/monitoring/parts/:id	Detalhes da parte + sumários	JWT
GET	/monitoring/parts/:id/entries	Entradas filtradas por data	JWT
GET	/monitoring/entries/:id	Busca entrada por ID	JWT
POST	/monitoring/entries	Cria entrada de horas	JWT
PUT	/monitoring/entries/:id	Atualiza entrada	JWT
DELETE	/monitoring/entries/:id	Remove entrada	JWT

3.7 Provider Module (Área do Prestador)

Método	Endpoint	Descrição	Auth
GET	/provider/contracts	Lista contratos do prestador	JWT
GET	/provider/contracts/active	Contrato ativo atual	JWT
GET	/provider/contracts/:id	Detalhes do contrato	JWT
GET	/provider/hours	Lista sumários de horas	JWT
GET	/provider/hours/current	Horas do mês atual	JWT
GET	/provider/hours/:id	Detalhes do sumário	JWT
GET	/provider/compliances	Lista compliances	JWT
GET	/provider/compliances/current	Compliance do mês atual	JWT
GET	/provider/compliances/:id	Detalhes do compliance	JWT
POST	/provider/compliances/:id/submit	Submete compliance	JWT
POST	/provider/compliances/documents	Upload de documento	JWT
GET	/provider/summary	Resumo geral do prestador	JWT

3.8 User Module

Método	Endpoint	Descrição	Auth
GET	/user	Lista user (filtros: search, role, status)	JWT
GET	/user/:id	Busca user por ID	JWT
POST	/user	Cria novo user	JWT
PUT	/user/:id	Atualiza user	JWT
DELETE	/user/:id	Remove user (soft delete)	JWT
PATCH	/user/:id/status	Atualiza status	JWT

3.9 Prestadores Module (Gestão)

Método	Endpoint	Descrição	Auth
GET	/prestadores	Lista prestadores (filtros: search, status)	JWT
GET	/prestadores/:id	Busca prestador por ID	JWT
POST	/prestadores	Cria novo prestador	JWT
PUT	/prestadores/:id	Atualiza prestador	JWT
DELETE	/prestadores/:id	Remove prestador (soft delete)	JWT
PATCH	/prestadores/:id/status	Atualiza status	JWT

3.10 Reports Module

Método	Endpoint	Descrição	Auth
GET	/reports	Lista relatórios	JWT
GET	/reports/:id	Busca relatório por ID	JWT
POST	/reports	Cria novo relatório	JWT
DELETE	/reports/:id	Remove relatório	JWT
GET	/reports/:id/download	Download do relatório (CSV)	JWT

3.11 Settings Module

Método	Endpoint	Descrição	Auth
GET	/settings	Busca configurações do usuário	JWT
PUT	/settings	Atualiza configurações	JWT

3.12 Invoices Module

Método	Endpoint	Descrição	Auth
GET	/invoices	Lista notas fiscais	JWT
GET	/invoices/:id	Detalhe de nota fiscal	JWT
POST	/invoices/emit	Emitir nota fiscal	JWT (provider)
GET	/invoices/:id/pdf	URL do PDF	JWT
POST	/invoices/:id/cancel	Cancelar nota fiscal	JWT

3.13 Companies Module (Certificado Digital)

Método	Endpoint	Descrição	Auth
POST	/companies/:id/certificate	Upload certificado digital (.pfx)	JWT
DELETE	/companies/:id/certificate	Remover certificado digital	JWT

---

4. Modelo de Dados (Prisma)

4.1 Diagrama ER Simplificado

┌─────────────────────────────────────────────────────────────────────────────┐
│                            MODELO DE DADOS                                  │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌──────────┐      ┌──────────────┐      ┌──────────┐                       │
│  │   User   │◄────►│ UserCompany  │◄────►│ Company  │                       │
│  └──────────┘      └──────────────┘      └──────────┘                       │
│       │                                       │                             │
│       │                                       │                             │
│       ▼                                       ▼                             │
│  ┌──────────┐                           ┌──────────┐                        │
│  │ Settings │                           │ Contract │◄─────┐                 │
│  └──────────┘                           └──────────┘      │                 │
│                                              │            │                 │
│                           ┌──────────────────┼────────────┤                 │
│                           │                  │            │                 │
│                           ▼                  ▼            ▼                 │
│                    ┌────────────┐    ┌────────────┐  ┌──────────┐           │
│                    │ContractPart│    │ContractStep│  │ Template │           │
│                    └────────────┘    └────────────┘  └──────────┘           │
│                        │    │                                               │
│                        │    └──────────────────────────────┐                │
│                        ▼                                   ▼                │
│                 ┌────────────┐    ┌────────────┐    ┌────────────┐          │
│                 │ WorkEntry  │───►│  WorkTask  │    │ Compliance │          │
│                 └────────────┘    └────────────┘    └────────────┘          │
│                                                                             │
│                 ┌────────────┐    ┌──────────┐    ┌──────────┐              │
│                 │  Invoice   │    │  Report  │    │   File   │              │
│                 └────────────┘    └──────────┘    └──────────┘              │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

4.2 Entidades Principais

// AUTH
model User {
  id            String         @id @default(uuid())
  email         String         @unique
  name          String
  avatar        String?
  provider      AuthProvider
  providerId    String
  companies     UserCompany[]
  settings      UserSettings?
  createdAt     DateTime       @default(now())
  updatedAt     DateTime       @updatedAt
  deletedAt     DateTime?
}

model Company {
  id                      String         @id @default(uuid())
  name                    String
  document                String?        // CNPJ
  logo                    String?
  inscricaoMunicipal      String?
  codigoMunicipioIbge     String?
  cnae                    String?
  simplesNacional         Boolean        @default(false)
  certificateFileId       String?        // FK para File (.pfx no S3)
  certificatePassword     String?        // Senha do certificado digital
  users                   UserCompany[]
  contracts               Contract[]
  templates               Template[]
  contractParts           ContractPart[]
  reports                 Report[]
  invoicesAsBorrower      Invoice[]
  invoicesAsProvider      Invoice[]
  createdAt               DateTime       @default(now())
  updatedAt               DateTime       @updatedAt
  deletedAt               DateTime?
}

model UserCompany {
  id            String         @id @default(uuid())
  userId        String
  companyId     String
  role          CompanyRole    @default(MEMBER)
  user          User           @relation(fields: [userId], references: [id])
  company       Company        @relation(fields: [companyId], references: [id])
  createdAt     DateTime       @default(now())

  @@unique([userId, companyId])
}

// CONTRACTS
model Contract {
  id            String          @id @default(uuid())
  name          String
  description   String?
  templateId    String?
  template      Template?       @relation(fields: [templateId], references: [id])
  companyId     String
  company       Company         @relation(fields: [companyId], references: [id])
  status        ContractStatus  @default(DRAFT)
  progress      Int             @default(0)
  value         Decimal?
  parts         ContractPart[]
  steps         ContractStep[]
  createdAt     DateTime        @default(now())
  updatedAt     DateTime        @updatedAt
  deletedAt     DateTime?
}

model ContractPart {
  id              String         @unique @default(uuid())
  contractId      String
  companyId       String
  contract        Contract       @relation(fields: [contractId], references: [id])
  company         Company        @relation(fields: [companyId], references: [id])
  workEntries     WorkEntry[]
  retroactiveRequests RetroactiveHourRequest[]
  createdAt       DateTime       @default(now())

  @@id([contractId, companyId])
}

// TEMPLATES
model Template {
  id            String          @id @default(uuid())
  name          String
  description   String?
  content       String          @db.Text
  variables     Json?
  companyId     String
  company       Company         @relation(fields: [companyId], references: [id])
  status        TemplateStatus  @default(DRAFT)
  contracts     Contract[]
  createdAt     DateTime        @default(now())
  updatedAt     DateTime        @updatedAt
  deletedAt     DateTime?
}

// MONITORING
model WorkEntry {
  id             String       @id @default(uuid())
  contractPartId String
  contractPart   ContractPart @relation(fields: [contractPartId], references: [id])
  date           DateTime
  totalMinutes   Int
  reason         String?
  tasks          WorkTask[]
  createdAt      DateTime     @default(now())
  updatedAt      DateTime     @updatedAt
  deletedAt      DateTime?
}

---

5. Padrões de Código

5.1 Nomenclatura

Tipo	Convenção	Exemplo
Classes	PascalCase	ContractService
Métodos	camelCase	findAllByCompany()
Variáveis	camelCase	contractList
Constantes	UPPER_SNAKE	MAX_PAGE_SIZE
Arquivos	kebab-case	contract.service.ts
DTOs	PascalCase + sufixo	CreateContractDto
Interfaces	PascalCase + prefixo I	IContractRepository

5.2 Estrutura de Response

// Sucesso (single)
{
  "data": { ... },
  "message": "Contract created successfully"
}

// Sucesso (list)
{
  "data": [...],
  "meta": {
    "total": 100,
    "page": 1,
    "pageSize": 20,
    "totalPages": 5
  }
}

// Erro
{
  "statusCode": 400,
  "message": "Validation failed",
  "errors": [
    { "field": "email", "message": "Invalid email format" }
  ]
}

5.3 Regras de Clean Code

1. Single Responsibility: Uma classe/método = uma responsabilidade
2. Dependency Injection: Sempre via constructor
3. No Magic Numbers: Usar constantes nomeadas
4. Early Return: Evitar if/else aninhados
5. Self-Documenting Code: Nomes descritivos, sem comentários desnecessários
6. Immutability: Preferir readonly e objetos imutáveis
7. Error Handling: Exceptions tipadas e tratadas

---

6. Cronograma de Implementação

Fase 1: Fundação (Prioridade Alta)

□ Setup do projeto e configurações
  ├── □ Configurar Prisma com PostgreSQL
  ├── □ Configurar Swagger
  ├── □ Criar estrutura de pastas
  └── □ Configurar variáveis de ambiente

□ Common Module
  ├── □ Guards (JWT, Company)
  ├── □ Decorators (@CurrentUser, @CurrentCompany, @Public)
  ├── □ Filters (Exception handlers)
  ├── □ Interceptors (Transform, Logging)
  └── □ Types (APIResponse, Pagination)

□ Auth Module
  ├── □ Domain (entities, interfaces, enums)
  ├── □ Data (DTOs, mappers)
  ├── □ Repository (User, Company)
  ├── □ Services (Auth, JWT, OAuth strategies)
  └── □ Controllers (7 endpoints)

□ Contracts Module
  ├── □ Domain
  ├── □ Data
  ├── □ Repository
  ├── □ Services
  └── □ Controllers (13 endpoints)

Fase 2: Core Features (Prioridade Média)

□ Dashboard Module (1 endpoint)
□ Templates Module (7 endpoints)
□ Monitoring Module (7 endpoints)
□ Provider Module (12 endpoints)

Fase 3: Complementares (Prioridade Baixa)

□ User Module (6 endpoints)
□ Prestadores Module (6 endpoints)
□ Reports Module (5 endpoints)
□ Settings Module (2 endpoints)

---

7. Checklist de Qualidade

Para cada módulo implementado:

• [ ] Todos os endpoints funcionando
• [ ] DTOs com validação class-validator
• [ ] Swagger documentado
• [ ] Soft delete implementado
• [ ] Filtro por companyId aplicado
• [ ] Tratamento de erros padronizado
• [ ] Mappers Entity ↔ DTO
• [ ] Repository com queries otimizadas

---

8. Observações Importantes

1. Compatibilidade Frontend: Todos os endpoints devem retornar exatamente a estrutura esperada pelos mocks do MSW

2. Autenticação Social: O fluxo OAuth deve ser transparente - frontend redireciona para provider, backend processa callback

3. Multi-tenancy: TODAS as queries devem filtrar por companyId do JWT

4. Soft Delete: Nunca usar DELETE físico, sempre UPDATE deletedAt

5. Paginação: Padrão de 20 itens por página, máximo 100

---

Documento gerado para guiar a implementação do backend Contrasync APIÚltima atualização: Março 2026