# ADR: Introdução Progressiva de Clean Architecture (Sem Migração Forçada)

Status: Proposta / ADR para adoção incremental

## Contexto (estado atual REAL)

Com base em auditoria e docs geradas a partir do código existente:

1. O sistema é Laravel com:
   - camadas HTTP (rotas, controllers, middleware),
   - persistência via Eloquent com conexão fixa em `TenantModel` para tenant e `MainModel` para central,
   - serviços em `app/Services/*` e algumas rotinas de fluxo/relatório em `app/Http/Controllers/*`.

2. Observou-se:
   - controllers com lógica de negócio e queries complexas (com `DB::raw`) e integrações externas em métodos específicos;
   - services que por vezes dependem do contexto HTTP (ex.: uso de `request()->route(...)`) ou instanciam controllers diretamente;
   - multi-tenancy implementado via middleware `app/Http/Middleware/Tenant.php` e conexão dinâmica em `App\Models\Cliente::connect()`.

Referências:
- `docs/architecture/multi-tenancy.md`
- `docs/architecture/violations.md`

## Problema

Os padrões existentes geram risco de:
1. acoplamento entre camadas (ex.: services chamando controllers diretamente);
2. dificuldade de testar e evoluir com regressão;
3. fragilidade em features de tenant e em contratos do front (ex.: relatórios/ DataTables).

Observação: isto é um diagnóstico baseado em evidências encontradas; não assume a existência de uma arquitetura “ideal” já implementada.

## Decisão

Introduzir princípios inspirados em separação de responsabilidades e isolamento de regras de negócio **apenas em novas features**.

Sem migração forçada do legado:
- manter a arquitetura atual como coexistente;
- novas classes devem ser criadas com critérios mínimos de isolamento;
- regressões devem ser evitadas por compatibilidade (principalmente multi-tenancy e contratos de resposta).

## Estratégia obrigatória (adoção progressiva)

1. Escopo restrito a novas features:
   - qualquer adoção de “camadas” adicionais (ex.: isolação de regra de negócio em classes dedicadas) deve começar em endpoints novos ou funcionalidades novas.

2. Coexistência com legado:
   - controllers antigos podem permanecer como orquestradores;
   - as novas features podem usar services/regra de negócio isoladas sem exigir reescrita completa do legado.

3. Multi-tenancy como critério de segurança:
   - para qualquer feature nova que manipule dados de tenant, respeitar o isolamento existente:
     - aplicar middleware `Tenant` quando aplicável,
     - usar `TenantModel` para acesso a dados do tenant,
     - usar `Cliente::connect()` quando a feature exigir conexão dinâmica.

4. Compatibilidade com contratos observados:
   - manter o formato JSON observado para fluxos consumidos por JS (ex.: DataTables serverSide).

## Consequências

Positivas:
- reduzir o acoplamento em novas partes do sistema;
- facilitar manutenção e revisão incremental.

Negativas/Trade-offs:
- haverá coexistência entre estilos antigos e novos por tempo indeterminado.

## Critérios de aceitação (para novas features)

1. A feature não quebra multi-tenancy (via `Tenant`/`TenantModel`/`connect()` como evidenciado no código).
2. A feature preserva o formato esperado pelo front/back quando houver consumo por JS.
3. Quando existir incerteza, documentar explicitamente como “Não identificado no código”.

## Contexto de implementação

Não descrito como padrão obrigatório no legado.
Não identificado no código: templates formais de arquitetura por camadas (Clean Architecture) já adotados.