Desafio Young Guns — Aplicar crédito sem duplicar

Este repositório faz parte do processo seletivo para desenvolvimento backend.

Você vai trabalhar em um pequeno serviço Python que aplica créditos em contas a partir de eventos enviados por um provedor de pagamentos.

O uso de IA é permitido e incentivado (ChatGPT, Copilot, Cursor, Claude, etc.). Você é responsável por todo o código entregue e deve conseguir explicar, testar e modificar sua solução durante a entrevista técnica.

Tempo estimado: 2 a 3 horas.

Contexto

O provedor externo envia eventos como:

event_id = "evt-abc123"   # identificador estável do evento
account_id = "acc-42"     # conta que recebe o crédito
amount_cents = 1000       # R$ 10 em centavos

O provedor utiliza um modelo de entrega at-least-once. Portanto, um mesmo evento pode ser entregue novamente.

O serviço também pode reiniciar e executar em mais de uma instância compartilhando o mesmo armazenamento.

Independentemente de como ou quando um evento seja entregue, um mesmo event_id não pode produzir o mesmo crédito mais de uma vez.

O saldo é armazenado em um arquivo SQLite (ledger.db). O módulo sqlite3 já vem com o Python — não é necessário instalar ou subir nenhum servidor de banco de dados.

python cli.py evt-abc123 acc-42 1000

Exemplo de saída:

Evento evt-abc123: aplicado
Saldo de acc-42: 1000 centavos

Comportamento esperado

O código atual não cumpre completamente este contrato.

1. Idempotência

Um event_id válido deve produzir seu efeito no máximo uma vez, mesmo que seja recebido novamente ou que o serviço tenha reiniciado.

Uma nova tentativa de aplicar um evento já processado deve retornar:

result.applied is False

sem aplicar novamente o crédito.

2. Ambiente de produção

Considere que mais de uma execução do serviço pode compartilhar o mesmo arquivo de banco de dados. A garantia de idempotência precisa continuar válida nesse ambiente.

3. Validação

Um evento é inválido quando:

• event_id está vazio;
• account_id está vazio;
• amount_cents é menor ou igual a zero.

Nesses casos:

• InvalidCreditError deve ser levantada;
• o saldo não deve ser alterado;
• o evento não deve ser registrado como processado;
• o mesmo event_id pode ser utilizado posteriormente em uma chamada válida.

4. Eventos diferentes

Eventos válidos com event_id diferentes devem produzir seus respectivos créditos normalmente.

Contrato do código

Você pode alterar a implementação interna e o schema do banco, mas a interface abaixo deve continuar funcionando:

ledger = CreditLedger(database_path)
result = ledger.apply_credit(event_id, account_id, amount_cents)

result.applied        # bool
result.balance_cents  # int

ledger.balance(account_id)  # int
InvalidCreditError           # exceção de validação

result.balance_cents representa o saldo persistido da conta observado ao término da chamada, considerando as operações já confirmadas naquele momento.

Se alterar o schema do banco, apague seu ledger.db local antes de executar o CLI novamente.

Testes adicionais

Além dos testes presentes neste repositório, sua solução será executada contra testes adicionais.

Eles verificarão o contrato descrito acima e o comportamento da solução em cenários compatíveis com um serviço backend executado em produção.

Evite implementar apenas o necessário para fazer o teste atualmente vermelho passar.

O que você precisa entregar

1. Clone este repositório

Não faça fork.

git clone https://github.com/pipe-challenge/young-guns-2026.git
cd young-guns-2026

2. Crie um novo repositório privado

Na sua conta do GitHub, crie um repositório privado e vazio, por exemplo:

young-guns-2026-submission

Não adicione README, .gitignore ou licença ao criá-lo.

Depois, altere o remote do projeto:

git remote remove origin
git remote add origin https://github.com/<seu-usuario>/young-guns-2026-submission.git
git push -u origin main

3. Trabalhe em uma branch

git checkout -b fix/<seu-primeiro-nome>

Implemente sua solução e faça commits que ajudem a entender as mudanças realizadas.

4. Testes

Faça os testes existentes passarem sem remover ou alterar suas asserções.

Adicione pelo menos 2 testes novos que aumentem de forma relevante a confiança na sua solução.

Pelo menos um deles deve demonstrar um comportamento incorreto existente no código original e passar após sua correção.

A escolha dos cenários adicionais faz parte da avaliação.

5. Abra um Pull Request

Faça push da sua branch:

git push -u origin fix/<seu-primeiro-nome>

Abra um Pull Request de sua branch para main dentro do seu repositório privado.

Não faça merge do PR.

6. Convide o avaliador da Pipefy

No seu repositório privado, acesse:

Settings → Collaborators → Add people

Adicione como colaborador o usuário GitHub do avaliador informado no e-mail da Pipefy.

Aguarde o convite ser aceito antes de finalizar sua entrega.

O repositório deve permanecer privado durante e após o processo seletivo.

7. Grave um vídeo de até 5 minutos

Use Loom, YouTube não listado ou Google Drive com acesso liberado.

Não envie o arquivo de vídeo para o repositório.

O vídeo deve estar acessível para qualquer pessoa que possua o link, sem necessidade de solicitar permissão ou fazer login.

No vídeo, explique:

• qual abordagem você escolheu e por quê;
• quais problemas relevantes encontrou no código original;
• quais foram as principais alterações realizadas;
• quais testes adicionou e por que escolheu esses cenários;
• como utilizou IA durante o desafio;
• pelo menos uma sugestão da IA que você validou, modificou ou rejeitou, e como chegou a essa decisão;
• alguma limitação que ainda exista ou algo que faria diferente com mais tempo.

Adicione o link do vídeo na descrição do Pull Request.

8. Envie sua entrega

Na task da Pipefy, envie:

• link do repositório privado;
• link do Pull Request;
• link do vídeo;

Setup

Python 3.11+. Sem dependências externas além do pytest.

python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt
pytest

No estado inicial do repositório, pytest não passa completamente. Isso é proposital.

Regras

• O uso de IA é permitido e incentivado.
• Você é responsável por todo o código submetido.
• Não altere as asserções dos testes existentes.
• Não adicione dependências novas sem justificar no PR.
• Mantenha a solução simples e proporcional ao problema.
• Não é necessário reorganizar todo o projeto.
• O histórico de Git deve permitir entender as mudanças, mas quantidade de commits não é critério de qualidade.
• O Pull Request precisa conter o link do vídeo.
• O repositório da entrega deve permanecer privado.

O que vamos avaliar

Principalmente:

• correção da solução;
• qualidade e relevância dos testes;
• qualidade e simplicidade do código;
• comportamento esperado para um serviço backend em produção;
• capacidade de identificar riscos e trade-offs;
• uso crítico de IA e domínio do código entregue;
• clareza da explicação técnica;
• uso básico de Git e GitHub.

O objetivo não é encontrar uma implementação específica, e sim avaliar as decisões de engenharia que levaram à sua solução.