README

Personal Financial Control

Sistema desktop para controle de finanças pessoais. Permite registrar receitas e despesas (inclusive parceladas), acompanhar o que está pago e o que está em aberto, e visualizar para onde o dinheiro está indo por meio de gráficos.

É um projeto pessoal, desenvolvido para estudos e também usado no controle das minhas próprias finanças.

🚧 Migração de tecnologia em andamento A versão atual é escrita em Delphi (VCL). O projeto está sendo migrado para JavaScript, em duas aplicações: uma desktop (Electron) e uma web, que compartilham as regras de negócio e a interface. O banco de dados SQLite e as funcionalidades existentes serão mantidos. A maior parte deste README descreve a versão Delphi; a versão nova tem uma seção própria no fim.

Funcionalidades

• Login com cadastro de usuários
• Receitas e despesas com geração automática de parcelas (valor por parcela, data da primeira parcela e quantidade; as demais vencem mês a mês)
• Gerenciar movimentações: busca por descrição, filtros por situação (pago / não pago) e mês, totais de receitas, despesas e saldo, edição, exclusão e baixa de pagamento
• Gráficos de movimentações: receitas e despesas agrupadas por forma de pagamento, categoria e subcategoria, com filtros por situação e por mês ou ano
• Cadastros de apoio:
  • Categorias e subcategorias
  • Tipos de pagamento (ex.: Dinheiro, Pix, Cartão de Crédito), indicando se permitem parcelamento
  • Formas de pagamento (ex.: "Cartão de Crédito NuBank"), com número máximo de parcelas
  • Fornecedores e clientes
  • Cidades (com UF e código SEFAZ)
• Utilitários: limpeza completa da base, recriando os dados padrão (usuário admin/admin, tipos de pagamento e categorias iniciais)

Documentação

Documentação detalhada da versão atual, na pasta docs/:

Tecnologia atual

O código é orientado a objetos: cada entidade tem uma classe com suas operações de banco (inserir, alterar, excluir, buscar). As telas usam herança visual: um formulário base de cadastro (templates/fMasterRegister) define a grade, a busca e os botões, e as telas de cadastro herdam dele.

Estrutura de pastas

PersonalFinancialControl.dpr   Ponto de entrada da aplica????o
fMain.pas / .dfm               Tela principal (menu)
class/                         Classes de dom??nio e acesso a dados, utilit??rios e scripts do banco
interfaces/                    Interface comum de CRUD
templates/                     Formul??rios base (heran??a visual)
forms/                         Telas da aplica????o
dataModules/                   Data modules (conex??o e consulta do relat??rio)
reports/                       Layout do relat??rio (FastReport)
database/                      Banco SQLite (PersonalFinancialControl)
images/                        ??cones da interface

Banco de dados

O banco fica em database/PersonalFinancialControl, ao lado do executável. Na inicialização, a aplicação verifica a estrutura e cria as tabelas que estiverem faltando.

Como executar

1. Abra PersonalFinancialControl.dproj no RAD Studio (com TeeChart e FastReport instalados).
2. Compile para a plataforma Win32.
3. Mantenha as pastas database/ e images/ ao lado do executável gerado e execute.

Versão nova (em desenvolvimento)

A versão nova fica no mesmo repositório, num monorepo com npm workspaces. As regras de negócio e as telas ficam em pacotes compartilhados. Cada aplicação guarda só o que é dela: janela, ponto de entrada e acesso aos dados.

packages/domain/   @pfc/domain: regras de neg??cio em JavaScript puro, com testes
packages/ui/       @pfc/ui: App (componente raiz), telas, componentes, tema e contratos de servi??o
apps/desktop/      aplica????o Electron: processo principal, preload e a entrada que monta o App
apps/web/          aplica????o web (ainda s?? a estrutura de pastas)

Ordem: primeiro o desktop é construído por inteiro; a web vem depois e reaproveita tudo o que está em packages/.

Situação: o desktop abre a janela com o App de @pfc/ui (faixa de título e área vazia, com as cores do sistema) e abre a conexão com o banco, mas as telas ainda não leem dados. Nenhuma tela ou regra foi migrada até agora. O andamento de cada regra está em BUSINESS_RULES.md §11.

Como executar

Requer Node.js 22 ou superior. Todos os comandos rodam na raiz do repositório:

npm install            # instala as dependências de todos os pacotes
npm run db:dev-copy    # cria a cópia do banco usada em desenvolvimento (necessária para abrir o app)
npm run dev:desktop    # abre o app desktop em modo de desenvolvimento
npm run build:desktop  # gera o build de produção do desktop
npm run lint           # verifica o código de todo o monorepo (ESLint)
npm run format         # formata apps/ e packages/ (Prettier)
npm test               # roda os testes das regras de negócio

Autor

Desenvolvido por Vagner Silva de Oliveira.