GeraFinance API 💰

Sistema de gerenciamento financeiro pessoal com foco em alta segurança.

---

🛠️ Tecnologias

Camada	Tecnologia
Framework	FastAPI
ORM	SQLAlchemy 2.0 (async)
Banco de dados	MySQL 8.0
Migrações	Alembic
Cache / Rate Limiter	Redis
Filas assíncronas	Celery
Autenticação	JWT RS256 (python-jose)
Hash de senha	Argon2id (passlib)
Criptografia	AES-256-GCM (cryptography)
2FA	TOTP (pyotp)
Frontend	React 18 + TypeScript
Gerenciador de dependências	Poetry

---

📁 Estrutura do Projeto

gerfinance_api/
├── app/
│   ├── core/          # Configurações, segurança, dependências
│   ├── models/        # Modelos SQLAlchemy
│   ├── schemas/       # Schemas Pydantic
│   ├── routers/       # Rotas FastAPI
│   ├── services/      # Lógica de negócio
│   └── tasks/         # Tasks Celery
├── alembic/           # Migrações do banco
├── tests/             # Testes automatizados
├── pyproject.toml     # Dependências e configurações
└── poetry.lock        # Lock file das dependências

---

⚙️ Configuração do Ambiente

Pré-requisitos

• Python 3.14+
• Poetry
• MySQL 8.0
• Redis

Instalação

# 1. Clone o repositório
git clone https://github.com/seu-usuario/gerfinance_api.git
cd gerfinance_api

# 2. Instale as dependências
poetry install --no-root

# 3. Ative o ambiente virtual
poetry env activate

Variáveis de ambiente

Crie um arquivo .env na raiz do projeto:

DATABASE_URL=mysql+aiomysql://usuario:senha@localhost:3306/gerfinance
REDIS_URL=redis://localhost:6379
SECRET_KEY=sua_chave_secreta
# Uma origem, várias separadas por vírgula, ou uma lista em JSON:
ALLOWED_ORIGINS=http://localhost:5173

Migrações

Rodando via Docker Compose, as migrações já são aplicadas automaticamente: o serviço migrate roda alembic upgrade head uma única vez (restart: "no") antes de api e worker subirem (depends_on: migrate: condition: service_completed_successfully) — não precisa de nenhum passo manual, nem em ambiente novo (volume do MySQL vazio) nem em restart normal (alembic upgrade head é idempotente, não faz nada se já estiver na revisão mais recente).

Rodando fora do Docker (Poetry local), aplique manualmente:

# Aplicar migrações
alembic upgrade head

# Criar nova migração
alembic revision --autogenerate -m "descricao"

---

▶️ Rodando o projeto

# Servidor de desenvolvimento
fastapi dev app/main.py

# Worker Celery (broker/backend = REDIS_URL)
celery -A app.tasks worker --loglevel=info

Rodando via docker compose up, o worker já sobe junto (serviço worker no docker-compose.yml, mesma imagem da API) — o comando acima só é necessário para rodar o worker manualmente fora do Docker.

Acesse a documentação da API em: http://localhost:8000/docs

---

🔒 Segurança

• Senhas protegidas com Argon2id
• Dados sensíveis criptografados com AES-256-GCM
• Autenticação via JWT RS256, com refresh token e rotação: cada POST /auth/refresh bem-sucedido blacklista o refresh token usado (Redis) e devolve um novo — reapresentar um refresh token já rotacionado ou já deslogado (POST /auth/logout) retorna 401.
• 2FA com TOTP (compatível com Google Authenticator): POST /auth/2fa/setup, /auth/2fa/verify, /auth/2fa/disable. Quando ativo, POST /auth/login retorna um two_factor_token de curta duração em vez do par de tokens; troque-o por um TokenPair em POST /auth/2fa/login junto com o código TOTP atual.
• Rate limiting com Redis em /auth/login e /auth/register (5 tentativas/minuto por IP, resposta 429)

---

⚙️ Tasks assíncronas (Celery)

• app/tasks/notifications.high_value_transaction_alert: disparada automaticamente ao criar uma transação com valor acima de HIGH_VALUE_TRANSACTION_THRESHOLD (R$ 5.000,00). Sempre loga o alerta (auditoria completa); se SMTP_HOST, SMTP_FROM e NOTIFY_TO estiverem configurados, também envia um e-mail (via smtplib, biblioteca padrão — nenhuma dependência nova) para o endereço fixo de monitoramento em NOTIFY_TO, não para o e-mail do usuário dono da transação (mantém a task simples, sem precisar acessar o banco a partir do worker). Falha no envio (SMTP fora do ar, por exemplo) é logada, não interrompe a task.
• Throttle por usuário (HIGH_VALUE_ALERT_THROTTLE_SECONDS, padrão 900s/15min): no máximo 1 e-mail por usuário por janela. Transações altas extras dentro da janela não geram e-mail — só incrementam um contador no Redis; quando a próxima janela abre, o e-mail menciona quantas transações foram agrupadas desde o último alerta enviado.
• O dispatch é best-effort: se o broker (Redis) estiver indisponível, a criação da transação não falha por causa disso.

---

✅ CI

.github/workflows/ci.yml roda em todo push/PR: sobe MySQL e Redis reais como service containers, aplica as migrations do Alembic contra o MySQL do CI, roda a suíte unitária normal (pytest, sem infra real — SQLite em memória + FakeRedis) e, por fim, sobe um worker Celery real e roda um teste de integração ponta a ponta contra o Redis do CI (tests/integration/test_celery_e2e.py).

Esse teste de integração é marcado @pytest.mark.integration e fica de fora da execução local padrão (addopts em pyproject.toml já exclui -m integration) — pytest sozinho nunca tenta subir um worker de verdade. Para rodá-lo localmente: suba um Redis (docker run -p 6379:6379 redis:7), um worker (celery -A app.tasks worker --loglevel=info) e então pytest -m integration.

---

👩‍💻 Autora

Bruna — brunadevs@yahoo.com