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

```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`).