Skip to content

SETUP.md

Latest commit

 

History

History
261 lines (193 loc) · 5.31 KB

SETUP.md

File metadata and controls

261 lines (193 loc) · 5.31 KB

Setup e Instalação - Gás Mais Barato

Documentação completa para configurar e executar o projeto Next.js 14+ com TypeScript.

📋 Pré-requisitos

  • Node.js: >= 18.17.0
  • npm: >= 9.0.0 (ou yarn/pnpm)
  • Git: Para controle de versão

🚀 Instalação

1. Instalar Dependências

npm install

Isso instalará todas as dependências listadas em package.json:

Produção:

  • Next.js 14+
  • React 18
  • TypeScript
  • Tailwind CSS
  • Lucide Icons
  • csv-parse (para processar dados ANP)

Desenvolvimento:

  • ESLint (linting)
  • Vitest (testes)
  • Testing Library (testes de componentes)

2. Verificar TypeScript

npm run type-check

Isso executa tsc --noEmit para validar tipos sem gerar código compilado.

3. Executar em Desenvolvimento

npm run dev

Abrirá em http://localhost:3000

4. Build de Produção

npm run build
npm start

📁 Estrutura de Arquivos

webapp_gas_mais_barato/
├── app/
│   ├── layout.tsx          # Layout raiz com metadata
│   ├── page.tsx             # Página principal (Server Component)
│   └── globals.css          # Estilos globais Tailwind
├── components/
│   ├── kpi-card.tsx         # Card KPI reutilizável
│   ├── search-bar.tsx       # Barra de busca com autocomplete
│   └── stations-list.tsx    # Lista de postos (tabela/cards)
├── lib/
│   ├── analytics.ts         # Funções puras de BI
│   ├── utils.ts             # cn() para merge de classes
│   └── data/
│       └── csv-processor.ts # Processador CSV com cache
├── types/
│   └── gas.ts               # Interfaces TypeScript
├── data/
│   └── ultimas-4-semanas-glp.csv  # Dados ANP
├── package.json
├── tsconfig.json            # TypeScript strict mode
├── next.config.js           # Configuração Next.js
├── tailwind.config.ts       # Configuração Tailwind
└── .eslintrc.json           # ESLint rules

🔧 Configurações Importantes

TypeScript Strict Mode

O projeto usa TypeScript com strict mode ativado:

{
  "strict": true,
  "noUnusedLocals": true,
  "noUnusedParameters": true,
  "noFallthroughCasesInSwitch": true,
  "noUncheckedIndexedAccess": true,
  "noImplicitReturns": true,
  "noImplicitOverride": true
}

ESLint - Sem any

Regras configuradas para proibir any:

{
  "@typescript-eslint/no-explicit-any": "error"
}

Next.js - Otimizações

  • React Strict Mode: Detecta problemas em desenvolvimento
  • SWC Minify: Minificação otimizada
  • Server Actions: Habilitado para Server Components

🧪 Testes

Executar Testes

npm test

Executar com UI

npm run test:ui

Coverage

npm run test:coverage

📊 Fluxo de Dados

flowchart LR
    CSV[CSV ANP] --> Processor[csv-processor.ts]
    Processor --> Cache[In-Memory Cache 5min]
    Cache --> Analytics[analytics.ts]
    Analytics --> Page[app/page.tsx]
    Page --> Components[KPI Cards + Lista]
Loading

Cache Strategy

  • Cache Duration: 5 minutos
  • Location: In-memory (variável module-level)
  • Invalidação: Automática após timeout ou com clearCache()

🎨 Princípios de Desenvolvimento

1. Type Safety Total

  • Sem any em nenhum lugar
  • Interfaces explícitas para CSV → GasStation
  • Type guards para validação runtime

2. Funções Puras

  • Todas as funções em lib/analytics.ts são puras
  • Sem side effects
  • Testáveis por natureza

3. Tratamento de Erros

  • Validação de inputs com TypeError
  • Try-catch em operações de I/O
  • Fallbacks para dados inválidos

4. Performance

  • Server Components por padrão (sem JS no client desnecessário)
  • Cache de dados CSV
  • Tailwind CSS (CSS otimizado automaticamente)

🔐 Segurança

Headers configurados em next.config.js:

{
  'X-Frame-Options': 'SAMEORIGIN',
  'X-Content-Type-Options': 'nosniff',
  'Referrer-Policy': 'strict-origin-when-cross-origin'
}

🐛 Troubleshooting

Erros de Tipo após Instalação

Se ainda houver erros TypeScript após npm install:

rm -rf node_modules .next
npm install
npm run type-check

Cache não Invalidando

Para limpar o cache manualmente:

import { clearCache } from '@/lib/data/csv-processor';
clearCache();

Problemas com CSV

Verifique encoding:

file -b --mime-encoding data/ultimas-4-semanas-glp.csv
# Deve retornar: utf-8

📈 Métricas de Qualidade

✅ TypeScript: 100% tipado (strict mode) ✅ ESLint: Zero warnings/errors ✅ Build: Zero erros de compilação ✅ Testes: Cobertura > 80% (futuro)

🚢 Deploy

Vercel (Recomendado)

npm install -g vercel
vercel

Docker

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build
CMD ["npm", "start"]

📝 Próximos Passos

  1. Instalar dependências: npm install
  2. Verificar tipos: npm run type-check
  3. Executar dev: npm run dev
  4. Testar build: npm run build
  5. Criar testes: Implementar testes unitários
  6. Deploy: Configurar CI/CD

Última Atualização: 2025-12-26 Versão: 1.0.0 Status: ✅ Pronto para desenvolvimento