Guia — atenvi-web-admin

Backoffice interno Atenvi em Next.js 15 (App Router). Gestão de tenants, planos SaaS e billing — não é o painel do estabelecimento (isso é atenvi-web, ver atenvi-web.md).

Estrutura de pastas

src/
  app/
    (auth)/
      login/
    (dashboard)/
      layout.tsx
      tenants/
        page.tsx
        loading.tsx
        error.tsx
      plans/
      billing/
  components/       ← componentes locais do backoffice
  hooks/
  lib/
    api/            ← funções de fetch para TanStack Query
    utils/
  stores/           ← Zustand stores
  types/

Regras Next.js

Server Components por padrão — 'use client' apenas quando necessário (interação, estado)
Dados em Server Components via fetch direto ao atenvi-bff (sem TanStack Query no servidor)
TanStack Query apenas em Client Components para dados interativos/reativos
Loading UI com loading.tsx e Error boundary com error.tsx por rota

TanStack Query

Query keys: ['<resource>', <id>?] → ['tenants'], ['tenants', tenantId]
Funções de fetch centralizadas em src/lib/api/
Sem lógica de fetch inline em componentes

Zustand

Store por domínio de UI: useLayoutStore (sidebar, tema), useFilterStore
Sem server state no Zustand — apenas estado de UI

Componentes

Componentes de negócio locais em src/components/
Primitivos de UI via atenvi-ui e shadcn/ui — sem reimplementação

Escopo (P0 do MVP)

Criação/edição de tenant (provisiona schema via atenvi-bff)
Gestão de planos SaaS (limites, preços)
Billing: acompanhamento de assinatura/cobrança por tenant
Configuração de gateway de pagamento em nome do tenant (aba de plugins, ver docs/business.md F6)

CRUD completo de planos/billing pode esperar o tenant piloto validar — no P0 fino, provisionar tenant pode começar como seed/script no atenvi-bff em vez de UI completa aqui.