🎯 Desafio Técnico - Sistema de Gerenciamento de Voluntários

📋 Sobre o Desafio

Você deve criar uma API REST usando FastAPI para gerenciar o cadastro de voluntários em uma organização. Este desafio avaliará seus conhecimentos básicos em FastAPI, Pydantic e desenvolvimento de APIs.

⏱️ Prazo de Entrega

10 dias a partir do recebimento deste desafio

🚨 REQUISITO OBRIGATÓRIO: USO DO POETRY

📦 Gerenciamento de Dependências

É obrigatório o uso do Poetry para gerenciar as dependências e ambiente do projeto. Esta é uma habilidade essencial que será avaliada.

🎯 Objetivo

Desenvolver um sistema CRUD (Create, Read, Update, Delete) para cadastrar e gerenciar voluntários com os seguintes campos:

• nome (obrigatório)
• email (obrigatório, único)
• telefone (obrigatório)
• cargo_pretendido (obrigatório)
• disponibilidade (opções fixas)
• status (controle de estado)

🚀 Requisitos Técnicos

1. Estrutura da API

Endpoints obrigatórios:

POST   /voluntarios     - Cadastrar novo voluntário
GET    /voluntarios     - Listar voluntários (com filtros)
GET    /voluntarios/{id} - Buscar voluntário específico
PUT    /voluntarios/{id} - Atualizar voluntário
DELETE /voluntarios/{id} - Excluir voluntário (soft delete)

2. Funcionalidades

• ✅ Validação de email único (não permitir duplicatas)
• ✅ Data de inscrição automática
• ✅ Soft delete (marcar como inativo em vez de excluir)
• ✅ Filtros por status, cargo e disponibilidade
• ✅ Validações básicas nos campos

🔧 CONFIGURAÇÃO OBRIGATÓRIA COM POETRY

1. Pré-requisitos

# Instale o Poetry se não tiver
curl -sSL https://install.python-poetry.org | python3 -
# ou
pip install poetry

2. Configuração do Projeto

# Clone ou crie a estrutura do projeto

# Instale as dependências usando Poetry (OBRIGATÓRIO)
poetry install

# Ative o ambiente virtual
poetry shell

# Ou execute comandos diretamente no ambiente do Poetry
poetry run python --version

3. Comandos Essenciais do Poetry

# Executar a aplicação
poetry run task run

# Executar testes
poetry run task test

# Verificar linting
poetry run task lint

# Formatar código
poetry run task format

4. Estrutura Esperada do pyproject.toml

Seu projeto deve manter a estrutura base do pyproject.toml fornecida, com as dependências corretas.

📁 Estrutura do Projeto

api-certify/
├── main.py                 # Arquivo principal da aplicação
├── test_main.py           # Testes (opcional, mas desejável)
├── pyproject.toml         # Dependências (JÁ CONFIGURADO - usar Poetry)
└── README.md              # Instruções de execução

✅ Critérios de Avaliação

Avaliação Técnica (80% da nota)

Obrigatórios (50% da nota)

• Uso correto do Poetry para gerenciar dependências
• CRUD completo funcionando
• Validação de email único
• Campos obrigatórios validados
• Soft delete implementado

Diferenciais (30% da nota)

• Filtros funcionando corretamente
• Tratamento adequado de erros (404, 400, 409)
• Testes básicos implementados
• Documentação clara nos endpoints
• Uso correto de enums para validação

Avaliação de Boas Práticas (20% da nota)

• Código organizado e legível
• Commits frequentes e descritivos
• README claro e completo
• Configuração correta do ambiente com Poetry

🧪 Testes Esperados

Escreva pelo menos 2 testes básicos para validar sua implementação:

# Exemplos de testes esperados
def test_criar_voluntario_valido():
    """Deve criar voluntário com dados válidos"""
    pass

def test_nao_permitir_email_duplicado():
    """Não deve permitir cadastro com email duplicado"""
    pass

📤 Como Entregar

1. Repositório Git (OBRIGATÓRIO)

• Crie um repositório Git (GitHub, GitLab, etc.)
• Commits frequentes mostrando evolução
• README.md com instruções de execução usando Poetry

2. Documentação Obrigatória

Inclua no README:

• Como executar o projeto usando Poetry
• Endpoints disponíveis
• Exemplos de uso
• Decisões técnicas importantes

3. Link de Entrega

Envie para: claudiosilva.one@gmail.com

• Link do repositório Git
• Qualquer observação importante
• E preencha o Forms de Entrega de Desafio : https://forms.gle/Rpj82v33CoB8tRea8

🆘 Dicas Importantes

Foque no Básico:

• Poetry é obrigatório - mostre que sabe usar
• FastAPI + Pydantic são o core
• Não precisa de autenticação complexa
• Use "fake DB" (lista/dicionário) se preferir
• Mantenha a simplicidade

O que Avaliamos:

• ✅ Uso correto do Poetry
• ✅ Lógica de programação
• ✅ Conhecimento FastAPI básico
• ✅ Validações com Pydantic
• ✅ Qualidade e organização do código
• ✅ Capacidade de seguir especificações

Dúvidas Comuns:

• Poetry: Se tiver dificuldade, documente no README
• Banco de dados: Pode usar lista em memória
• Autenticação: Não é necessária
• Deploy: Não é necessário, apenas local
• Frontend: Apenas backend

⏰ Cronograma Sugerido

Dias	Atividade
1-2	Configuração do Poetry e ambiente
3-6	Desenvolvimento dos endpoints
7-8	Validações e tratamentos de erro
9	Testes e documentação
10	Revisão final e entrega

❗ IMPORTANTE: AVALIAÇÃO DO POETRY

Serão avaliados especificamente:

• ✅ Instalação correta das dependências com poetry install
• ✅ Uso do ambiente virtual do Poetry
• ✅ Execução dos comandos via poetry run
• ✅ Estrutura correta do pyproject.toml

Projetos que não utilizarem Poetry serão desconsiderados.

---

Boa sorte! 🚀 Esperamos ver sua capacidade de criar uma API funcional e bem estruturada com FastAPI e gerenciar dependências corretamente com Poetry.