Arquitetura e Boas Práticas do Front-end (React)

Este documento estabelece as regras canônicas de arquitetura para este projeto. Qualquer Inteligência Artificial ou desenvolvedor que atuar neste código DEVE ler e seguir estas diretrizes rigorosamente.

O objetivo desta arquitetura é manter o ecossistema React amigável para desenvolvedores com mentalidade de Backend, priorizando a Separação de Conceitos (Separation of Concerns) e a previsibilidade dos dados.

1. A API é a Única Fonte da Verdade (Fim dos Mocks)

Regra: Não crie, não mantenha e não faça fallback para dados mockados (falsos) em produção ou na integração.
Motivo: O banco de dados (Supabase) dita as regras. Se a API falhar, o front-end deve exibir um estado de erro elegante, e não mascarar a falha com dados locais inventados.
Ação: Repositórios (*Repository.js) devem apenas fazer o fetch seguro para a API e repassar a resposta.

2. O Padrão MVC Adaptado (Model-View-Hook)

Para evitar que as Páginas (*Page.jsx) se tornem "Componentes Deuses" (fazendo requisições, filtrando dados e renderizando HTML ao mesmo tempo), adotamos o seguinte fluxo:

A. Repositório (Acesso a Dados)

Fica na pasta src/repositories/.
Sua ÚNICA função é bater na API, tratar erros HTTP e devolver o JSON puro (Array ou Objeto).
Não deve conter regras de negócio, filtragem de tela ou formatação de datas.

B. Mappers (Tradução Estrita)

Fica na pasta src/mappers/.
Traduz os dados do banco para o formato que a UI espera.
Regra de Ouro: O Mapper deve ser rígido. Se o banco retorna full_name, o mapper converte para name e todo o resto da aplicação usa apenas name. Não propague a bagunça do banco para a tela.

C. Custom Hooks (O Controlador)

Fica na pasta src/hooks/ (ex: useAgenda.js).
Puxa os dados do repositório, passa pelo mapper, controla os estados de loading, error, e lida com a lógica de negócio (como submissão de formulários e filtragem de abas).
Ele encapsula todos os useEffect e useState complexos.

D. Páginas e Componentes (A View Burra)

Fica em src/pages/ e src/components/.
As páginas são estritamente cascas visuais (HTML/Tailwind).
Elas importam o Custom Hook, pegam as variáveis prontas e apenas decidem como desenhar isso na tela.

3. Lidar com Datas (Fuso Horário)

Sempre que a API enviar uma data no formato string YYYY-MM-DD, lembre-se que o construtor nativo do JavaScript (new Date('YYYY-MM-DD')) converte para o horário UTC e, dependendo do fuso do usuário, pode jogar a data para o dia anterior.
Solução: Use o helper local parseLocalDate ou processe os componentes da data (ano, mês, dia) manualmente antes de criar o objeto Date.

Exemplo de Fluxo Ideal

A página PacientesPage.jsx chama o hook const { pacientes, loading } = usePacientes().
O hook usePacientes chama o patientRepository.getAll().
O repositório faz fetch na API.
O hook pega o resultado, passa no patientMapper.toUi() e atualiza o estado interno.
A página renderiza os dados que chegaram do hook.

3.1 KiB Raw Permalink Blame History