Clean Architecture

Clean Architecture aplicada ao Fluig

Destilação prática dos princípios de Clean Architecture para os dois mundos do Fluig: o widget Angular + PO-UI (front) e o lado plataforma (datasets, eventos de workflow e formulários). Objetivo: regra de negócio que sobrevive a troca de tela, de endpoint e de versão — e é testável com Jasmine/Karma sem HTTP nem plataforma no ar.

Skills irmãs: /fluig:ddd (modelagem — o que construir), esta (estrutura — como organizar). Se o time também usa o plugin protheus, os equivalentes são /protheus:clean-architecture e /protheus:ddd — mesmos princípios, outro stack.

Consulta MCP (antes de gerar código)

• Versão do Angular/PO-UI: nunca fixe em código novo. Leia o package.json do projeto; para projeto novo, use a versão estável atual do Angular (o PO-UI acompanha o major do Angular). Confirme via MCP — não confie na memória do modelo para versão.
• MCP do Angular CLI (npx -y @angular/cli mcp): get_best_practices e search_documentation antes de decidir padrão (standalone, signals, control flow); list_projects para entender o workspace; modernize/onpush_zoneless_migration em código legado.
• MCP do PO-UI (@po-ui/mcp, já configurado no plugin): list_components + get_component_docs antes de escrever qualquer componente visual; get_guide para temas (acessibilidade, theming).
• MCP tbc-knowledge: searchFluigPatterns({ category: "conventions" }) para as convenções do plugin (estrutura de pastas, naming wg_/ds_/wf_).

A Regra de Dependência

Dependências apontam para dentro: apresentação → aplicação → domínio ← infraestrutura. A regra de negócio não conhece componente, template, HttpClient nem DatasetFactory.

[ Component/Page PO-UI · template · evento de form · evento de workflow ]  ← entrada/saída
        ↓ chama
[ Service de aplicação (caso de uso): orquestra, coordena estado ]         ← aplicação
        ↓ chama                          ↓ chama (via interface)
[ Domínio: classes/funções TS puras ]  [ Adapter: HttpClient, DatasetFactory, hAPI ]

Teste rápido de violação: se o mesmo arquivo tem template/HTTP E um cálculo/decisão de negócio, ele está em duas camadas — dividir. Vale para .component.ts e para ds_*.js.

Mapa de camadas → artefatos Fluig

No widget (Angular + PO-UI)

• A DI do Angular já entrega o DIP: o caso de uso recebe o adapter pelo construtor (inject()); para testar, provê-se um dublê no TestBed — sem HttpTestingController para testar regra de negócio.
• Componente com HttpClient injetado = violação direta (pula duas camadas).

No lado plataforma (server-side JS)

O antipadrão nº 1 do Fluig é o god-dataset: createDataset() com 300 linhas fazendo constraint parsing + REST + regra + montagem de dataset. A refatoração guiada está em references/plataforma-datasets-eventos.md.

SOLID em TypeScript/Angular — resumo operacional

• SRP — um service = um assunto; componente > ~200 linhas ou service que mistura HTTP + regra + formatação → dividir.
• OCP — variação por estratégia injetada (token de DI + implementações), não switch de tipo replicado.
• LSP — implementações de uma interface honram o contrato (sem throw "não suportado").
• ISP — interfaces por papel (ConsultaPedidos, AprovaPedidos), não um ApiService gordo.
• DIP — casos de uso dependem de abstração (abstract class/token); Angular DI injeta a concreta. Detalhes e exemplos: references/camadas-widget-angular.md.

Quando aplicar (pragmatismo)

Não crie domain/ para um widget que só lista um dataset — sobre-engenharia também é dívida.

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

Um arquivo gigante é problema; vinte arquivos de dez linhas também são — cada um entra no bundle, no review e no .zip do widget. Separe por motivo de mudança, não por contagem de classes. O Angular já obriga multi-arquivo por componente; a camada extra tem que se pagar:

• Extraia um service quando houver 2+ consumidores ou quando a testabilidade exigir (dublê no lugar de HTTP/Dataset). Service com um consumidor só é indireção, não arquitetura.
• Interface com uma implementação só: só se o teste precisa do dublê.
• No dataset/evento (Rhino, sem import), o "arquivo por camada" não existe — separe em funções puras no mesmo fonte, como já diz o mapa de camadas acima.
• A lista de artefatos é fechada no /fluig:plan. Arquivo que não está no plano não é criado na implementação — se a necessidade apareceu, é decisão de design e volta ao /fluig:brainstorm.

Fluxo de uso

1. Design (/fluig:brainstorm / /fluig:plan): por caso de uso, defina os artefatos por camada antes de codar; marque o que é regra pura (testável sem TestBed/plataforma).
2. Implementação (/fluig:widget, /fluig:dataset, /fluig:workflow, /fluig:implement): siga os esqueletos das references.
3. Review (/fluig:review): checklist estrutural em references/plataforma-datasets-eventos.md e references/camadas-widget-angular.md.
4. Teste (/fluig:test): a recompensa — domínio com Jasmine puro (rápido, sem TestBed); adapter com HttpTestingController; componente só com teste de interação.

Regras inegociáveis

• Componente/página nunca injeta HttpClient nem chama DatasetFactory — sempre via service.
• Regra de negócio nunca importa @angular/*, @po-ui/*, nem toca hAPI/DatasetFactory.
• Evento de workflow/form delega para função nomeada — a lógica nunca mora inline no evento.
• Integração REST Protheus: URL/rota/parse em um único adapter por recurso.
• Toda regra pura nasce com spec Jasmine (o /fluig:test cobra cobertura ≥ 70%).
• try/catch + log nos adaptadores server-side (regra do plugin) — mas o catch não engole: loga e propaga/devolve erro estruturado.