ADR-0014 · SSR primeiro, com React Query hidratado e cache nativo do Next

Status: aceito (22/10/2026) — entregue na versão 2.1.0.

Contexto

Todas as páginas do web eram componentes 'use client': o navegador baixava o JavaScript, descobria quem era o usuário (getSession) e só então buscava rascunhos, sacola ou pedidos. Isso gerava telas de “Carregando…” e “Verificando autenticação…”, duas idas à rede antes do conteúdo e o usuário guardado no localStorage. As rotas protegidas dependiam só da presença do cookie (o middleware.ts).

Decisão

1. Páginas são Server Components. Cada page.tsx pré-carrega no servidor as consultas da tela e entrega o estado do TanStack Query hidratado (prefetch() + <HydrateClient>). A interação fica em componentes 'use client' colocados ao lado (*-view.tsx).
2. Uma queryOptions por consulta (lib/query/queries.ts), usada pelo servidor e pelos hooks, para que a chave hidratada seja a mesma que o cliente procura.
3. Sessão validada no servidor pelos layouts protegidos (requireUser/requireAdmin); o proxy.ts vira só uma barreira otimista por cookie.
4. Cache nativo só para dados públicos. Slide show, documentos e ajuda usam o Data Cache do Next (fetch com next.tags, 1 h), invalidado por updateTag quando o admin edita. Dados de usuário: no-store e um QueryClient por requisição.
5. Cliente HTTP e config do React Query em pacote (@moldape/api-client), com fetch nativo, para o editor 3D reutilizar.
6. Fora do escopo: o cache da vetorização do estúdio (vectorization-store, image-cache) ficou como estava, para não mexer no salvamento.

Alternativas consideradas

• Cache Components (cacheComponents + 'use cache'). Exige envolver em Suspense todo acesso a cookies e params e muda a semântica de todas as rotas de uma vez. Adiado: o ganho para dados por usuário é pequeno, e o fetch com tags já cobre o conteúdo público.
• Manter CSR e só trocar o axios. Não resolve as telas de carregamento nem a validação de sessão.

Consequências

• ➕ HTML com dados na primeira resposta; sem “piscar” de usuário vazio.
• ➕ Sessão inválida ou não-admin é barrada antes de gerar qualquer HTML.
• ➕ Login e catálogo não chamam a API a cada visita.
• ➕ Bundle menor (o AuthProvider e os contexts do estúdio só carregam na área do cliente).
• ➖ Toda página protegida é dinâmica (ƒ); o servidor do Next passa a falar com a API — recomenda-se ORDER_LIFECYCLE_INTERNAL_URL na rede interna.
• ➖ Novas telas precisam seguir o padrão page.tsx (servidor) + *-view.tsx (cliente).