Regra 1 — Blocos, nao monolitos
Regra 1 — Blocos, nao monolitos
Primeiro ensaio da trilha. Escrito antes de qualquer codigo.
1. O que a regra diz
Tudo e bloco. Em toda camada. Em toda escala.
Os 8 principios:
- Blocos, nao monolitos
- Comeco, meio e fim (entrada → processamento → saida)
- Validar antes de empilhar
- Substituivel por design (contratos, nao dependencia)
- Simples ate provar que precisa ser complexo
- IA executa, humano arquiteta
- Componentizacao em toda camada
- Estrutura de pastas padronizada
"Sistemas confiaveis sao feitos de blocos confiaveis. Nao existe atalho."
Validar (principio 3) concretamente significa: smoke test (curl /health), contrato (endpoint recebe X, devolve Y), integracao (service A conversa com B). Nenhum bloco entra no sistema sem pelo menos 1 validacao.
2. Como o GLC aplica
O escopo do email do Ale tem 4 frentes: MAPEAMENTO, WORKPLAN, PRODUCAO, PROMOCAO. A tentacao e tratar como "um sistema". Na pratica, cada um e um bloco com entrada, processamento e saida distintos:
| Bloco | Entrada | Processamento | Saida |
|---|---|---|---|
| Mapear | CNPJ, CNAE, socios, endereco, estrutura | Classificar + consultar status | Dashboard com semaforo |
| Workplan | Licencas vencendo em N dias | Montar calendario + SLAs | Plano aprovado + checklists |
| Producao | Licenca + plano | Coletar docs, validar, submeter | Protocolo + licenca renovada |
| Promocao | Base publica de empresas com licencas vencidas | Enriquecer decisores + segmentar | Leads + apresentacao |
Porque isso importa:
- Substituivel (princ. 4): o Bloco C pode trocar o orgao alvo (Fed → Municipal) sem afetar o Bloco A
- Simplicidade (princ. 5): v1 so liga Bloco A. Bloco B, C, D existem como placeholders no dominio, nao como codigo
- IA executa, humano arquiteta (princ. 6): Claude desenhou essa decomposicao; Ale+Rafa validam ou cortam
- Validar antes (princ. 3): antes de construir o Bloco B, o Bloco A precisa ter cliente real operando e pagando. Mesmo teste do
/health, so que em nivel de produto
Dentro do Bloco A tambem tem sub-blocos:
- CRUD de empresa (entrada: form; saida: empresa persistida)
- Classificador de licencas aplicaveis (entrada: empresa + catalogo; saida: lista filtrada)
- Calculador de proxima renovacao (entrada: licenca + historico; saida: data estimada)
- Disparo de alerta (entrada: licenca; saida: email enviado + log)
Cada um tem entrada, processamento, saida. Cada um pode ser testado sozinho. Cada um pode ser substituido (ex: trocar email por WhatsApp sem mexer no classificador).
3. Armadilha comum
"Tudo e bloco" virando 'tudo e mini-microservico'.
Bloco nao precisa ser microservico. Pode ser uma funcao, um modulo, uma classe. O que importa e:
- Tem contrato claro? (assinatura)
- Da para testar isolado? (sem subir meio mundo)
- Da para substituir sem cascata?
No GLC, calcular_proxima_renovacao(licenca, historico) -> date e um bloco perfeitamente legitimo. Nao precisa de container proprio.
Outro erro: decompor em blocos antes de entender o dominio. Se a decomposicao for errada, voce monta 4 containers que nunca conversam direito. O email do Ale ja entrega a decomposicao natural (Mapeamento/Workplan/Producao/Promocao) — aproveitar.
4. Checklist (vale so quando v1 estiver de pe, mas ja vale olhar agora)
- Cada bloco tem entrada/processamento/saida documentados
- Cada bloco tem pelo menos 1 teste de contrato (input → output esperado)
- Nenhum bloco chama outro sem ir por um contrato (HTTP ou assinatura de funcao clara)
- V1 entrega 1 bloco funcionando, nao 4 pela metade
-
/healthresponde 200 em cada service - Trocar o canal de alerta (email → WhatsApp) nao requer tocar no classificador
Referencias
- Decomposicao em blocos:
docs/requisitos.mdsecao 2 - Diagrama C4:
docs/arquitetura.mdsecoes 2 e 3 - ADR 0001 (v1 so Bloco A):
docs/decisoes/0001-escopo-v1-vertical-unico.md