docs: PROJETO.md com visão geral para Claude Design

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
2026-05-26 22:02:33 -03:00
parent 2277f4375d
commit 91ab9c4360
1 changed files with 102 additions and 0 deletions
@@ -0,0 +1,102 @@
+# 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
+
+```bash
+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`).