Aplicativo web para importar notas e cupons fiscais (PDF/imagem), revisar a extração e acompanhar despesas confirmadas. A leitura dos documentos usa OpenAI Vision quando há chave configurada, com fallback para OCR/heurística local. Feito para rodar numa VPS.

Recursos

Login simples (usuário/senha, hash bcrypt, sessão por cookie assinado).
Upload de PDF/JPG/PNG com confirmação em lote antes de gravar: mostra o número de documentos e o valor total, e destaca itens ilegíveis para correção.
Data ilegível/ausente → 1º dia do mês corrente (regra única compartilhada por IA e cadastro manual).
CRUD completo de documentos (criar, editar, excluir, listar/filtrar).
Dashboard com KPIs, gastos por mês e por fornecedor.
Tema claro/escuro (persistido no navegador).
Banco SQLite (WAL), sem serviço externo.

Stack

FastAPI + Uvicorn · Jinja2 (server-rendered) · SQLite · OpenAI (Vision) com fallback OCR (PyMuPDF + Tesseract) · bcrypt.

Rodar localmente

python -m venv .venv
.venv/Scripts/activate            # Windows;  no Linux/Mac: source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env              # defina ADMIN_PASSWORD e SECRET_KEY
python app.py                     # http://127.0.0.1:8000

Sem OPENAI_API_KEY o app usa OCR/heurística local (o Tesseract precisa estar instalado no sistema para OCR de imagens). Com a chave, a extração usa a IA.

Migrar histórico (opcional)

python scripts/migrate_notas.py   # importa Skill/dados/lernotafiscal.db -> app

Testes

python -m unittest

Deploy em VPS

Guia completo (Ubuntu + systemd + Nginx + HTTPS) em DEPLOY.md.

Estrutura

app/                aplicação FastAPI (config, database, auth, rotas, templates)
app/ai_extraction   extração via OpenAI Vision
app/ingestion       orquestra IA -> fallback OCR local
lernotafiscal/      motor de extração heurística/OCR reutilizado no fallback
scripts/            utilitários (migrate_notas.py)
deploy/             unit systemd + config nginx

Variáveis de ambiente

Veja .env.example. Principais: SECRET_KEY, ADMIN_USERNAME, ADMIN_PASSWORD, OPENAI_API_KEY, OPENAI_MODEL, DB_PATH, MAX_UPLOAD_BYTES, SESSION_HTTPS_ONLY.