Domain-Driven Design aplicado a Protheus
Destilação prática de Implementing Domain-Driven Design (Vaughn Vernon) para o mundo
ADVPL/TLPP. DDD responde o que construir e como falar sobre isso com o cliente;
a skill irmã /protheus:clean-architecture responde como organizar o código. Use as
duas juntas em desenvolvimentos com regra de negócio rica.
Regra de ouro do livro: DDD vale a pena onde a complexidade está no negócio (regras,
exceções comerciais, fluxos do cliente) — não em CRUD. Um cadastro simples via MVC padrão
não precisa de agregado; a política de crédito com 12 exceções comerciais precisa.
Parte estratégica (começa aqui, não no código)
1 — Linguagem ubíqua
Um vocabulário único, do negócio do cliente, usado em conversa, especificação, nome de classe,
método e teste. No Protheus a tentação é falar "o ZC1", "o campo ZC1_PERC" — a linguagem
ubíqua exige ContratoComercial, PercentualNegociado.
- Construa o glossário no brainstorm (termo do cliente → significado → tabela/campo que o
materializa) e mantenha na especificação. Detalhe:
references/estrategico.md.
- Código nomeado pela linguagem:
Class ContratoComercial, Method EstaVigente().
O nome da tabela (ZC1) aparece só no repositório.
- Teste de sanidade: leia o método em voz alta para o key-user. Se ele não reconhece o termo,
o nome está errado (ou o modelo está).
2 — Bounded Contexts
Um modelo vale dentro de uma fronteira explícita. "Produto" no contexto Vendas (preço,
tabela de desconto) não é o mesmo "Produto" de Estoque (endereçamento, lote) — e forçar
um modelo único gera o God-fonte com 30 parâmetros.
No Protheus, as fronteiras naturais: o módulo (SIGAFAT/SIGAEST/SIGAFIN), o processo do
cliente, o time que responde. Regras práticas:
- 1 contexto = 1 namespace TLPP (
cliente.vendas, cliente.logistica) e 1 pasta de fontes.
- Customização não cruza contexto por variável
Private/tabela compartilhada — cruza por
contrato explícito (ver context mapping).
- Sinal de fronteira violada: a mesma classe/função precisa de
If por módulo chamador.
3 — Context Mapping (integrações)
Todo desenvolvimento Protheus integra com algo — ERP padrão, Fluig, e-commerce, legado.
O mapa de contextos torna explícito quem manda no modelo (upstream) e quem se adapta
(downstream). O padrão mais importante para o dia a dia:
- ACL — Anticorruption Layer: uma camada sua que traduz o modelo alheio para o seu.
O JSON do e-commerce ou o retorno do ExecAuto não circulam cru pelo seu domínio —
são convertidos na borda. Padrões, exemplos e tabela de decisão:
references/estrategico.md.
Parte tática (os building blocks em TLPP)
Detalhes e código completo em references/tatico-tlpp.md. O essencial:
| Padrão |
O que é |
No Protheus/TLPP |
| Value Object |
Valor imutável definido pelos atributos, com validação no construtor |
Class Cnpj, Class Dinheiro, Class Vigencia — TLPP class que valida ao nascer e não tem setter |
| Entidade |
Tem identidade que persiste no tempo |
ContratoComercial (id = número); a identidade não é o R_E_C_N_O_ |
| Agregado |
Conjunto entidade-raiz + filhos que muda numa transação só, invariantes garantidas pela raiz |
Pedido (SC5+SC6): itens só mudam via métodos da raiz; persistência = 1 ExecAuto = 1 transação |
| Repositório |
Coleção que esconde a persistência, um por agregado |
IPedidoRepo (interface) + implementação BeginSQL/ExecAuto |
| Serviço de domínio |
Regra que não pertence a uma entidade (envolve várias) |
PoliticaCredito:Avaliar(oCliente, oPedido, oHistorico) |
| Serviço de aplicação |
Caso de uso: orquestra, transaciona, não contém regra |
= camada "caso de uso" da /protheus:clean-architecture |
| Evento de domínio |
Fato ocorrido que outros contextos consomem |
"PedidoFaturado" → grava em tabela de eventos/fila; workflow Fluig e integrações reagem sem acoplar |
Regras de agregado que evitam os erros clássicos (Vernon insiste nelas):
- Agregados pequenos — modele a menor fronteira que protege a invariante real.
- Referencie outros agregados por identidade (código do cliente), não por objeto.
- 1 transação = 1 agregado; consistência entre agregados é eventual (eventos),
não um
BeginTran gigante em 5 tabelas de contextos diferentes.
Fluxo de uso
- Brainstorm (
/protheus:brainstorm): monte glossário (linguagem ubíqua), identifique
os contextos envolvidos e desenhe o context map (quem é upstream? precisa de ACL?).
Anexe à especificação aprovada.
- Modelagem tática: para cada contexto, liste agregados (com invariantes!), value
objects e serviços. Gabarito completo:
references/exemplo-modelagem.md.
- Implementação: estruture com
/protheus:clean-architecture (o domínio DDD é a camada
interna); gere com /protheus:writer//protheus:implement.
- Teste: invariantes de agregado e value objects são os melhores alvos de teste unitário (ex.: PROBAT, do tlppCore) —
puros, sem banco.
Regras inegociáveis
- Glossário de linguagem ubíqua antes de nomear classes em desenvolvimento com regra rica.
- Nome de tabela/campo (ZC1, C5_DESC) não aparece fora de repositório e dicionário.
- 1 bounded context = 1 namespace; comunicação entre contextos só por contrato (ACL/evento).
- Invariante de agregado protegida na raiz — nunca "cada tela valida por si".
- 1 transação por agregado; nada de
BeginTran atravessando contextos.
- DDD tático só onde há regra de negócio rica — CRUD segue MVC padrão (
/protheus:mvc-generator).
1---2name: ddd-23description: Aplica Domain-Driven Design (baseado em Implementing DDD, de Vaughn Vernon) ao desenvolvimento Protheus — linguagem ubíqua com o cliente, bounded contexts para organizar customizações, context mapping para integrações, e padrões táticos em TLPP (entidades, value objects, agregados, repositórios, serviços e eventos de domínio). Use quando o dev pedir para "modelar o domínio", "aplicar DDD", "definir bounded context", "organizar uma customização grande por contexto", "modelar integração entre sistemas", "criar value object/agregado", ou no brainstorm de desenvolvimentos com regra de negócio rica.4---56# Domain-Driven Design aplicado a Protheus78Destilação prática de *Implementing Domain-Driven Design* (Vaughn Vernon) para o mundo9ADVPL/TLPP. DDD responde **o que construir e como falar sobre isso com o cliente**;10a skill irmã `/protheus:clean-architecture` responde **como organizar o código**. Use as11duas juntas em desenvolvimentos com regra de negócio rica.1213> Regra de ouro do livro: DDD vale a pena onde a **complexidade está no negócio** (regras,14> exceções comerciais, fluxos do cliente) — não em CRUD. Um cadastro simples via MVC padrão15> não precisa de agregado; a política de crédito com 12 exceções comerciais precisa.1617## Parte estratégica (começa aqui, não no código)1819### 1 — Linguagem ubíqua2021Um vocabulário único, **do negócio do cliente**, usado em conversa, especificação, nome de classe,22método e teste. No Protheus a tentação é falar "o ZC1", "o campo ZC1_PERC" — a linguagem23ubíqua exige `ContratoComercial`, `PercentualNegociado`.2425- Construa o **glossário no brainstorm** (termo do cliente → significado → tabela/campo que o26 materializa) e mantenha na especificação. Detalhe: `references/estrategico.md`.27- Código nomeado pela linguagem: `Class ContratoComercial`, `Method EstaVigente()`.28 O nome da tabela (ZC1) aparece **só no repositório**.29- Teste de sanidade: leia o método em voz alta para o key-user. Se ele não reconhece o termo,30 o nome está errado (ou o modelo está).3132### 2 — Bounded Contexts3334Um modelo vale dentro de uma fronteira explícita. "Produto" no contexto **Vendas** (preço,35tabela de desconto) não é o mesmo "Produto" de **Estoque** (endereçamento, lote) — e forçar36um modelo único gera o God-fonte com 30 parâmetros.3738No Protheus, as fronteiras naturais: o módulo (SIGAFAT/SIGAEST/SIGAFIN), o processo do39cliente, o time que responde. Regras práticas:40- **1 contexto = 1 namespace TLPP** (`cliente.vendas`, `cliente.logistica`) e 1 pasta de fontes.41- Customização não cruza contexto por variável `Private`/tabela compartilhada — cruza por42 contrato explícito (ver context mapping).43- Sinal de fronteira violada: a mesma classe/função precisa de `If` por módulo chamador.4445### 3 — Context Mapping (integrações)4647Todo desenvolvimento Protheus integra com algo — ERP padrão, Fluig, e-commerce, legado.48O mapa de contextos torna explícito **quem manda no modelo** (upstream) e **quem se adapta**49(downstream). O padrão mais importante para o dia a dia:5051- **ACL — Anticorruption Layer**: uma camada sua que traduz o modelo alheio para o seu.52 O JSON do e-commerce ou o retorno do ExecAuto **não circulam cru** pelo seu domínio —53 são convertidos na borda. Padrões, exemplos e tabela de decisão: `references/estrategico.md`.5455## Parte tática (os building blocks em TLPP)5657Detalhes e código completo em `references/tatico-tlpp.md`. O essencial:5859| Padrão | O que é | No Protheus/TLPP |60|---|---|---|61| **Value Object** | Valor imutável definido pelos atributos, com validação no construtor | `Class Cnpj`, `Class Dinheiro`, `Class Vigencia` — TLPP class que valida ao nascer e não tem setter |62| **Entidade** | Tem identidade que persiste no tempo | `ContratoComercial` (id = número); a identidade **não** é o R_E_C_N_O_ |63| **Agregado** | Conjunto entidade-raiz + filhos que muda **numa transação só**, invariantes garantidas pela raiz | Pedido (SC5+SC6): itens só mudam via métodos da raiz; persistência = 1 ExecAuto = 1 transação |64| **Repositório** | Coleção que esconde a persistência, **um por agregado** | `IPedidoRepo` (interface) + implementação BeginSQL/ExecAuto |65| **Serviço de domínio** | Regra que não pertence a uma entidade (envolve várias) | `PoliticaCredito:Avaliar(oCliente, oPedido, oHistorico)` |66| **Serviço de aplicação** | Caso de uso: orquestra, transaciona, não contém regra | = camada "caso de uso" da `/protheus:clean-architecture` |67| **Evento de domínio** | Fato ocorrido que outros contextos consomem | "PedidoFaturado" → grava em tabela de eventos/fila; workflow Fluig e integrações reagem sem acoplar |6869Regras de agregado que evitam os erros clássicos (Vernon insiste nelas):701. **Agregados pequenos** — modele a menor fronteira que protege a invariante real.712. **Referencie outros agregados por identidade** (código do cliente), não por objeto.723. **1 transação = 1 agregado**; consistência entre agregados é **eventual** (eventos),73 não um `BeginTran` gigante em 5 tabelas de contextos diferentes.7475## Fluxo de uso76771. **Brainstorm** (`/protheus:brainstorm`): monte glossário (linguagem ubíqua), identifique78 os contextos envolvidos e desenhe o context map (quem é upstream? precisa de ACL?).79 Anexe à especificação aprovada.802. **Modelagem tática**: para cada contexto, liste agregados (com invariantes!), value81 objects e serviços. Gabarito completo: `references/exemplo-modelagem.md`.823. **Implementação**: estruture com `/protheus:clean-architecture` (o domínio DDD é a camada83 interna); gere com `/protheus:writer`/`/protheus:implement`.844. **Teste**: invariantes de agregado e value objects são os melhores alvos de teste unitário (ex.: PROBAT, do tlppCore) —85 puros, sem banco.8687## Regras inegociáveis8889- Glossário de linguagem ubíqua antes de nomear classes em desenvolvimento com regra rica.90- Nome de tabela/campo (ZC1, C5_DESC) não aparece fora de repositório e dicionário.91- 1 bounded context = 1 namespace; comunicação entre contextos só por contrato (ACL/evento).92- Invariante de agregado protegida na raiz — nunca "cada tela valida por si".93- 1 transação por agregado; nada de `BeginTran` atravessando contextos.94- DDD tático só onde há regra de negócio rica — CRUD segue MVC padrão (`/protheus:mvc-generator`).
tbc-servicos