NFPlan

Controle seus gastos com a Nota Fiscal Paulista

🌐 Acessar app · 🐛 Reportar bug

---

✨ O que é

NFPlan é um app web gratuito para escanear QR codes da Nota Fiscal Paulista (NFC-e) e acompanhar seus gastos automaticamente. Basta apontar a câmera do celular para o QR code da nota fiscal — o app extrai todos os dados (estabelecimento, itens, valores, data) e organiza tudo em um dashboard visual.

💡 100% gratuito, código aberto e sem anúncios.

---

🖼️ Screenshots

Scanner	Dashboard	Detalhes da Nota

---

🚀 Funcionalidades

📷 Scanner de QR Code	Use a câmera ou envie uma foto para escanear a NFC-e
🔗 Importação por URL	Cole o link da nota manualmente
🤖 Scraping automático	Extrai dados da SEFAZ sem digitar nada
🏷️ Categorização inteligente	Classifica automaticamente por tipo de estabelecimento (supermercado, farmácia, etc.)
📊 Dashboard de gastos	Gráficos por categoria, evolução diária e controle de orçamento mensal
📅 Filtro por mês	Visualize notas e análises de qualquer período
🌙 Dark mode	Tema claro/escuro com persistência e suporte ao tema do sistema
📲 PWA	Instale como app nativo no celular (iOS/Android)
🕐 Timezone Brasil	Todas as datas em UTC-3 (America/Sao_Paulo)
🔒 Privacidade	Row Level Security — cada usuário vê apenas suas próprias notas

---

🛠️ Tech Stack

Camada	Tecnologia
Framework	Next.js 16 (App Router)
Frontend	React 19, Tailwind CSS 4
Linguagem	TypeScript 5
Backend	Supabase — Auth + PostgreSQL
Gráficos	Recharts
QR Code	html5-qrcode
Scraping	Axios + Cheerio
Testes	Jest + React Testing Library

---

📦 Instalação

1. Clone o repositório

git clone https://github.com/seu-usuario/nfplan.git
cd nfplan

2. Instale as dependências

npm install

3. Configure as variáveis de ambiente

Copie o arquivo de exemplo de variáveis de ambiente:

cp .env.example .env

Abra o arquivo .env e configure as chaves:

NEXT_PUBLIC_SUPABASE_URL=https://seu-projeto.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=sua-chave-anon-publica
SUPABASE_SERVICE_ROLE_KEY=sua-chave-service-role-privada
NEXT_PUBLIC_TURNSTILE_SITE_KEY=1x00000000000000000000AA

🔑 Crie um projeto gratuito em supabase.com para obter as credenciais em Project Settings → API. 🛡️ A variável NEXT_PUBLIC_TURNSTILE_SITE_KEY está configurada com a chave pública de testes do Cloudflare Turnstile. Para produção, gere suas próprias chaves no painel da Cloudflare e configure a Site Key na Vercel e a Secret Key nas configurações de Autenticação do Supabase.

4. Configure o banco de dados

No SQL Editor do Supabase Dashboard, execute as migrations em:

specs/001-supabase-auth-analytics/quickstart.md

5. Rode o app

# Desenvolvimento
npm run dev

# Testes
npm test

# Verificação completa (lint + testes + build)
npm run verify

Acesse http://localhost:3000.

💡 Para testar a câmera no celular, acesse pelo IP local da máquina na mesma rede Wi-Fi, ou use ngrok.

---

📱 PWA

O NFPlan é um Progressive Web App. Para instalar:

• Android (Chrome): Menu → "Adicionar à tela inicial"
• iOS (Safari): Compartilhar → "Adicionar à Tela de Início"
• Desktop (Chrome/Edge): Ícone de instalação na barra de endereço

---

📁 Estrutura do Projeto

app/
  api/                      # API Routes (Next.js)
    nfce/route.ts           # Scraping da NFC-e
    invoices/route.ts       # CRUD de notas fiscais
    analytics/route.ts      # Dados para gráficos
    budget/route.ts         # Orçamento mensal
    auth/callback/route.ts  # Callback do Supabase Auth
  components/
    qr-scanner.tsx          # Scanner de QR code
    invoice-modal.tsx       # Modal de detalhes
    theme-provider.tsx      # Contexto de tema
    theme-toggle.tsx        # Toggle claro/escuro
    logo.tsx                # Logo SVG adaptativo
    analytics/              # Gráficos (Recharts)
  lib/
    date.ts                 # Utilitários de data (UTC-3)
    supabase/               # Clientes Supabase
  login/page.tsx            # Tela de login
  signup/page.tsx           # Tela de cadastro
  page.tsx                  # Dashboard principal
  layout.tsx                # Layout raiz + PWA meta tags
public/
  manifest.json             # Manifest do PWA
  icon-*.png                # Ícones do PWA
  logo.svg / logo-mobile.svg
specs/                      # Especificações e documentação

---

🧪 Testes

# Rodar todos os testes
npm test

# Modo watch (desenvolvimento)
npm run test:watch

# Verificação completa antes de commit
npm run verify   # lint + testes + build

---

🤝 Contribuição

Contribuições são bem-vindas! Para reportar bugs ou sugerir funcionalidades, abra uma issue. Para contribuir com código:

1. Fork o projeto
2. Crie uma branch (git checkout -b feat/nome-da-feature)
3. Commit suas mudanças (git commit -m 'feat: descrição')
4. Push para a branch (git push origin feat/nome-da-feature)
5. Abra um Pull Request

⚠️ Rode npm run verify antes de abrir o PR para garantir que lint, testes e build passam.

---

📄 Licença

Distribuído sob a licença MIT. Veja LICENSE para mais informações.

---

Feito com 💜 no Brasil