SeConectai_Vendas/Etapas/V2/10-frontend-schema-arquitetura.md

SeConectai Vendas — Schema de Frontend (Web Responsivo)

Este documento define a arquitetura do frontend que vai consumir a API já especificada nas etapas 1–8. Cobre estrutura de telas, navegação, sistema de design e a estratégia de responsividade para funcionar bem tanto em tela de PC quanto em smartphone.

1. Visão geral

Uma única aplicação, com duas áreas autenticadas separadas:

• Área master (/master/...) — seu painel, gestão dos tenants.
• Área tenant (/app/...) — painel que seus clientes usam no dia a dia (vendas, clientes, produtos, alertas).

Ambas consomem a mesma API REST do backend. O layout de cada área é diferente (menu, cores, permissões), mas compartilham o mesmo sistema de design (componentes, tokens, grid responsivo).

2. Stack sugerida

• Next.js 14+ (App Router) + React 18 + TypeScript
• Tailwind CSS para estilos utilitários, com tokens de design via CSS variables (necessário para o whitelabel: cor primária muda por tenant em tempo de execução, não pode ser fixa no build)
• shadcn/ui como base de componentes acessíveis, customizados por cima (não usar como está "fora da caixa" — ajustar aos tokens do projeto)
• TanStack Query (React Query) para cache/estado de dados vindos da API (listagens, dashboards)
• React Hook Form + Zod para formulários e validação — os schemas Zod devem espelhar os DTOs do backend
• Recharts para os gráficos de dashboard (resumo de vendas etc)
• Estado de UI leve (sidebar aberta/fechada, tema) via Context/Zustand — não precisa de Redux para este escopo

3. Estratégia de responsividade

Mobile-first. Breakpoints (padrão Tailwind, manter):

Breakpoint	Largura	Uso principal
base	< 640px	smartphone
sm	≥ 640px	smartphone grande / phablet
md	≥ 768px	tablet
lg	≥ 1024px	desktop
xl	≥ 1280px	desktop grande

Regras de layout por faixa:

• Desktop (lg e acima): sidebar fixa lateral (~240px) + topbar. Conteúdo em grid de 2 colunas quando fizer sentido (ex: formulário + resumo lateral).
• Tablet (md): sidebar colapsada só com ícones (expande em hover ou toque), conteúdo em coluna única ou 2 colunas conforme espaço.
• Mobile (abaixo de md):
  • Sidebar vira drawer (menu lateral que desliza, acionado por ícone de hambúrguer na topbar).
  • Bottom tab bar fixa com os 4–5 itens mais usados de cada área (ex. no tenant: Dashboard, Clientes, Vendas, Recebimentos, Mais).
  • Tabelas não fazem scroll horizontal como solução padrão — cada linha vira um card empilhado (rótulo: valor), com as informações mais importantes em destaque e as secundárias colapsadas/expansíveis.
  • Formulários em coluna única; campos grandes o suficiente para touch (mínimo 44x44px de área de toque).
  • Modais viram tela cheia ou bottom sheet (desliza de baixo), nunca uma caixa pequena centralizada como no desktop.
  • Filtros de listagem (que no desktop ficam visíveis lateralmente) viram um botão "Filtros" que abre um bottom sheet no mobile.

Checklist de teste obrigatório em toda tela construída: 375px (mobile pequeno), 768px (tablet) e 1280px (desktop), sem scroll horizontal indevido em nenhuma delas.

4. Mapa de rotas

Público (sem autenticação)

/login                          → detecta master ou tenant pelo e-mail/domínio
/esqueci-senha
/redefinir-senha/:token

Área master — /master

/master/dashboard
/master/tenants                 (lista)
/master/tenants/novo
/master/tenants/:id             (detalhe, edição, faturas do tenant)
/master/planos
/master/faturas                 (visão consolidada de todas as mensalidades)
/master/evolution-config
/master/alertas/templates
/master/alertas/logs
/master/configuracoes           (perfil do admin master, senha, MFA)

Área tenant — /app

/app/dashboard
/app/clientes                   (lista)
/app/clientes/novo
/app/clientes/:id               (detalhe, contatos, histórico de vendas)
/app/produtos                   (produtos e serviços)
/app/produtos/novo
/app/produtos/:id
/app/vendas                     (lista)
/app/vendas/nova
/app/vendas/:id                 (detalhe, itens, parcelas)
/app/recebimentos               (contas a receber, marcar pago)
/app/whatsapp                   (instâncias Evolution, QR code, status)
/app/email-config
/app/alertas/templates
/app/alertas/logs
/app/equipe                     (usuários do tenant, só para tenant_admin)
/app/perfil                     (logo, cor, dados da empresa)

5. Navegação e layout por área

Desktop:

• Sidebar: logo do tenant (ou logo master) no topo, itens de menu com ícone + label, indicador do item ativo, avatar do usuário + logout no rodapé.
• Topbar: breadcrumb da página atual, sino de notificações (alertas recentes), busca rápida (clientes/vendas).

Mobile:

• Topbar fixa: logo compacta (só o símbolo, não o nome completo) + ícone de menu (drawer) + sino de notificações.
• Drawer: réplica do menu completo da sidebar desktop, ocupa a tela inteira ou 80% da largura.
• Bottom tab bar: 4 itens fixos mais "Mais" (que abre o restante do menu). Ícone + label curto embaixo.

6. Sistema de design (tokens)

Paleta neutra da plataforma (usada em textos, fundos, bordas — igual em master e em todos os tenants):

• --neutral-950: #12141A — texto principal
• --neutral-500: #6B7280 — texto secundário
• --neutral-200: #E5E7EB — bordas
• --neutral-50: #F8F9FB — fundo de página
• --surface: #FFFFFF — fundo de cards/painéis
• --danger: #DC2626 — erros, valores atrasados
• --success: #16A34A — pagos, confirmados
• --warning: #D97706 — pendências, avisos

Cor de marca do painel master (fixa, identidade do SeConectai Vendas): --brand-master: #1E3A5F (azul petróleo escuro) com acento --brand-master-accent: #2DD4BF (verde-água) — usada apenas na área /master.

Cor de marca de cada tenant (dinâmica, whitelabel): variável --color-primary, resolvida em runtime a partir de tenants.cor_primaria (endpoint público de tema, já definido na Etapa 8 do backend) e aplicada via CSS variable no layout de /app. Se o tenant não definiu cor própria, cair para um azul neutro padrão (#2563EB). Validar contraste mínimo (WCAG AA) contra branco antes de aplicar — se a cor escolhida pelo tenant não passar, usar uma versão escurecida automaticamente para texto sobre fundo colorido.

Tipografia: uma família para UI (ex: Inter ou similar, boa legibilidade em telas pequenas e números tabulares para valores monetários) e uso de font-variant-numeric: tabular-nums em qualquer coluna de valores para alinhamento visual em tabelas/cards.

7. Componentes de design system (biblioteca a construir)

Base (components/ui/): Button, Input, Select, DatePicker, Textarea, Table (com variante que vira lista de Cards abaixo do breakpoint md), Modal/Sheet (adaptável tela-cheia no mobile), Toast, Badge/StatusPill (para status de fatura/parcela/venda), Card, Pagination, EmptyState, Skeleton (loading), Tabs, FormField (wrapper de label+erro+input).

Layout (components/layout/): Sidebar, Topbar, Drawer, BottomTabBar, Breadcrumb.

Domínio (components/domain/): ClienteCard, VendaForm, ParcelaRow, ProdutoForm, StatusFaturaBadge, ResumoVendasChart, InstanciaWhatsappCard.

8. Dados e autenticação no client

• TanStack Query para toda chamada de leitura (listagens, dashboards, detalhes), com invalidação automática após mutations (criar/editar/excluir).
• Zod schemas espelhando os DTOs do backend — usados tanto na validação de formulário quanto na tipagem das respostas da API (fonte única de verdade dos tipos no frontend).
• Access token em memória (não em localStorage, para reduzir superfície de XSS); refresh token em cookie httpOnly, setado pelo backend. Interceptor de requisição renova o access token automaticamente em caso de 401 e repete a chamada original.
• Middleware do Next.js protegendo /master/* e /app/*, verificando sessão válida antes de renderizar a página (evita "flash" de conteúdo protegido).
• Tema (cor primária + logo) resolvido no login: chama o endpoint público de tema com o identificador do tenant, aplica as CSS variables antes mesmo do usuário autenticar (tela de login já com a cara do tenant certo).

9. Estrutura de pastas sugerida

frontend/
├── app/
│   ├── (public)/
│   │   ├── login/
│   │   ├── esqueci-senha/
│   │   └── redefinir-senha/[token]/
│   ├── master/
│   │   ├── layout.tsx
│   │   ├── dashboard/
│   │   ├── tenants/
│   │   ├── planos/
│   │   ├── faturas/
│   │   ├── evolution-config/
│   │   └── alertas/
│   └── app/
│       ├── layout.tsx
│       ├── dashboard/
│       ├── clientes/
│       ├── produtos/
│       ├── vendas/
│       ├── recebimentos/
│       ├── whatsapp/
│       ├── email-config/
│       ├── alertas/
│       ├── equipe/
│       └── perfil/
├── components/
│   ├── ui/
│   ├── layout/
│   └── domain/
├── lib/
│   ├── api/             (client HTTP + funções por domínio)
│   ├── auth/
│   ├── theme/
│   └── validators/       (schemas Zod)
├── hooks/
└── styles/
    └── tokens.css        (CSS variables da paleta e tipografia)

10. Checklist de responsividade (aplicar em toda tela nova)

• Testado em 375px, 768px e 1280px sem overflow horizontal indevido
• Tabelas de listagem viram cards empilhados abaixo de md
• Navegação principal acessível via bottom tab bar ou drawer no mobile
• Touch targets ≥ 44x44px em elementos interativos no mobile
• Formulário utilizável com teclado virtual aberto (campo em foco não fica escondido atrás do teclado)
• Modais/diálogos viram tela cheia ou bottom sheet no mobile
• Cor primária dinâmica do tenant aplicada corretamente em botões/links/destaques, com contraste validado
• Foco de teclado visível em todos os elementos interativos (acessibilidade, não só mobile)
• Estados de carregamento (skeleton) e vazio (empty state) tratados em toda listagem