Padrões NestJS

Adaptação do code-style NestJS do Contrasync, consultado em 2026-09-07. Referência técnica: módulos NestJS. Este é um contrato para implementação futura.

Camadas

Controller valida o contrato HTTP e delega. Service orquestra o caso de uso. Repository concentra persistência. Mapper transforma entidades em DTOs públicos. Domain contém tipos, entidades, interfaces, enums, constantes e regras puras. Adaptadores implementam portas para Google, Git, filas e redes.

Módulos usam injeção de dependência via constructor. Não importar SDK de rede ou geração no controller. Não misturar chamada externa com transação de banco longa. Planejar efeito externo por outbox e reconciliar seu resultado.

Tipagem e nomenclatura

Proibido any. Dados externos entram como unknown e passam por validação. Usar tipos Prisma gerados nas consultas quando Prisma for implementado. Classes em PascalCase, métodos camelCase, constantes UPPER_SNAKE_CASE e arquivos kebab-case. DTOs terminam em Dto.

Tipos e constantes reutilizáveis pertencem a domain, não a arquivos de controller, service, mapper ou repository. Imports usam aliases configurados. Sem comentários explicativos no código: nomes claros e documentação registram a intenção.

Funções têm responsabilidade única, retornos antecipados e erros tipados. Contratos públicos e portas têm tipos de retorno explícitos. A regra de inferir retorno do Vue não se transfere automaticamente para contratos do backend.

Entrada e autorização

DTOs validam formato, tamanho máximo, enums, paginação e datas. Texto longo de artigo tem limite próprio, distinto de título e pesquisa. Definir constantes compartilhadas, sem presumir decorators do Contrasync já implementados.

Toda operação valida associação do usuário ao projeto. Repository filtra projectId e registros removidos quando aplicável. Não confiar no identificador de projeto enviado pelo cliente nem em aprovação antiga. Aprovação referencia contentVersionId.

Persistência e arquivos

Se adotado Prisma, um módulo global fornece um PrismaService por processo. Não registrar o serviço novamente em cada módulo e não criar clientes avulsos. API e workers separados têm pools próprios que precisam caber no limite total do banco.

Metadados de arquivo têm registro central; entidades de conteúdo referenciam fileId. Não duplicar tamanho, MIME e caminho em várias tabelas. Histórico de publicação e auditoria é preservado mesmo quando conteúdo é arquivado. Definir exclusão lógica por domínio, sem apagar recibos necessários à reconciliação.

Integrações

Todo adapter define timeout, erros transitórios/permanentes, limites, idempotência e consulta de estado quando suportada. Não presumir que toda rede suporta todos os formatos ou agendamento nativo. Capacidades e permissões devem ser verificadas na integração concreta.

Webhook valida assinatura, data e identificador do evento. Não registrar payloads com segredo em logs. Segredos não entram em DTO público, prompt ou frontend. Um resultado de geração é dado não confiável até passar por validação de schema e regras editoriais.

Qualidade

Testar autorização entre projetos, concorrência de orçamento e pauta, timeout após envio, webhook repetido, pausa com job pendente e falha de deploy. Cobrir efeitos e invariantes, usando contratos simulados nas verificações locais sem publicar conteúdo real.