# Guia de Referência: State (Comportamental) Este guia orienta a aplicação do padrão **State** em projetos de software. **Objetivo:** Encapsular comportamentos que mudam conforme o estado interno, fazendo cada estado representar suas próprias transições/regras. O padrão deve ser usado somente quando as forças do problema o justificarem. --- ## 1. Problema que resolve Um objeto tem muitos `if/switch` sobre status em vários métodos e cada novo estado espalha alterações. ### Sinais no código/arquitetura - `switch(status)` se repete. - Transições válidas são complexas. - Cada estado habilita ações diferentes. ## 2. Quando usar - Pedidos, tickets, workflow de aprovação, máquinas, conexões. - Ciclos de vida com regras e transições explícitas. ## 3. Quando NÃO usar - Quando há poucos estados simples e uma enum + tabela de transição é mais clara. - Quando estados são apenas dados sem mudança de comportamento. ## 4. Estrutura e participantes - Context: mantém estado atual e delega. - State: contrato de comportamento. - ConcreteState: regras e possíveis transições. ## 5. Procedimento de implementação 1. Liste estados e transições válidas. 2. Extraia comportamentos dependentes de status. 3. Defina contrato State. 4. Mova regras para estados concretos. 5. Centralize auditoria/transição e evite estados impossíveis. ## 6. Exemplo mental `Ticket` delega `assign`, `resolve`, `reopen` a `OpenState`, `InProgressState`, `ResolvedState`. ## 7. Benefícios esperados - Remove condicionais espalhadas. - Torna transições explícitas. - Cada estado fica coeso. ## 8. Custos e trade-offs - Mais classes. - Pode ser excesso para máquina de estados pequena. ## 9. Encaixe com Clean Architecture e SOLID Excelente para entidades com ciclo de vida rico; mantenha infraestrutura fora dos states e dispare efeitos externos via eventos/casos de uso. **Regras para a IA:** - Dependa de abstrações quando a variação justificar uma fronteira. - Não faça o domínio importar SDKs, frameworks, banco de dados ou UI. - Mantenha cada participante com responsabilidade coesa. - Prefira composição quando ela reduzir acoplamento; não crie hierarquias artificiais. - Registre a decisão arquitetural quando o padrão afetar muitos módulos. ## 10. Caminho de refatoração Procure múltiplos `if status` e alterações divergentes sempre que um novo estado é adicionado. Ao refatorar um sistema existente: 1. Proteja o comportamento atual com testes. 2. Faça passos pequenos e reversíveis. 3. Introduza primeiro a abstração/contrato. 4. Migre um fluxo por vez. 5. Remova código antigo apenas após equivalência comportamental comprovada. ## 11. Estratégia de testes Teste matriz de transições, operações permitidas/proibidas e efeitos de cada estado. Checklist mínimo: - [ ] caminho feliz - [ ] entradas/estados de limite - [ ] erros e falhas de dependências - [ ] comportamento de cada implementação concreta - [ ] teste de contrato quando houver múltiplas implementações - [ ] teste de integração apenas onde a fronteira externa for relevante ## 12. Padrões relacionados - Strategy - Memento - Template Method ## 13. Perguntas de diagnóstico para a IA 1. Qual aspecto do sistema realmente varia? 2. Essa variação já está causando duplicação, condicionais ou acoplamento? 3. Uma função/composição simples resolveria com menos abstrações? 4. O padrão reduz o custo de uma mudança concreta que já é provável? 5. Qual é o custo de introduzir novas classes, indireção e configuração? 6. Como a decisão será testada e observada em produção? ## 14. Prompt pronto ```text Você é o arquiteto do projeto. Avalie se o padrão **State** é adequado para o problema abaixo. Contexto: [DESCREVA o sistema, stack/arquitetura, estado atual e o problema observado] Objetivo: [DESCREVA o resultado esperado ao avaliar ou aplicar este padrão] Restrições: [DESCREVA prazo, legado, performance, testes, compatibilidade e o que não pode mudar] Antes de codificar: 1. Identifique as forças que justificam ou rejeitam State. 2. Compare pelo menos uma alternativa mais simples e um padrão relacionado (Strategy, Memento, Template Method). 3. Se o padrão for justificado, mostre participantes, dependências e fluxo. 4. Preserve Clean Architecture/SOLID: regras centrais não dependem de infraestrutura. 5. Implemente incrementalmente, com testes. 6. Ao final, liste trade-offs e sinais de overengineering. Não aplique o padrão apenas porque foi solicitado; rejeite-o se não houver variação/complexidade que o justifique. ``` ### Como preencher os campos - **Contexto:** descreva o tipo de sistema, stack/versões, arquitetura atual, onde a mudança acontece e o comportamento relevante já existente. - **Objetivo:** descreva o resultado observável que deve existir ao final, não apenas a tecnologia que você quer usar. - **Restrições:** informe o que não pode mudar, compatibilidade, prazo, segurança, acessibilidade, performance, legado, dependências e limites de escopo. ### Exemplo preenchido ```text Contexto: Atendimento muda entre Agendado, Presente, Em atendimento e Concluído, com ações permitidas diferentes em cada estado. Objetivo: Encapsular comportamento por estado e tornar transições explícitas. Restrições: Não usar se são apenas poucos flags sem comportamento; validar transições inválidas. ``` ## 15. Critério de aceite A aplicação de **State** só está concluída quando: - [ ] o problema que motivou o padrão está explicitamente documentado; - [ ] o código cliente depende do contrato correto, não de detalhes acidentais; - [ ] adicionar a variação-alvo exige menos mudanças que antes; - [ ] testes protegem a extensão/refatoração; - [ ] não houve vazamento de infraestrutura para o núcleo; - [ ] a solução ficou mais compreensível para manutenção, não apenas “mais orientada a padrões”. ## 16. Base Conceitual e Relações - Catálogo Refactoring.Guru em português — escopo de 22 padrões. - *Design Patterns: Elements of Reusable Object-Oriented Software* (Gamma, Helm, Johnson e Vlissides) — intenção, aplicabilidade, participantes, consequências e relações entre padrões. - Guias de Clean Architecture, princípios de design, refatoração e código limpo deste pacote.