Projeto da FASE 1: Sistema de gestão de clientes, planos e assinaturas para operadora de telecomunicações, desenvolvido com NestJS, Prisma e PostgreSQL seguindo os princípios da Arquitetura Limpa.
Este projeto foi desenvolvido seguindo os princípios da Clean Architecture (Arquitetura Limpa) proposta por Robert C. Martin, organizando o código em camadas bem definidas com responsabilidades específicas e baixo acoplamento.
┌─────────────────────────────────────────┐
│ HTTP Layer (Controllers) │ ← Camada de Apresentação
│ ClienteController | PlanoController │ (Controllers específicos)
│ AssinaturaController | GestaoController│
├─────────────────────────────────────────┤
│ Application Layer (Use Cases) │ ← Camada de Aplicação
│ ClienteService | PlanoService │ (Services por domínio)
│ AssinaturaService │
├─────────────────────────────────────────┤
│ Domain Layer (Entities) │ ← Camada de Domínio
│ Cliente | Plano | Assinatura │ (Entidades + Repositories)
│ + Repository Interfaces │
├─────────────────────────────────────────┤
│ Infrastructure Layer (Database) │ ← Camada de Infraestrutura
│ Repository Implementations │ (Prisma + Converters)
│ + Data Converters │
└─────────────────────────────────────────┘
@startuml
!define RECTANGLE class
' Definindo os componentes principais
component "Serviço Gestão" as ServicoGestao {
component "GestaoController" as Controller
component "GestaoService" as Service
component "ClienteRepository" as ClienteRepo
component "PlanoRepository" as PlanoRepo
component "AssinaturaRepository" as AssinaturaRepo
}
' Componentes de infraestrutura
component "Banco de Dados PostgreSQL" as BancoDados {
component "Tabela Cliente" as TabelaCliente
component "Tabela Plano" as TabelaPlano
component "Tabela Assinatura" as TabelaAssinatura
}
component "Prisma ORM" as Prisma {
component "PrismaClienteRepository" as PrismaCliente
component "PrismaPlanoRepository" as PrismaPlano
component "PrismaAssinaturaRepository" as PrismaAssinatura
}
' Entidades de domínio
component "Entidades de Domínio" as Entidades {
component "Cliente Entity" as ClienteEntity
component "Plano Entity" as PlanoEntity
component "Assinatura Entity" as AssinaturaEntity
}
' Relacionamentos entre camadas
Controller --> Service : usa
Service --> ClienteRepo : usa
Service --> PlanoRepo : usa
Service --> AssinaturaRepo : usa
' Implementações dos repositórios
ClienteRepo <|.. PrismaCliente : implementa
PlanoRepo <|.. PrismaPlano : implementa
AssinaturaRepo <|.. PrismaAssinatura : implementa
' Conexão com banco
PrismaCliente --> BancoDados : conecta
PrismaPlano --> BancoDados : conecta
PrismaAssinatura --> BancoDados : conecta
' Uso das entidades
Service --> ClienteEntity : cria/usa
Service --> PlanoEntity : cria/usa
Service --> AssinaturaEntity : cria/usa
' Relacionamentos no banco
TabelaAssinatura --> TabelaCliente : FK codCli
TabelaAssinatura --> TabelaPlano : FK codPlano
' Anotações dos endpoints
note top of Controller
Endpoints FASE 1 (REST por Domínio):
GET /clientes
GET /planos
POST /assinaturas
PATCH /planos/:id
GET /assinaturas/:tipo
GET /assinaturas/cliente/:codcli
GET /assinaturas/plano/:codplano
end note
note bottom of BancoDados
Modelos necessários:
- Cliente (codigo, nome, email)
- Plano (codigo, nome, custoMensal, data, descricao)
- Assinatura (codigo, codPlano, codCli,
inicioFidelidade, fimFidelidade,
dataUltimoPagamento, custoFinal, descricao)
end note
@endumlA aplicação foi desenvolvida seguindo rigorosamente os cinco princípios SOLID:
Cada classe possui uma única responsabilidade:
- Controllers: Apenas manipulam requisições HTTP
- Services: Contêm apenas lógica de negócio
- Repositories: Responsáveis apenas pela persistência de dados
- Entities: Representam apenas as regras de negócio do domínio
// Exemplo: ClienteController tem apenas a responsabilidade de lidar com HTTP
@Controller('clientes')
export class ClienteController {
constructor(private readonly clienteService: ClienteService) {}
@Get()
listarTodos() {
return this.clienteService.listarTodos(); // Delega para o service
}
}As classes estão abertas para extensão e fechadas para modificação:
- Uso de interfaces abstratas para repositórios
- Possibilidade de adicionar novas implementações sem modificar código existente
// Interface abstrata - fechada para modificação
export abstract class ClienteRepository {
abstract listarTodos(): Promise<Cliente[]>;
}
// Implementação concreta - aberta para extensão
export class PrismaClienteRepository implements ClienteRepository {
async listarTodos(): Promise<Cliente[]> {
// Implementação específica do Prisma
}
}Implementações concretas podem substituir suas abstrações sem quebrar a funcionalidade:
PrismaClienteRepositorypode substituirClienteRepositoryPrismaPlanoRepositorypode substituirPlanoRepository
Interfaces específicas e coesas, sem métodos desnecessários:
- Cada repository possui apenas os métodos necessários para sua entidade
- DTOs específicos para cada operação
Dependência de abstrações, não de implementações:
- Services dependem de interfaces abstratas dos repositories
- Injeção de dependência configurada no módulo
@Injectable()
export class ClienteService {
constructor(
private clienteRepository: ClienteRepository, // Abstração, não implementação
) {}
}Abstrai a lógica de acesso a dados, permitindo trocar implementações sem afetar a lógica de negócio.
Domain Layer (Abstract) → Infrastructure Layer (Concrete)
ClienteRepository → ClienteRepositoryImpl
PlanoRepository → PlanoRepositoryImpl
AssinaturaRepository → AssinaturaRepositoryImpl
Utilizado pelo NestJS para gerenciar dependências e garantir baixo acoplamento.
Objetos específicos para transferência de dados entre camadas:
CriarAssinaturaDto: Para criação de assinaturasAssinaturaListDto: Para listagem de assinaturas
Entidades de domínio encapsulam regras de negócio:
export class Assinatura {
isAtiva(): boolean {
const hoje = new Date();
return this.dataUltimoPagamento >=
new Date(hoje.getTime() - 30 * 24 * 60 * 60 * 1000);
}
}| Método | Endpoint | Descrição | Parâmetros | Resposta |
|---|---|---|---|---|
GET |
/clientes |
Lista todos os clientes | Nenhum | Array com todos os atributos da entidade |
GET |
/planos |
Lista todos os planos | Nenhum | Array com todos os atributos da entidade |
POST |
/assinaturas |
Cria uma assinatura | {codCli, codPlano, custoFinal, descricao} |
Objeto com todos os atributos da assinatura |
PATCH |
/planos/:id |
Atualiza custo mensal do plano | {custoMensal} |
Objeto com todos os atributos do plano |
GET |
/assinaturas/:tipo |
Lista assinaturas por tipo | tipo: TODOS|ATIVOS|CANCELADOS |
Array de objetos com status |
GET |
/clientes/:codcli/assinaturas |
Lista assinaturas do cliente | codcli: número |
Array de objetos com status |
GET |
/planos/:codplano/assinaturas |
Lista assinaturas do plano | codplano: número |
Array de objetos com status |
Para facilitar os testes e validação dos endpoints, foram criados dois arquivos dedicados:
- Arquivo:
TESTES-API.postman_collection.json - Conteúdo: Collection completa com todos os 7 endpoints da FASE 1
- Como testar?: Vá em "import" e insira o arquivo.
# Teste básico para verificar se a API está funcionando
curl http://localhost:3000/clientes
# Deve retornar array JSON com clientesgit clone <URL_DO_SEU_REPOSITORIO>
cd servico-gestaoCrie o arquivo .env na raiz do projeto:
# Configurações do PostgreSQL
POSTGRES_USER=docker
POSTGRES_PASSWORD=docker
POSTGRES_DB=servico_gestao
POSTGRES_PORT=5432docker-compose up --build
- ✅ Migrações aplicadas automaticamente
- ✅ Banco populado com dados de teste
- ✅ Aplicação iniciada
curl http://localhost:3000/clientes# Parar todos os serviços
docker-compose down
# Ver logs em tempo real
docker-compose logs -f backend
# Resetar banco de dados (recria tudo)
docker-compose down -v
docker-compose up --buildsrc/
├── main.ts # Entry point da aplicação
├── app.module.ts # Módulo principal
├── cliente.module.ts # Módulo de clientes
├── plano.module.ts # Módulo de planos
├── assinatura.module.ts # Módulo de assinaturas
├── gestao.module.ts # Módulo de gestão (endpoints compostos)
├── prisma.service.ts # Serviço do Prisma
│
├── application/ # Camada de Aplicação
│ └── use-cases/ # Casos de uso específicos
│ ├── cliente.service.ts # Lógica de negócio - Clientes
│ ├── plano.service.ts # Lógica de negócio - Planos
│ └── assinatura.service.ts # Lógica de negócio - Assinaturas
│
├── domain/ # Camada de Domínio
│ ├── entities/ # Entidades de negócio
│ │ ├── cliente.entity.ts
│ │ ├── plano.entity.ts
│ │ └── assinatura.entity.ts
│ └── repositories/ # Interfaces dos repositórios
│ ├── cliente.repository.ts
│ ├── plano.repository.ts
│ └── assinatura.repository.ts
│
├── infrastructure/ # Camada de Infraestrutura
│ ├── http/ # Controllers (REST API)
│ │ ├── cliente.controller.ts # Endpoints de clientes
│ │ ├── plano.controller.ts # Endpoints de planos
│ │ ├── assinatura.controller.ts # Endpoints de assinaturas
│ │ └── gestao.controller.ts # Endpoints compostos
│ └── database/ # Implementações dos repositórios
│ ├── cliente.repository.impl.ts
│ ├── cliente.converter.ts # Conversão Entity ↔ Prisma
│ ├── plano.repository.impl.ts
│ ├── plano.converter.ts
│ ├── assinatura.repository.impl.ts
│ └── assinatura.converter.ts
│
└── shared/ # Recursos compartilhados
└── constants/ # Constantes do sistema
├── index.ts
└── time.constants.ts
prisma/
├── schema.prisma # Schema do banco de dados
└── seed.ts # Script de população inicial
- NestJS: Framework Node.js para aplicações escaláveis
- TypeScript: Linguagem com tipagem estática
- Prisma: ORM moderno para TypeScript/Node.js
- PostgreSQL: Banco de dados relacional robusto
- Docker: Containerização da aplicação
- Docker Compose: Orquestração de containers
O desenvolvimento desta fase foi focado na criação de uma base sólida para o sistema de gestão da operadora, priorizando:
- Arquitetura Limpa: Separação clara de responsabilidades entre camadas
- Princípios SOLID: Aplicação rigorosa dos cinco princípios
- Separação por Domínio: Services e Controllers específicos para cada entidade
- Testabilidade: Código desacoplado e facilmente testável
- Manutenibilidade: Estrutura organizada e extensível
A aplicação seguiu uma abordagem híbrida, combinando:
- Controllers por Domínio:
ClienteController,PlanoController,AssinaturaController - Controller Composto:
GestaoControllerpara endpoints que cruzam domínios - Services Especializados: Cada entidade possui seu próprio service
- Repositories com Converters: Separação entre entidades de domínio e modelos de dados
Foi implementado um padrão de conversão entre as entidades de domínio e os modelos do Prisma:
// Exemplo do ClienteConverter
export class ClienteConverter {
static toEntity(prismaCliente: PrismaCliente): Cliente {
// Converte modelo Prisma para entidade de domínio
}
static toPrisma(cliente: Cliente): PrismaCliente {
// Converte entidade de domínio para modelo Prisma
}
}Este padrão garante que:
- A camada de domínio permaneça independente do ORM
- As regras de conversão fiquem centralizadas
- Seja fácil trocar o ORM no futuro
Desafio: Definir relacionamentos entre Cliente, Plano e Assinatura de forma eficiente.
Solução: Utilizou-se chaves estrangeiras para manter integridade referencial e campos calculados para status das assinaturas.
Referência: Prisma Relations
Desafio: Abstrair a camada de dados mantendo flexibilidade para mudanças futuras.
Solução: Criação de interfaces abstratas na camada de domínio com implementações concretas na infraestrutura.
Referência: Repository Pattern
Desafio: Determinar se uma assinatura está ativa ou cancelada baseada em regras de negócio.
Solução: Implementação de lógica na entidade de domínio e nos repositórios, considerando o último pagamento (30 dias).
Desafio: Configurar ambiente de desenvolvimento reproduzível e fácil de executar.
Solução: Docker Compose com serviços separados para aplicação e banco de dados, incluindo scripts de inicialização.
Referência: NestJS with Docker
Desafio: Organizar o código de forma que cada domínio tenha suas responsabilidades bem definidas.
Solução: Criação de módulos, services e controllers específicos para cada entidade (Cliente, Plano, Assinatura), com um módulo de gestão para operações que cruzam domínios.
Referência: NestJS Modules
Desafio: Manter a independência entre as entidades de domínio e os modelos do banco de dados.
Solução: Implementação de classes converter que fazem a tradução entre entidades de domínio e modelos Prisma, mantendo as camadas desacopladas.
Desafio: Criar dados de teste realistas para validação dos endpoints.
Solução: Script de seed automatizado com dados variados (assinaturas ativas e canceladas).
Referência: Prisma Seeding
- Clean Architecture - Robert C. Martin
- SOLID Principles
- NestJS Documentation
- Prisma Best Practices
- TypeScript Handbook
Desenvolvido por: Gabriela de Castro Laurindo
Data de Entrega Final do Projeto: Agosto de 2025
Situação Atual: O projeto segue em constante aprimoramento, com foco na implementação de melhorias e na solidificação dos conhecimentos.