# Migração da `includes/`

## Objetivo

Reduzir `includes/` até ela deixar de ser o centro do sistema.

O alvo não é "colocar tudo em PSR" de forma cega. O alvo é separar responsabilidades:

- `src/` para regras, serviços, repositórios, controllers e guards
- `pages/*` para composição de tela, partials e modais da própria área
- `assets/` para JS/CSS reutilizável
- uma camada mínima de bootstrap para WordPress + autenticação + contexto

## Diagnóstico atual

Hoje `includes/` mistura quatro papéis diferentes:

1. Bootstrap/runtime
- `autoload.php`
- `autoload_v2.php`
- `template/head.php`
- `template/body-start.php`
- `template/footer.php`

2. Domínio legado
- classes em `includes/` e `includes/classes`
- helpers globais com acesso a `$wpdb`, sessão, contrato e usuário

3. UI compartilhada
- `abas/`
- `cards/`
- `widgets/`
- `graficos/`
- `modais/`
- `template/`

4. Utilitários soltos
- helpers de string, cor, formatação, contexto, permissões, dashboards, glossário etc.

Na prática, `includes/` virou um "container genérico" que atende tanto páginas antigas quanto páginas novas.

## O que já está melhor no sistema

Algumas peças centrais já existem em `src/` e podem puxar a migração:

- `App\Core\Permissions\Support\AccessResolver`
- `App\Core\Menus\Services\MenusService`
- controllers em `src/Modules/*/Http`
- APIs novas em `/adm/api/...`

Além disso, a maior parte das páginas admin novas já conversa com módulos PSR por API.

## O que ainda prende o sistema ao legado

### 1. O layout ainda sobe o runtime antigo

`includes/template/head.php` ainda carrega:

- `../wp/wp-load.php`
- `includes/autoload.php`
- depois `autoload_v2.php`

Isso significa que as telas novas ainda nascem com os globais do legado disponíveis.

### 2. Algumas páginas ainda dependem de objetos globais

Exemplos vistos em `pages/admin`:

- `$TemplateClass`
- `$contratoClass`
- `$contratoSiteClass`
- `$utilClass`
- `$PermissaoClass`

Essas dependências não precisam continuar no layout; elas precisam ser trocadas por serviços mais explícitos.

### 3. A UI compartilhada está espalhada em três padrões

Hoje convivem:

- modais inline dentro da própria página
- modais locais em `pages/admin/modals`
- modais carregados por `TemplateClass->carregarModais(...)`

Isso dificulta saber o que ainda é compartilhado de verdade.

## Proposta de destino por categoria

### A. Bootstrap

Criar uma camada única e pequena para bootstrap de áreas, por exemplo:

- `bootstrap/app.php`
- `bootstrap/admin.php`
- `bootstrap/parceiro.php`
- `bootstrap/cliente.php`

Responsabilidades permitidas:

- carregar WordPress
- registrar autoload PSR
- bind de usuário atual
- contexto de contrato/tenant
- guarda de acesso
- helpers mínimos realmente transversais

Responsabilidades proibidas:

- instanciar dezenas de classes globais
- incluir modais
- incluir widgets
- incluir abas
- montar header visual

### B. Helpers

Separar helpers em três grupos:

1. Permanecem como funções globais por compatibilidade de framework
- helpers pequenos e puros
- ex.: escape, formatação simples, bridge com WP

2. Viram classes estáticas ou serviços em `src/Shared` ou `src/Core`
- contexto
- acesso
- integrações
- resolução de área/tenant

3. Viram helpers locais de tela/área
- coisas usadas só em `pages/admin`
- coisas usadas só em paciente/prontuário/parceiros

Regra prática:

- se depende de banco, usuário, contrato, permissão ou regra de negócio: não deve morar em helper solto
- se só monta HTML reaproveitável da mesma área: deve ficar perto da área

### C. Template/layout

Quebrar `includes/template` em duas partes:

1. Layout base da aplicação
- head
- body-start
- footer
- assets comuns

2. componentes de layout por área
- admin
- parceiro
- cliente

Destino sugerido:

- `pages/shared/layout/`
- `pages/admin/_layout/`
- `pages/parceiro/_layout/`
- `pages/cliente/_layout/`

`TemplateClass` deve ser eliminado aos poucos.

Em especial, estes comportamentos podem sair dele primeiro:

- breadcrumb
- título da página
- carregamento de modais

Os dois primeiros podem virar partials ou render helpers de layout.
O terceiro deve migrar para include explícito da própria área.

### D. Modais, abas, cards, widgets, gráficos

Nem tudo isso precisa ir para `src/`.

Destino recomendado:

- UI específica de admin: `pages/admin/components/`
- UI específica de parceiro: `pages/parceiro/components/`
- UI específica de paciente/prontuário: dentro da própria feature
- visualização reaproveitável e sem regra de negócio: partial PHP local
- gráfico que depende de query/regra: serviço em `src` + partial simples na página

Exemplos de organização:

- `pages/admin/components/modals/`
- `pages/admin/components/cards/`
- `pages/admin/components/widgets/`
- `pages/admin/components/charts/`

Se um widget depender de consulta complexa:

- query/transformação em `src/Modules/.../Services`
- HTML do widget em `pages/admin/components/widgets/...`

### E. Classes legadas de domínio

O caminho não deve ser "mover arquivo de `includes/classes` para `src` e pronto".

O caminho melhor é:

1. descobrir qual módulo atende aquela responsabilidade
2. migrar casos de uso para repository/service/controller em `src`
3. deixar uma bridge temporária só onde a tela ainda exige objeto legado
4. remover a bridge quando a última tela sair

## Estratégia recomendada

### Fase 1. Congelar a expansão da `includes/`

Regra nova:

- nada novo entra em `includes/`
- código novo vai para `src/`, `pages/.../components` ou `assets/...`

### Fase 2. Criar bootstrap novo por área

Antes de apagar qualquer helper, criar uma entrada mínima para admin semelhante ao que já se tentou em `pages/parceiro`, mas sem carregar o legado inteiro por padrão.

Exemplo de alvo:

- `bootstrap/admin.php` resolve usuário, contrato, permissões e contexto
- layout admin usa esse bootstrap
- dependências legadas passam a ser opt-in, não default

### Fase 3. Extrair `TemplateClass`

Prioridade alta porque ele está no meio do layout.

Substituições:

- `criarBreadcrumbMatDash(...)` -> partial ou renderer de layout
- `criarTituloMatDash(...)` -> partial ou renderer de layout
- `carregarModais([...])` -> include explícito de component local

### Fase 4. Remover includes visuais genéricos

Alvos rápidos:

- `includes/modais`
- `includes/widgets`
- `includes/graficos`
- `includes/abas`
- `includes/cards`

Esses itens devem ser relocados por área/feature.

### Fase 5. Reduzir helpers globais

Separar:

- helpers puros que ficam globais por enquanto
- helpers que devem virar serviço
- helpers mortos ou redundantes

### Fase 6. Derrubar `includes/autoload.php` do layout

Só depois que:

- páginas críticas não dependerem mais de `$TemplateClass`
- telas restantes não dependerem de `$contratoClass`, `$PermissaoClass`, `$utilClass` no render
- bridges de runtime estiverem explícitas

## Ordem prática que parece mais segura

1. Criar bootstrap novo do admin
2. Tirar `TemplateClass` do header/body/footer
3. Mover modais compartilhados para `pages/admin/components/modals`
4. Mover widgets/gráficos/abas por domínio
5. Transformar helpers pesados em serviços
6. Só então cortar `includes/autoload.php` do layout

## Leituras do estado atual que ajudam na priorização

Pontos observados no código:

- poucas páginas admin ainda incluem helpers diretamente de `includes/helpers`
- várias telas novas já usam modais inline ou modais locais da própria pasta
- `TemplateClass->carregarModais(...)` aparece em poucos arquivos, o que facilita matar esse ponto cedo
- `pages/parceiro` já sinaliza uma ideia de isolamento físico por área, mas ainda herda runtime legado

## Decisão arquitetural sugerida

Em vez de tentar "migrar a `includes/` inteira para `src/`", tratar a pasta como quatro migrações separadas:

1. bootstrap
2. domínio legado
3. UI compartilhada
4. utilitários

Isso evita dois erros comuns:

- colocar HTML/partials dentro de `src/`
- manter regra de negócio escondida em helper visual

## Próximo passo recomendado

Se formos executar essa limpeza, o melhor primeiro passo é pequeno e reversível:

1. criar um bootstrap novo do admin
2. adaptar `includes/template/head.php`, `body-start.php` e `footer.php` para depender dele
3. extrair o que hoje vem de `TemplateClass`

Depois disso, a `includes/` deixa de ser obrigatória para toda página admin, e a remoção do legado fica muito mais previsível.