Skip to content

GitLab

API · Changes

Page history
Create API authored by Lucas Aquino Brentano's avatar Lucas Aquino Brentano
Hide whitespace changes
Inline Side-by-side
API.md 0 → 100644
View page @ fff17de4
# Taskee Backend API - Documentação Técnica
## Visão Geral
API REST desenvolvida com **FastAPI** para gerenciamento de eventos gamificados, tarefas, atividades e ranking de participantes. Utiliza **Firebase Authentication** para autenticação e **Cloud Firestore** como banco de dados NoSQL.
**URL Base**: `http://localhost:8000`
**Documentação Interativa**: `http://localhost:8000/docs`
---
## Arquitetura
### Stack Tecnológica
- **Framework**: FastAPI
- **Autenticação**: Firebase Authentication (JWT)
- **Banco de Dados**: Cloud Firestore (NoSQL)
- **Storage**: Firebase Storage
- **Testes**: Pytest (31 arquivos de teste)
- **Containerização**: Docker + Docker Compose
### Padrão Arquitetural
```
app/
├── controllers/ # Endpoints HTTP (rotas)
├── services/ # Lógica de negócio
├── models/ # Modelos de dados (Pydantic)
├── schemas/ # Validação de entrada/saída
├── dependencies/ # Injeção de dependências (Firebase, Auth)
└── utils/ # Funções auxiliares
```
---
## Autenticação e Autorização
### Níveis de Segurança
| Nível | Descrição | Dependência |
|-------|-----------|-------------|
| **PUBLIC** | Sem autenticação | Nenhuma |
| **AUTHENTICATED** | Requer token Firebase válido | `get_current_user_firebase` |
| **ADMIN** | Requer `is_admin=true` | `require_admin_firebase` |
### Fluxo de Autenticação
1. Frontend faz login via Firebase Client SDK (`signInWithEmailAndPassword`)
2. Obtém ID Token com `getIdToken()`
3. Envia token para `/firebase-auth/verify` (validação backend)
4. Backend valida token e retorna dados do usuário
### Controle de Plataforma
- **Web Dashboard**: Somente admins (`is_admin=true`)
- **Mobile App**: Todos usuários ativos
---
## Recursos e Endpoints
### 1. Account Management (Público)
**Prefixo**: `/account`
| Método | Endpoint | Descrição |
|--------|----------|-----------|
| POST | `/signup` | Criar conta Firebase Auth |
| DELETE | `/delete-account` | Deletar conta permanentemente |
| DELETE | `/soft-delete-account` | Deletar conta logicamente |
**Nota**: Login é feito no frontend via Firebase SDK.
---
### 2. Firebase Authentication (Público)
**Prefixo**: `/firebase-auth`
| Método | Endpoint | Descrição |
|--------|----------|-----------|
| POST | `/verify` | Validar token Firebase e sincronizar usuário |
| POST | `/logout` | Logout (invalidar token) |
**Validação de Plataforma**:
```json
{
"firebase_token": "eyJhbG...",
"platform": "web" // ou "mobile"
}
```
---
### 3. Password Management (Público)
**Prefixo**: `/password`
| Método | Endpoint | Descrição |
|--------|----------|-----------|
| POST | `/reset/request` | Solicitar reset de senha (email com token válido por 1h) |
---
### 4. Users (Autenticado)
**Prefixo**: `/users`
| Método | Endpoint | Descrição | Acesso |
|--------|----------|-----------|--------|
| POST | `/create` | Criar usuário (com Firebase UID) | Admin |
| POST | `/create-with-firebase` | Criar usuário + Firebase Auth | Admin |
| GET | `/` | Listar todos usuários | Admin |
| GET | `/{user_id}` | Buscar por ID | Autenticado |
| GET | `/uuid/{uuid}` | Buscar por UUID | Autenticado |
| GET | `/email/{email}` | Buscar por email | Autenticado |
| PUT | `/{user_id}` | Atualizar perfil (próprio ou admin) | Autenticado |
| DELETE | `/{user_id}` | Deletar do Firestore | Admin |
| DELETE | `/{user_id}/complete` | Deletar Firebase Auth + Firestore | Autenticado |
**Modelo User**:
```python
{
"id": str,
"firebase_uid": str,
"name": str,
"email": str,
"birth_date": datetime,
"phone_number": str,
"city": str,
"state": str,
"country": str,
"gender": UserGender,
"is_active": bool,
"is_admin": bool
}
```
---
### 5. Events (Autenticado)
**Prefixo**: `/events`
| Método | Endpoint | Descrição | Acesso |
|--------|----------|-----------|--------|
| POST | `/create` | Criar evento (com upload de banner) | Admin |
| PUT | `/update` | Atualizar evento | Admin |
| GET | `/all` | Listar todos eventos | Público |
| GET | `/my-events` | Eventos do usuário (admin: todos / user: inscritos) | Autenticado |
**Modelo Event**:
```python
{
"id": str,
"title": str,
"description": str,
"access_code": str, # Código de inscrição
"field": str,
"start_date": datetime,
"end_date": datetime,
"type": str, # Feira, Workshop, etc.
"status": str, # ongoing, finished
"is_active": bool,
"customization": {
"primary_color": str,
"secondary_color": str,
"tertiary_color": str,
"font": str,
"icon_url": str,
"banner_url": str
},
"tasks": List[Task],
"activities": List[Activity]
}
```
---
### 6. Tasks (Autenticado)
**Prefixo**: `/tasks`
| Método | Endpoint | Descrição |
|--------|----------|-----------|
| POST | `/create/{event_id}` | Criar tarefa em evento |
| GET | `/all/{event_id}` | Listar tarefas do evento |
| GET | `/{event_id}/{task_id}` | Buscar tarefa específica |
| PUT | `/update/{event_id}/{task_id}` | Atualizar tarefa |
| DELETE | `/delete/{event_id}/{task_id}` | Deletar tarefa |
**Modelo Task**:
```python
{
"id": str,
"title": str,
"description": str,
"task_type": str, # question, quiz, challenge
"task_category": str,
"status": str,
"score": int,
"sequence": int,
"min_char": int, # Mínimo de caracteres para resposta
"question": List[Question], # Para quizzes
"is_active": bool
}
```
---
### 7. Activities (Autenticado)
**Prefixo**: `/events/{event_id}/activities`
| Método | Endpoint | Descrição |
|--------|----------|-----------|
| POST | `/` | Criar atividade (com upload de imagem) |
| GET | `/` | Listar atividades (ativas por padrão) |
| GET | `/{activity_id}` | Buscar atividade específica |
| PUT | `/{activity_id}` | Atualizar atividade |
| DELETE | `/{activity_id}` | Deletar permanentemente |
| DELETE | `/{activity_id}/soft` | Desativar atividade |
| PUT | `/{activity_id}/restore` | Reativar atividade |
**Modelo Activity**:
```python
{
"id": str,
"title": str,
"description": str,
"type": str, # Palestra, Workshop, etc.
"image_url": str,
"start_at": datetime,
"end_at": datetime
}
```
---
### 8. User Tasks (Autenticado)
**Prefixo**: `/user_tasks`
Gerencia respostas de usuários em tarefas.
| Método | Endpoint | Descrição |
|--------|----------|-----------|
| POST | `/upsert/question/{user_id}/{event_id}/{task_id}` | Submeter resposta dissertativa |
| POST | `/upsert/quiz/{user_id}/{event_id}` | Submeter quiz (múltipla escolha) |
| POST | `/upsert/challenge/{user_id}/{event_id}/{task_id}` | Submeter desafio (upload de imagem) |
| GET | `/event/{event_id}/user/{user_id}` | Listar respostas do usuário no evento |
| GET | `/{event_id}` | Listar todas respostas do evento |
| GET | `/{event_id}/task/{task_id}` | Respostas de tarefa específica |
| GET | `/current/{event_id}/{user_id}` | Tarefa atual do usuário |
| GET | `/completion/{event_id}/{user_id}` | Status de conclusão das tarefas |
| PUT | `/evaluate/{user_task_id}` | Avaliar resposta (admin) |
**Modelo UserTask**:
```python
{
"id": str, # {user_id}_{task_id}
"user_id": str,
"task_id": str,
"event_id": str,
"answers": [
{
"user_answer": str,
"is_correct": bool,
"submission_type": SubmissionType, # text, image
"submission_url": str # URL Firebase Storage
}
],
"is_validated": bool,
"score": float
}
```
---
### 9. User Events (Autenticado)
**Prefixo**: `/user_event`
Gerencia inscrições de usuários em eventos.
| Método | Endpoint | Descrição |
|--------|----------|-----------|
| POST | `/register` | Inscrever-se em evento (via código de acesso) |
| GET | `/event/{event_id}/my-registration` | Buscar inscrição do usuário |
| GET | `/my-registrations` | Listar todos eventos inscritos |
**Modelo UserEvent**:
```python
{
"id": str, # {user_id}_{event_id}
"user_id": str,
"event_id": str,
"total_score": int, # Pontuação consolidada
"enrollment_date": datetime
}
```
---
### 10. Ranking (Público)
**Prefixo**: `/ranking`
| Método | Endpoint | Descrição |
|--------|----------|-----------|
| GET | `/{event_id}` | Ranking completo do evento |
| GET | `/{event_id}/user/{user_id}` | Posição específica do usuário |
**Resposta Ranking**:
```python
{
"event_id": str,
"ranks": [
{
"position": int,
"user_id": str,
"name": str,
"total_score": int
}
]
}
```
---
## Serviços
### AccountService
- Criação de usuários no Firebase Auth
- Deleção física e lógica de contas
### FirebaseAuthService
- Validação de tokens JWT
- Controle de acesso por plataforma (web/mobile)
- Atualização de último login
### UserService
- CRUD completo de usuários
- Integração Firebase Auth ↔ Firestore
- Validação de permissões
### EventService
- Gerenciamento de eventos gamificados
- Upload de banners (Firebase Storage)
- Customização de aparência
### TaskService
- CRUD de tarefas (question, quiz, challenge)
- Validação de tipos e categorias
- Sequenciamento de tarefas
### ActivityService
- CRUD de atividades do evento
- Upload de imagens
- Soft delete (desativação)
### UserTaskService
- Submissão de respostas (texto, quiz, imagem)
- Avaliação de respostas (admin)
- Atualização de pontuação no UserEvent
- Validação de respostas de quiz
### UserEventService
- Inscrição em eventos via código de acesso
- Controle de pontuação consolidada
- Listagem de eventos do usuário
### RankingService
- Geração de ranking por evento
- Ordenação por pontuação
- Busca de posição específica
### PasswordService
- Envio de email de reset (token temporário 1h)
---
## Modelos de Dados Principais
### Enumerações
```python
class UserGender(str, Enum):
MALE = "male"
FEMALE = "female"
OTHER = "other"
class SubmissionType(str, Enum):
TEXT = "text"
IMAGE = "image"
```
---
## Testes
### Cobertura
- **Total de arquivos**: 31 testes
- **Estrutura**:
- Controllers: 9 arquivos
- Services: 10 arquivos
- Models: 4 arquivos
- Integrações: 8 arquivos
### Testes por Módulo
| Módulo | Arquivos de Teste |
|--------|-------------------|
| User | `test_user_controller.py`, `test_user_service.py`, `test_user_model.py` |
| Task | `test_task_controller.py`, `test_task.py`, `test_task_validators.py` |
| Event | `test_event_controller.py`, `test_event_service.py` |
| Activity | `test_activity_controller.py`, `test_activity_service_extended.py`, `test_activity.py` |
| UserTask | `test_user_task_controller.py`, `test_user_task_service.py`, `test_user_task_service_extended.py` |
| UserEvent | `test_user_event_controller.py`, `test_user_event_service.py` |
| Auth | `test_firebase_auth_controller.py`, `test_firebase_auth_service.py`, `test_firebase_auth_dependencies.py` |
| Password | `test_password_controller.py`, `test_password_service.py`, `test_password_reset_confirm.py` |
| Ranking | `test_ranking_controller.py`, `test_ranking_service.py` |
| Account | `test_account_controller.py`, `test_account_service.py` |
| Infrastructure | `test_firebase.py`, `test_firebase_storage.py`, `test_main.py`, `test_routes.py` |
### Executar Testes
```bash
# Todos os testes
pytest tests/
# Com cobertura
pytest --cov=app --cov-report=term-missing
# Teste específico
pytest tests/test_user_service.py
```
---
## Configuração e Deploy
### Variáveis de Ambiente
Crie `.env` com:
```env
# Firebase
FIREBASE_CREDENTIALS_PATH=service-account.json
FIREBASE_STORAGE_BUCKET=your-bucket.appspot.com
# API
DEBUG=true
ALLOWED_ORIGINS=http://localhost:5173,https://taskee.work.gd
```
### Instalação Local
```bash
# Criar ambiente virtual
python -m venv .venv
source .venv/bin/activate # Linux/Mac
.venv\Scripts\activate # Windows
# Instalar dependências
pip install -r requirements.txt
# Iniciar servidor
uvicorn app.main:app --reload
```
### Docker
```bash
# Build e Run
docker-compose up --build
# Ou manualmente
docker build -t taskee_backend .
docker run -p 8000:8000 taskee_backend
```
---
## CORS e Segurança
### Origins Permitidas
```python
allow_origins=[
"http://localhost:5173", # Frontend local
"https://taskee.work.gd", # Produção
"https://www.taskee.work.gd"
]
```
### Proteção de Rotas
- **PUBLIC**: Signup, login, reset de senha
- **AUTHENTICATED**: Perfis, eventos, tarefas, atividades
- **ADMIN**: Criação de usuários, gestão completa
---
## Fluxos Principais
### 1. Fluxo de Cadastro e Login
```
1. POST /account/signup (cria Firebase Auth)
2. Frontend: signInWithEmailAndPassword()
3. Frontend: getIdToken()
4. POST /firebase-auth/verify (valida e sincroniza)
→ Retorna dados do usuário + valida plataforma
```
### 2. Fluxo de Inscrição em Evento
```
1. GET /events/all (usuário vê eventos disponíveis)
2. POST /user_event/register (inscreve com access_code)
3. GET /user_event/my-registrations (confirma inscrição)
```
### 3. Fluxo de Resolução de Tarefa
```
1. GET /tasks/all/{event_id} (lista tarefas)
2. POST /user_tasks/upsert/{tipo}/{user_id}/{event_id}/{task_id}
→ Submete resposta (text/quiz/image)
3. Admin: PUT /user_tasks/evaluate/{user_task_id}
→ Avalia e pontua
4. Atualiza automaticamente total_score no UserEvent
5. GET /ranking/{event_id} (visualiza posição)
```
### 4. Fluxo de Ranking
```
1. Usuário completa tarefas → score atualizado em UserEvent
2. GET /ranking/{event_id} → lista ordenada por pontuação
3. GET /ranking/{event_id}/user/{user_id} → posição específica
```
---
## Dependências Principais
```
fastapi # Framework web
firebase-admin # Firebase SDK Python
pydantic[email] # Validação de dados
uvicorn # ASGI server
pytest # Framework de testes
pytest-cov # Cobertura de testes
python-multipart # Upload de arquivos
httpx # Cliente HTTP async
```
---
## Observações Importantes
1. **Login não é feito na API**: Frontend usa Firebase Client SDK
2. **Tokens expiram em 1 hora**: Frontend deve renovar automaticamente
3. **Plataforma web é exclusiva para admins**: Validado em `/firebase-auth/verify`
4. **Pontuação é automática**: Atualizada ao avaliar UserTask (quizzes) ou ao submeter (questões abertas precisam avaliação)
5. **Upload de arquivos**: Banner (events), imagens (activities, challenges) → Firebase Storage
6. **Soft delete**: Activities podem ser desativadas sem perder dados
---
## Suporte e Documentação
- **Swagger UI**: `http://localhost:8000/docs`
- **Repositório**: Estrutura modular com separação clara de responsabilidades
- **Padrão**: Controllers → Services → Firestore (DDD simplificado)