Projeto Final: Sistema Enterprise Tipado com Clean Architecture e Domain-Driven Design
Consolidação e coroamento de toda a formação de TypeScript Profissional: construa do zero um Motor de Assinaturas e Faturamento Enterprise (SaaS Billing Engine) 100% tipado, aplicando na prática Clean Architecture, Domain-Driven Design (DDD), princípios SOLID, Value Objects imutáveis, Result/Either Pattern funcional e repositórios genéricos desacoplados.
📑 Índice do Conteúdo
1. O Desafio Enterprise: SaaS Billing & Subscription Engine
Parabéns por alcançar a 50ª e última lição desta formação profissional de TypeScript! Ao longo das 49 aulas anteriores, você construiu uma base sólida: desde a inferência e tipos primitivos, passando por uniões discriminadas, Generics avançados com infer, Mapped Types, Decorators modernos, manipulação tipada do DOM até as configurações mais rigorosas do tsconfig.json.
Neste Projeto Final, uniremos todo esse conhecimento em um sistema corporativo real: um Motor de Assinaturas e Faturamento Recorrente (SaaS Subscription Engine). O sistema deve atender às seguintes exigências de negócio e arquitetura:
- Domínio Rico e Puro: Nada de modelos anêmicos. Entidades e Value Objects encapsulam suas próprias regras de validação e máquinas de estado.
- Independência de Frameworks: O núcleo da aplicação é escrito em TypeScript puro, sem depender de Express, Fastify ou ORMs específicos.
- Tratamento Funcional de Erros: Adoção do Result Pattern (estilo Rust/Haskell) em vez de lançar exceções
try/catchdesgovernadas. - Injeção e Inversão de Dependências: Repositórios e gateways de pagamento baseados em contratos estritos (
interfaces).
src/
├── core/
│ └── Result.ts # Tratamento funcional de erros (Sucesso/Falha)
├── domain/
│ ├── value-objects/
│ │ ├── Email.ts # Validação intrínseca de formato
│ │ └── Dinheiro.ts # Aritmética de precisão para centavos
│ ├── entities/
│ │ ├── Cliente.ts # Entidade raiz de assinante
│ │ └── Assinatura.ts # Ciclo de vida: Ativa, Pausada, Cancelada
│ └── repositories/
│ └── IAssinaturaRepo.ts # Contrato genérico de persistência
├── application/
│ └── use-cases/
│ └── CriarAssinatura.ts # Caso de uso com DTOs tipados
└── infrastructure/
├── database/
│ └── InMemoryRepo.ts # Repositório em memória para testes
└── payment/
└── FakeStripeGateway.ts # Gateway de pagamento desacoplado
2. Tratamento Funcional com o Result Pattern
Em sistemas corporativos de missão crítica, disparar exceções (throw new Error) para erros esperados de negócio (como “saldo insuficiente” ou “e-mail duplicado”) desvia o fluxo natural de controle e mascara falhas graves de runtime. O Result Pattern transforma a resposta em um tipo de união estrita:
export type Result =
| { readonly sucesso: true; readonly valor: T }
| { readonly sucesso: false; readonly erro: E };
export class Results {
public static ok(valor: T): Result {
return { sucesso: true, valor };
}
public static falha(erro: E): Result {
return { sucesso: false, erro };
}
}
3. Camada de Domínio: Value Objects Imutáveis
Para evitar bugs clássicos de arredondamento com números de ponto flutuante em JavaScript (como 0.1 + 0.2 === 0.30000000000000004), o Value Object Dinheiro armazena internamente os valores em centavos inteiros:
export class Dinheiro {
private readonly centavos: number;
private constructor(centavos: number) {
this.centavos = Math.round(centavos);
}
public static deReais(valor: number): Result {
if (valor < 0) {
return Results.falha('O valor financeiro não pode ser negativo.');
}
return Results.ok(new Dinheiro(valor * 100));
}
public get valorEmReais(): number {
return this.centavos / 100;
}
public somar(outro: Dinheiro): Dinheiro {
return new Dinheiro(this.centavos + outro.centavos);
}
public formatar(): string {
return `R$ ${this.valorEmReais.toFixed(2)}`;
}
}
4. Entidade de Domínio: Ciclo de Vida da Assinatura
A entidade Assinatura gerencia sua própria máquina de estados finitos (FSM):
export type StatusAssinatura = 'pendente' | 'ativa' | 'cancelada' | 'suspensa';
export interface PropsAssinatura {
id: string;
clienteId: string;
plano: 'starter' | 'pro' | 'enterprise';
precoMensal: Dinheiro;
status: StatusAssinatura;
iniciadaEm: Date;
expiraEm: Date;
}
export class Assinatura {
private props: PropsAssinatura;
public constructor(props: PropsAssinatura) {
this.props = { ...props };
}
public get id(): string { return this.props.id; }
public get status(): StatusAssinatura { return this.props.status; }
public get preco(): Dinheiro { return this.props.precoMensal; }
public ativar(): Result {
if (this.props.status === 'ativa') {
return Results.falha('A assinatura já se encontra ativa.');
}
if (this.props.status === 'cancelada') {
return Results.falha('Não é possível reativar uma assinatura definitivamente cancelada.');
}
this.props.status = 'ativa';
return Results.ok(undefined);
}
public cancelar(): Result {
if (this.props.status === 'cancelada') {
return Results.falha('A assinatura já está cancelada.');
}
this.props.status = 'cancelada';
return Results.ok(undefined);
}
}
5. Caso de Uso: Assinar Plano Corporativo
O Caso de Uso orquestra as regras da aplicação interagindo com o Gateway de Pagamentos e o Repositório de Assinaturas:
export interface AssinarPlanoInput {
clienteId: string;
emailCliente: string;
plano: 'starter' | 'pro' | 'enterprise';
valorMensal: number;
}
export interface IGatewayPagamento {
cobrar(clienteId: string, valor: Dinheiro): Promise;
}
export interface IAssinaturaRepository {
salvar(assinatura: Assinatura): Promise;
buscarPorId(id: string): Promise;
}
export class AssinarPlanoUseCase {
public constructor(
private readonly gateway: IGatewayPagamento,
private readonly repo: IAssinaturaRepository
) {}
public async executar(input: AssinarPlanoInput): Promise {
// 1. Criar Value Object financeiro
const dinheiroRes = Dinheiro.deReais(input.valorMensal);
if (!dinheiroRes.sucesso) {
return Results.falha(dinheiroRes.erro);
}
// 2. Cobrar no gateway financeiro
const cobrancaRes = await this.gateway.cobrar(input.clienteId, dinheiroRes.valor);
if (!cobrancaRes.sucesso) {
return Results.falha(`Falha no faturamento: ${cobrancaRes.erro}`);
}
// 3. Criar entidade com estado ativo
const assinatura = new Assinatura({
id: `sub_${Date.now()}_${Math.random().toString(36).substring(2, 7)}`,
clienteId: input.clienteId,
plano: input.plano,
precoMensal: dinheiroRes.valor,
status: 'pendente',
iniciadaEm: new Date(),
expiraEm: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000)
});
// 4. Ativar assinatura
const ativacaoRes = assinatura.ativar();
if (!ativacaoRes.sucesso) {
return Results.falha(ativacaoRes.erro);
}
// 5. Persistir no repositório
await this.repo.salvar(assinatura);
return Results.ok({ assinaturaId: assinatura.id });
}
}
Você concluiu com sucesso todas as 50 lições da Web Academy! Dominar a união entre a tipagem estática do TypeScript e princípios avançados de arquitetura de software (Clean Architecture, DDD e SOLID) coloca você no percentil superior de engenheiros de software do mercado global.
projeto-final-enterprise-billing.ts
// =====================================================================
// PROJETO FINAL: SAAS BILLING ENGINE COM CLEAN ARCHITECTURE & DDD
// =====================================================================
// [1. RESULT PATTERN]
type Result =
| { readonly ok: true; readonly data: T }
| { readonly ok: false; readonly error: E };
const ok = (data: T): Result => ({ ok: true, data });
const fail = (error: E): Result => ({ ok: false, error });
// [2. VALUE OBJECT: DINHEIRO COM CENTAVOS PRECISOS]
class Dinheiro {
private constructor(public readonly centavos: number) {}
public static criar(reais: number): Result {
if (reais < 0) return fail('Valor monetário não pode ser negativo.');
return ok(new Dinheiro(Math.round(reais * 100)));
}
public formatar(): string {
return `R$ ${(this.centavos / 100).toFixed(2)}`;
}
}
// [3. ENTIDADE DE DOMÍNIO: ASSINATURA COM MÁQUINA DE ESTADOS]
type StatusSub = 'pendente' | 'ativa' | 'cancelada';
class Assinatura {
public constructor(
public readonly id: string,
public readonly clienteId: string,
public readonly plano: string,
public readonly valor: Dinheiro,
public status: StatusSub = 'pendente'
) {}
public ativar(): Result {
if (this.status === 'ativa') return fail('A assinatura já está ativa.');
if (this.status === 'cancelada') return fail('Assinatura cancelada não pode ser reativada.');
this.status = 'ativa';
return ok(undefined);
}
public cancelar(): Result {
if (this.status === 'cancelada') return fail('Assinatura já se encontra cancelada.');
this.status = 'cancelada';
return ok(undefined);
}
}
// [4. PORTAS DE INFRAESTRUTURA (INTERFACES)]
interface IAssinaturaRepo {
salvar(sub: Assinatura): Promise;
buscar(id: string): Promise;
}
interface IGatewayCobranca {
cobrar(clienteId: string, quantia: Dinheiro): Promise;
}
// [5. ADAPTADORES DE INFRAESTRUTURA EM MEMÓRIA]
class InMemoryAssinaturaRepo implements IAssinaturaRepo {
private readonly dados = new Map();
public async salvar(sub: Assinatura): Promise {
this.dados.set(sub.id, sub);
}
public async buscar(id: string): Promise {
return this.dados.get(id) || null;
}
}
class FakeStripeGateway implements IGatewayCobranca {
public async cobrar(clienteId: string, quantia: Dinheiro): Promise {
console.log(`[Stripe Gateway] Autorizando cobrança de ${quantia.formatar()} para cliente ${clienteId}...`);
return ok(`ch_stripe_${Date.now()}`);
}
}
// [6. CASO DE USO DE APLICAÇÃO (USE CASE)]
class AssinarPlanoUseCase {
public constructor(
private readonly gateway: IGatewayCobranca,
private readonly repo: IAssinaturaRepo
) {}
public async executar(clienteId: string, plano: string, preco: number): Promise {
const dinheiroRes = Dinheiro.criar(preco);
if (!dinheiroRes.ok) return fail(dinheiroRes.error);
const cobrancaRes = await this.gateway.cobrar(clienteId, dinheiroRes.data);
if (!cobrancaRes.ok) return fail(cobrancaRes.error);
const sub = new Assinatura(`sub_${Date.now()}`, clienteId, plano, dinheiroRes.data);
const ativacao = sub.ativar();
if (!ativacao.ok) return fail(ativacao.error);
await this.repo.salvar(sub);
return ok(sub);
}
}
// [7. EXECUÇÃO DA DEMONSTRAÇÃO COMPLETA]
async function rodarProjetoFinal() {
console.log('======================================================');
console.log('🎯 PROJETO FINAL: SISTEMA ENTERPRISE TYPESCRIPT & DDD');
console.log('======================================================');
const repo = new InMemoryAssinaturaRepo();
const gateway = new FakeStripeGateway();
const useCase = new AssinarPlanoUseCase(gateway, repo);
console.log('n1. Processando assinatura de plano corporativo:');
const resultado = await useCase.executar('cli_corp_9918', 'TypeScript Enterprise Cloud', 2490.00);
if (resultado.ok) {
const sub = resultado.data;
console.log(`✅ Assinatura criada com Sucesso!`);
console.log(` -> ID: ${sub.id}`);
console.log(` -> Plano: ${sub.plano}`);
console.log(` -> Mensalidade: ${sub.valor.formatar()}`);
console.log(` -> Status Atual: ${sub.status.toUpperCase()}`);
console.log('n2. Testando cancelamento de assinatura:');
sub.cancelar();
console.log(` -> Status após cancelamento: ${sub.status.toUpperCase()}`);
console.log('n3. Testando proteção de invariante (tentativa de reativação inválida):');
const reativacaoInvalida = sub.ativar();
if (!reativacaoInvalida.ok) {
console.log(`🛡️ Invariante de domínio protegida: "${reativacaoInvalida.error}"`);
}
} else {
console.log(`❌ Erro no processo: ${resultado.error}`);
}
console.log('n======================================================');
console.log('🎉 FORMAÇÃO DE TYPESCRIPT PROFISSIONAL 100% CONCLUÍDA!');
console.log('======================================================');
}
rodarProjetoFinal();
Aplique o que você aprendeu nesta lição
Utilize nossas ferramentas online gratuitas para experimentar os conceitos ou teste o código ao vivo no Playground IDE.
Editor de Códigos Web Online
Ambiente com destaque de sintaxe para você testar tags, tabelas e scripts na hora.
Abrir Ferramenta OnlinePlayground Web Online
Escreva seu código HTML, CSS ou JavaScript e veja o resultado renderizado ao vivo no navegador com zero configuração.
⚡ Codificar no Playground IDE