Financeiro (Desktop)

Aplicativo desktop Windows (Electron + Vite) para controle financeiro local, com contas a pagar/receber, importacao e exportacao de Excel, lancamentos parciais e auditoria. Opera offline e persiste em SQLite via Prisma.

Principais recursos

• Cadastro de titulos (pagar/receber) e lancamentos.
• Status e saldo calculados (ABERTO, PARCIAL, QUITADO, CANCELADO).
• Atrasado calculado por vencimento (não persiste).
• Importacao idempotente de Excel (dedupe_key).
• Exportacao de Excel com filtros.
• Auditoria imutavel de eventos.
• Backup automatico do banco local.

Stack

• Electron (main process)
• Vite (renderer)
• React + MUI + MUI X DataGrid
• Prisma + SQLite

Requisitos

• Node.js LTS
• Windows (app alvo)

Scripts

• npm run dev: inicia Vite + Electron (dev)
• npm run dist: build do renderer + main + instalador Windows
• npm run prisma:migrate: cria migracao inicial (dev)

Estrutura do projeto

assets/            # icones e assets
prisma/            # schema e migrations
src/
  main/            # Electron main
  renderer/        # UI (React)
  shared/          # tipos e regras

Banco de dados

• SQLite em %APPDATA%/Financeiro/data.db
• Prisma com migrations embarcadas no build.

Backup automatico

Ao iniciar o app:

• copia data.db para %APPDATA%/Financeiro/backups/data-YYYYMMDD-HHMM.db
• mantem os ultimos 30 backups
• se data.db não existir, não cria backup

Recuperacao

Se o banco estiver corrompido/inacessivel:

• o app exibe modal no renderer
• ao confirmar, restaura o ultimo backup e reinicia

Importacao de Excel (idempotente)

• dedupe_key = CNPJ/CPF + Nome + Historico + Vencimento + Valor
• normalizacoes:
  • doc: somente digitos
  • nome: trim + colapsar espacos + uppercase
  • historico: trim + colapsar espacos
  • vencimento: YYYY-MM-DD
  • valor: numero com 2 casas

Regras:

• Se não existir título com dedupe_key: cria título (origin=IMPORT).
• Se existir título: nunca cria lancamento.
• Se título não tem lancamentos ATIVOS: pode atualizar vencimento/valor/criacao.
• Se título tem lancamentos ATIVOS: atualiza apenas dados de pessoa e historico.
• Se Data Pagamento existir e título for novo: cria lancamento automatico (Transferencia/Deposito).

Exportacao de Excel

• Uma aba "Titulos" (1 linha por título)
• Colunas:
  • Tipo
  • Nome
  • CNPJ/CPF
  • Historico
  • Data Criacao
  • Data Vencimento
  • Valor Original
  • Status
  • Atrasado (Sim/Nao)
  • Total Lancado
  • Saldo
  • Data Quitação

Filtros suportados:

• type (PAGAR/RECEBER)
• status
• overdueOnly
• searchText (nome/doc/historico)
• dueDateFrom / dueDateTo

IPC (renderer -> main)

A UI acessa apenas window.financeApi via preload:

• Titulos: create, list, cancel
• Lancamentos: create, list, cancel
• Contas: create, list
• Auditoria: list, listTitleHistory
• Importacao: selectFile, importExcel
• Exportacao: exportExcel
• Sistema: openDataFolder, openBackupsFolder, restoreLatestBackup

Regras de negocio (resumo)

• total_lancado = soma de lancamentos ATIVOS
• saldo = valor_original - total_lancado
• status:
  • CANCELADO tem prioridade
  • saldo <= 0 => QUITADO
  • total_lancado > 0 e saldo > 0 => PARCIAL
  • total_lancado == 0 => ABERTO
• atrasado: status em ABERTO/PARCIAL e vencimento < hoje

UI

• Sidebar + Topbar com busca global
• Paginas: Titulos, Detalhe, Importar, Exportar, Contas
• Confirmacao obrigatoria para cancelamentos (motivo opcional)
• Historico/auditoria visivel no detalhe do título

Como rodar (dev)

1. npm install
2. npm run dev

Como gerar instalador

1. npm run dist
2. Saida em dist/

Validacao rapida

• Criar título, adicionar lancamento, cancelar, ver auditoria.
• Importar Excel e validar idempotencia.
• Exportar Excel e validar colunas.
• Verificar backups em %APPDATA%/Financeiro/backups.

Observacoes

• Fonte de verdade: docs/requisitos.md e PRD.md.
• Nao ha acesso direto ao DB pelo renderer.