carvalho-finances/PROJETO.md

Financeiro Carvalho

O que é

Aplicação web de controle financeiro pessoal, construída como produto de uso diário por Manoel — engenheiro de software, diabético tipo 1, velejador amador e entusiasta de jogos de tabuleiro. O objetivo central é simples: saber exatamente quanto dinheiro entra, quanto sai e confirmar que pelo menos 40% da renda está sendo poupada todo mês.

Proposta de valor

Manoel não queria um app genérico de finanças cheio de funcionalidades que nunca vai usar. Queria algo seu, que reflita sua vida real — com categorias para insulina, para o veleiro e para jogos de tabuleiro — e que tornasse o hábito de registrar gastos prazeroso, não tedioso.

A solução mistura controle financeiro sério com gamificação RPG: cada ação financeira (importar extrato, categorizar transações, atingir a meta de 40%) rende XP e faz o personagem pixel art evoluir. Quests diárias, semanais e mensais traduzem bons hábitos financeiros em objetivos concretos de jogo.

Funcionalidades

Controle financeiro

• Import de extratos — upload de OFX (formato bancário brasileiro) ou CSV, com prévia antes de confirmar e deduplicação automática na reimportação
• Transações manuais — registro de gastos e receitas avulsos com data, valor, descrição e categoria
• Recorrências fixas — cadastro de custos mensais fixos (plano de saúde, streaming, etc.) com alerta quando não aparecem no mês
• Contas bancárias — CRUD de contas (corrente, poupança, investimento, cartão) com saldo calculado automaticamente pelas transações vinculadas
• Categorias personalizadas — pré-populadas com perfil do Manoel; editáveis e extensíveis

Dashboard

• Widget de % poupado no mês — verde se ≥ 40%, vermelho se abaixo
• Gastos por categoria — barras horizontais com cores por categoria
• Evolução mensal — gráfico de barras dos últimos 6 meses (receitas vs. gastos)
• Transações recentes — últimas 10 movimentações
• Patrimônio total — soma dos saldos de todas as contas cadastradas
• Widget do personagem — prévia do personagem com barra de XP, link para /personagem
• Navegação entre meses
• Alerta de recorrências sem cobertura

Gamificação RPG

• Personagem pixel art — humanoid SVG com animação idle/celebrate, cores controladas pelos cosméticos equipados
• Sistema XP — cada ação financeira rende pontos (categorizar transação = +10 XP, importar extrato = +50 XP, atingir meta 40% = +200 XP)
• Levels com limiar crescente: level × level × 100 XP (nível 1 → 100 XP, nível 2 → 400, nível 3 → 900...)
• Quests diárias, semanais e mensais com objetivos financeiros reais e recompensa XP
• Achievements — 11 conquistas por milestones (primeira transação, primeiro import, 3 meses acima de 40%, "Veleirista Econômico" com gastos de veleiro abaixo de R$500...)
• Cosméticos desbloqueados automaticamente por nível — cabelo, camisa, calças, sapatos
• Tela /personagem com painel completo: personagem, barra XP, quests ativas, todas as conquistas, cosméticos disponíveis

Stack técnica

Camada	Tecnologia
Backend	Go 1.23, chi router, pgx/v5
Frontend	Vue 3, Vite, TypeScript, Pinia, Vue Router
Banco	PostgreSQL 16
Deploy	Docker multi-stage, binário único ~25 MB com assets Vue embarcados
Infraestrutura	Dokploy (self-hosted)

Estrutura do projeto

financeiro-carvalho/
├── apps/
│   ├── api/            # Backend Go
│   │   ├── cmd/server/ # Entrypoint
│   │   ├── internal/
│   │   │   ├── handler/     # HTTP handlers
│   │   │   ├── service/     # Regras de negócio + testes
│   │   │   ├── repository/  # Queries SQL
│   │   │   ├── model/       # Structs compartilhadas
│   │   │   └── migration/   # 8 migrations SQL idempotentes
│   │   └── static/     # Vue dist embarcado via //go:embed
│   └── web/            # Frontend Vue 3
│       └── src/
│           ├── views/       # Páginas (Home, Transações, Contas, Personagem...)
│           ├── stores/      # Pinia (dashboard, game, accounts, transactions...)
│           └── components/  # CharacterWidget, XPBar
├── Dockerfile          # Multi-stage: Node (Vue build) → Go (binary) → Alpine
└── docker-compose.yml  # app + postgres

Telas

Rota	Descrição
/	Dashboard mensal com todos os widgets
/transacoes	Lista e CRUD de transações manuais
/importar	Upload e revisão de extratos OFX/CSV
/categorias	Gerenciamento de categorias
/recorrencias	Custos fixos mensais
/contas	Contas bancárias e patrimônio
/personagem	Painel RPG completo
/configuracoes	Configurações gerais

Rodar localmente

docker compose up --build
# Acesse http://localhost:8080

Variáveis de ambiente (opcionais, têm defaults para desenvolvimento):

• POSTGRES_PASSWORD — senha do banco (default: financeiro)
• APP_PORT — porta exposta (default: 8080)

Identidade visual e tom

O app é pessoal, não corporativo. O personagem pixel art e a gamificação traduzem a ideia de que finanças podem ser um hábito divertido, não uma obrigação ansiosa. As cores do personagem evoluem com o nível — recompensa visual por consistência financeira real.

Paleta principal: fundo claro (#f8fafc), texto escuro (#1e293b), destaque roxo gamificação (#7c3aed), verde para metas atingidas (#059669), vermelho para gastos/metas não atingidas (#dc2626).