# Guia de Referência: Factory Method (Criacional)


Este guia orienta a aplicação do padrão **Factory Method** em projetos de software. **Objetivo:** Delegar a decisão de qual classe concreta instanciar, mantendo o código cliente dependente de uma abstração. O padrão deve ser usado somente quando as forças do problema o justificarem.

---

## 1. Problema que resolve

O fluxo principal sabe que precisa de um produto, mas o tipo concreto varia por contexto, plataforma, integração ou extensão futura.

### Sinais no código/arquitetura
- Há muitos `new`/construtores espalhados para produtos da mesma família conceitual.
- Adicionar um novo tipo exige editar código de alto nível que deveria permanecer estável.
- Um framework/base class conhece o fluxo, mas subclasses precisam escolher o produto concreto.

## 2. Quando usar
- Criação de conectores, exportadores, parsers, notificadores ou gateways cuja implementação varia.
- Extensões/plugins em que cada módulo registra ou produz um tipo específico.
- Fluxos em que uma superclasse define o processo e subclasses controlam apenas a criação.

## 3. Quando NÃO usar
- Quando existe apenas uma implementação e não há variação real prevista.
- Quando uma função fábrica simples resolve sem hierarquia ou polimorfismo.
- Quando a escolha do produto é apenas configuração de dados e não comportamento.

## 4. Estrutura e participantes
- Product: contrato usado pelo cliente.
- ConcreteProduct: implementações concretas.
- Creator: declara o método fábrica e trabalha com `Product`.
- ConcreteCreator: decide qual `ConcreteProduct` produzir.

## 5. Procedimento de implementação
1. Extraia um contrato comum para os produtos.
2. Mova a criação para um método fábrica.
3. Faça o fluxo principal depender apenas do contrato do produto.
4. Crie variantes do creator somente quando houver diferenças legítimas de criação.
5. Teste o fluxo com produtos fakes/stubs para confirmar o desacoplamento.

## 6. Exemplo mental

Um módulo de exportação chama `createExporter()` e depois `export(data)`. `PdfReportCreator` retorna `PdfExporter`; `CsvReportCreator` retorna `CsvExporter`.

## 7. Benefícios esperados
- Reduz acoplamento entre lógica de negócio e classes concretas.
- Facilita OCP: novos produtos podem ser adicionados com menor impacto.
- Centraliza regras de construção.

## 8. Custos e trade-offs
- Pode criar subclasses/arquivos adicionais.
- Se usado sem variação real, vira cerimônia desnecessária.

## 9. Encaixe com Clean Architecture e SOLID

Normalmente o contrato do produto fica em domínio/aplicação; a implementação concreta pode ficar em adapters/infra. O ponto de composição escolhe o creator.

**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

Bom alvo quando aparecem condicionais repetidas para escolher classes concretas ou quando a criação impede testes isolados.

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 o comportamento do cliente contra o contrato; teste cada creator para garantir que produz um objeto compatível e corretamente configurado.

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
- Abstract Factory
- Template Method
- Prototype

## 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 **Factory Method** é 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 Factory Method.
2. Compare pelo menos uma alternativa mais simples e um padrão relacionado (Abstract Factory, Template Method, Prototype).
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: Serviço de exportação precisa gerar PDF e CSV sem o cliente conhecer classes concretas.
Objetivo: Adicionar um novo formato de exportação sem modificar o fluxo principal.
Restrições: Manter contrato atual; evitar switch central crescente; testes por produto concreto.
```


## 15. Critério de aceite

A aplicação de **Factory Method** 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.