Clean Architecture

Clean Architecture aplicada a ADVPL/TLPP

Destilação prática dos princípios do livro Clean Architecture para o ecossistema Protheus. O objetivo não é academicismo: é que a regra de negócio do cliente sobreviva a troca de tela, de banco, de release e de dev — e seja testável por unidade, sem subir tela nem depender de massa de dados.

Skills irmãs: /protheus:ddd (modelagem do domínio — o que construir), esta skill (estrutura — como organizar), /protheus:migrate (procedural → TLPP OO) e /protheus:refactor-method-complexity-reduce (extração de métodos em função complexa).

A Regra de Dependência (o coração do livro)

Dependências de código apontam sempre para dentro — da infraestrutura para o domínio, nunca o contrário. A regra de negócio não conhece tela, endpoint, tabela nem framework.

[ REST @Get/@Post · ModelDef/ViewDef · Ponto de Entrada · Schedule ]   ← entrada/saída
        ↓ chama
[ Caso de uso: orquestra, valida entrada, controla transação ]        ← aplicação
        ↓ chama                     ↓ chama
[ Regra de negócio pura ]    [ Repositório / ExecAuto wrapper ]        ← domínio · persistência
   (sem SQL, sem tela)          (todo SQL/RecLock vive AQUI)

Teste rápido de violação: se a função tem BeginSQL/RecLock E um cálculo de negócio E monta JSON/tela, ela está em três camadas ao mesmo tempo — dividir.

Mapa de camadas → artefatos Protheus

SOLID em TLPP — resumo operacional

• SRP — um fonte/classe/função = um motivo para mudar. Função > ~60 linhas ou que mistura camadas → extrair (a skill /protheus:refactor-method-complexity-reduce automatiza a extração). Detalhes e exemplos: references/solid-tlpp.md.
• OCP — variações de comportamento por classe/bloco injetado, não por Do Case de tipo espalhado em N funções.
• LSP — subclasse TLPP honra o contrato da base (mesmos pré/pós-requisitos; não "lança erro se for do tipo X").
• ISP — interfaces TLPP pequenas por papel (ICalculaFrete), não uma IUtils gorda.
• DIP — caso de uso depende de interface de repositório; a implementação concreta (BeginSQL/ExecAuto) é injetada no construtor. É isso que permite testar a regra com dublê.

Organização de fontes (screaming architecture)

O diretório grita o domínio, não a tecnologia: agrupe por assunto de negócio (faturamento/, estoque/), não por tipo (apis/, queries/, telas/). Dentro de cada assunto, os sufixos de camada dizem o papel: *Service (caso de uso), *Repo (persistência), regra pura sem sufixo. A nomenclatura de arquivo segue a convenção do projeto; a organização é por pasta e namespace TLPP (namespace cliente.faturamento).

Quando aplicar (pragmatismo)

Sobre-engenharia também é dívida: não crie interface + repositório + service para encapsular um Posicione(). O critério é: a regra de negócio merece viver isolada e testada.

Camada ≠ arquivo (o SOLID não é para virar enxurrada de fontes)

Um fonte gigante é problema; vinte fontes minúsculos também são — cada .tlpp entra no patch, precisa compilar, versionar e ser conferido na documentação de customizações. Separe por motivo de mudança, não por contagem de classes.

• TLPP aceita mais de uma classe no mesmo fonte (verificado em código compilado em produção: adapter + service convivendo no mesmo arquivo, sob o mesmo namespace). Classes coesas — mesmo papel, mesmo contexto, que mudam pelo mesmo motivo — ficam juntas.
• Piso: classe pequena que existe só "para ficar SOLID" volta para o fonte do seu papel. Interface com uma implementação só: só crie se o teste precisa do dublê.
• Teto: fonte passando de ~800 linhas, ou classe de ~500, é sinal de divisão real.
• A lista de fontes é fechada no /protheus:plan. Fonte que não está no plano não é criado na implementação — se apareceu a necessidade, ela é decisão de design e volta ao /protheus:brainstorm.

Os números são ponto de partida calibrado em desenvolvimento real. Ajuste no seu projeto se o padrão local for outro — mas mantenha um teto declarado, não "o quanto sair".

Fluxo de uso

1. No design (/protheus:brainstorm / /protheus:plan / /protheus:advpl-tlpp-sdd): para cada caso de uso da especificação, defina os artefatos por camada (tabela acima) antes de codar. Liste que regra é pura (testável por unidade) e que acesso a dados vira repositório/ExecAuto.
2. Na implementação (/protheus:writer / /protheus:implement): siga references/regra-dependencia-camadas.md (esqueleto de cada camada com código) e valide contra os sinais de violação.
3. No review (/protheus:reviewer / /protheus:code-review): aplique o checklist estrutural de references/refatoracao-exemplo.md — o exemplo before/after mostra o monólito típico (endpoint que faz tudo) e a versão em camadas.
4. Testes: a recompensa da separação — regra pura testada por unidade (ex.: PROBAT, o framework de testes do tlppCore) sem fixture de banco; o E2E de tela fica com /protheus:tir-test-generator.

Regras inegociáveis

• Regra de negócio nunca contém BeginSQL, RecLock, MsMessage ou montagem de JSON.
• Endpoint REST / PE / ViewDef nunca acessa tabela diretamente — sempre via caso de uso.
• Escrita em tabela padrão TOTVS = ExecAuto (encapsulado em repositório), nunca RecLock direto (pula validações do dicionário).
• Transação (BeginTran/EndTran) pertence ao caso de uso — nem à regra, nem ao repositório.
• Todo caso de uso novo nasce com teste unitário da(s) regra(s) pura(s) que orquestra.