FastAPI Study Project - Game to Life API

Este repositório é uma API REST assíncrona construída com FastAPI, SQLAlchemy AsyncSession e SQLite. O projeto serve como uma base para um sistema de gamificação ou tracker de atividades com pontuação (XP) e streaks, esse projeto é feito para fins de estudo.

Objetivo

A API permite gerenciar usuários, autenticação JWT, categorias, atividades, logs de XP, saldos de XP, relacionamentos de usuário-atividade e streaks de produtividade.

Dependências principais

• fastapi - framework web assíncrono
• uvicorn - servidor ASGI
• sqlalchemy - ORM para banco de dados
• aiosqlite - driver SQLite assíncrono
• pydantic - validação de dados
• python-dotenv - carregamento de variáveis de ambiente
• httpx - cliente HTTP assíncrono
• requests - cliente HTTP síncrono
• fastapi_users - autenticação e gerenciamento de usuários

Estrutura do projeto

Game_to_life_API/
├── main.py                    # inicializa o servidor
├── .env                       # variáveis de ambiente (secret, algorithm)
├── requirements.txt           # dependências
├── README.md                  # este arquivo
├── app/
│   ├── app.py                # aplicação FastAPI com todos os endpoints
│   ├── db.py                 # modelos SQLAlchemy e configuração assíncrona
│   ├── schemas.py            # schemas Pydantic para validação
│   ├── users.py              # (gerenciamento de usuários)
│   └── auth/
│       └── auth_handler.py    # geração e validação de tokens JWT
└── test.db                   # banco SQLite gerado localmente

Como usar

1. Ative o ambiente virtual:

& .\.venv\Scripts\Activate.ps1

2. Inicie o servidor:

python main.py

Ou com reload automático:

uvicorn main:app --reload

3. Acesse a documentação interativa:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Endpoints disponíveis

Raiz

• GET / - retorna mensagem de boas-vindas

Autenticação

• POST /login - faz login com email e password, retorna access_token
• POST /auth/jwt/login - rota alternativa de login
• GET /users - lista usuários (⚠️ requer JWT no cabeçalho Authorization: Bearer <token>)

Usuários

• POST /user - cria novo usuário com email, hashed_password e nickname

Categorias

• POST /categories - cria categoria com category_name e category_description
• GET /categories - lista todas as categorias

Atividades

• POST /activities - cria atividade com activity_name, activity_description, difficulty_id e category_id
• GET /activities - lista todas as atividades

XP (Experience Points)

• POST /xplog - cria log de XP com user_id, activity_id e amount
• GET /xplog - lista todos os logs de XP
• POST /xpbalance - cria ou atualiza saldo de XP com user_id e total_xp
• GET /xpbalance - lista todos os saldos de XP

Atividades do usuário

• POST /user_activity - cria relacionamento usuário-atividade com user_id, activity_id, status, started_at e finished_at
• GET /user_activity - lista todas as atividades de usuários

Dificuldade

• POST /difficulty - cria dificuldade com name e xp_multiplier
• GET /difficulty - lista todas as dificuldades

Streaks

• POST /streaks - cria streak com user_id, current_streak, longest_streak e last_activity_date
• GET /streaks - lista todos os streaks

Configuração do JWT

O arquivo .env deve conter:

secret=a_super_secret_key_change_me_fast_:D
algorithm=HS256

Os tokens JWT têm validade de 10 minutos (600 segundos).

Observações importantes

• O banco de dados usado é SQLite local (test.db)
• As tabelas são criadas automaticamente ao iniciar a aplicação
• A autenticação atual compara hashed_password diretamente sem hashing real
• Apenas o endpoint GET /users está protegido por JWT no momento
• Todos os IDs usam UUID (Universal Unique Identifier)
• As operações assíncronas garantem melhor performance em produção

Sugestões de evolução

• ✅ Implementar hashing seguro de senhas (bcrypt, passlib)
• ✅ Adicionar endpoints para atualizar (PUT/PATCH) e excluir (DELETE)
• ✅ Ampliar proteção JWT para mais endpoints
• ✅ Incluir testes automáticos com pytest
• ✅ Migrar para PostgreSQL ou MySQL em produção
• ✅ Adicionar documentação OpenAPI melhorada
• ✅ Implementar rate limiting
• ✅ Adicionar logs estruturados

Status dos testes

✅ Todos os endpoints foram testados e estão funcionando:

• Criação de usuários
• Autenticação JWT
• CRUD de categorias, atividades, dificuldades
• Logs de XP e saldos de XP
• Relacionamentos usuário-atividade
• Streaks

Observações finais

Este projeto é um exemplo prático de backend assíncrono em Python utilizando padrões modernos e serve como base para futuros desenvolvimentos de sistemas de gamificação e rastreamento de produtividade.