From 91ab9c4360a758759ec1ff9414acffe33e674d47 Mon Sep 17 00:00:00 2001 From: Mlcarvalho1 Date: Tue, 26 May 2026 22:02:33 -0300 Subject: [PATCH] =?UTF-8?q?docs:=20PROJETO.md=20com=20vis=C3=A3o=20geral?= =?UTF-8?q?=20para=20Claude=20Design?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Sonnet 4.6 --- PROJETO.md | 102 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 102 insertions(+) create mode 100644 PROJETO.md diff --git a/PROJETO.md b/PROJETO.md new file mode 100644 index 0000000..6878f30 --- /dev/null +++ b/PROJETO.md @@ -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`).