SeConectai_Vendas/Etapas/V2/11-frontend-setup-projeto.md

Etapa 11 — Setup do Projeto Frontend

Contexto do projeto

Estou construindo o frontend do SeConectai Vendas — CRM/vendas multi-tenant. O backend (API REST em NestJS) já está pronto, seguindo o schema e as etapas descritas em documentos separados. O frontend consome essa API e tem duas áreas: painel master (/master) e painel tenant (/app).

A arquitetura completa (rotas, breakpoints, tokens de design, estrutura de pastas) está definida no arquivo 10-frontend-schema-arquitetura.md — use esse arquivo como fonte de verdade para tudo que for construído nesta e nas próximas etapas.

Esta é a Etapa 1 de 9 do frontend (numerada como Etapa 11 no conjunto geral do projeto, para não colidir com as 8 etapas do backend). Aqui é só a fundação — nenhuma tela de negócio ainda.

Objetivo desta etapa

Inicializar o projeto Next.js com toda a configuração base: Tailwind com os tokens de design do schema, estrutura de pastas, variáveis de ambiente, lint/format, e uma página inicial validando a conexão com a API do backend.

Tarefas

1. Inicialização do projeto

   • Next.js 14+ com App Router, TypeScript, ESLint já integrado.
   • Configurar Tailwind CSS.
   • Configurar Prettier + regra de integração com ESLint (sem conflito de formatação).

2. Tokens de design

   • Criar styles/tokens.css com todas as CSS variables definidas na seção 6 do schema (--neutral-*, --surface, --danger, --success, --warning, --brand-master, --brand-master-accent, --color-primary com fallback #2563EB).
   • Configurar tailwind.config.ts para expor essas variáveis como cores utilitárias (ex: bg-primary, text-danger), em vez de usar var(--...) espalhado pelo código.
   • Configurar fonte (Inter ou equivalente definida no schema), incluindo font-variant-numeric: tabular-nums disponível como classe utilitária para colunas de valores monetários.

3. Estrutura de pastas

   • Criar exatamente a estrutura de pastas da seção 9 do schema: app/(public)/, app/master/, app/app/, components/ui/, components/layout/, components/domain/, lib/api/, lib/auth/, lib/theme/, lib/validators/, hooks/, styles/.
   • Cada pasta de rota deve existir com um page.tsx placeholder (ex: "Em construção — Etapa X") para validar que o roteamento do mapa de rotas inteiro já resolve sem erro 404, mesmo antes das telas reais existirem.

4. Variáveis de ambiente e cliente HTTP base

   • .env.local.example com NEXT_PUBLIC_API_URL e demais chaves que forem necessárias.
   • Criar lib/api/client.ts: wrapper mínimo sobre fetch (ou axios, justificar a escolha) com base URL configurável, tratamento de erro padronizado (parse de erro da API em formato consistente), e um ponto único de onde o interceptor de refresh token será plugado na Etapa 13 (deixar o gancho pronto, sem implementar auth ainda).

5. Página de diagnóstico

   • Uma rota simples (ex: /diagnostico, pode ser removida depois) que chama GET /health do backend e mostra o resultado — só para confirmar que a integração frontend↔backend está funcionando de ponta a ponta antes de seguir.

6. Qualidade

   • Scripts no package.json: dev, build, start, lint, format.
   • Configurar Husky + lint-staged (ou equivalente) para rodar lint no pre-commit, se fizer sentido para o fluxo do projeto.

Critérios de aceite

• npm run dev sobe o projeto sem erro
• Todas as rotas do mapa de rotas (seção 4 do schema) resolvem, com página placeholder, sem 404
• tokens.css contém todas as variáveis do schema, aplicadas corretamente (inspecionar no DevTools que os valores computados batem)
• Classes utilitárias do Tailwind (bg-primary, text-danger etc) funcionam e refletem os tokens
• /diagnostico mostra o retorno real de GET /health do backend (com o backend rodando local)
• npm run lint roda sem erro
• Estrutura de pastas idêntica à definida na seção 9 do schema de frontend