A inspiração

Sistemas que processam pagamentos precisam identificar operações que merecem revisão. Mas, na prática, muitos desses sistemas devolvem apenas um número — uma pontuação de risco — sem explicar por que aquela transação foi classificada daquela forma. Para quem precisa revisar, auditar ou contestar uma decisão, um score opaco é quase inútil.

Foi daí que surgiu o RiscoClaro: e se a análise de risco fosse tão transparente quanto o resultado? A ideia não é construir um detector de fraude real, mas demonstrar, de ponta a ponta, como um motor de risco determinístico e explicável pode devolver uma pontuação acompanhada dos motivos que a compuseram.

O nome diz tudo: risco + claro. A pontuação é só metade da história; a outra metade são os fatores que a justificam.

O que eu aprendi

Durante o desenvolvimento, alguns aprendizados se destacaram:

  • Explicabilidade como requisito de projeto, não como detalhe. Desde o início, o motor de risco foi desenhado para registrar cada fator acionado, e não apenas somar pontos. Isso mudou a forma como modelei os dados: a análise precisa guardar os motivos, não só o score.
  • Determinismo facilita testes e auditoria. Regras claras e parametrizadas tornam o comportamento previsível e testável. Cada regra tem seu próprio teste unitário, e os limites de classificação (29/30 e 59/60) são verificados explicitamente.
  • Idempotência é uma decisão de arquitetura, não um detalhe. Garantir que o mesmo externalId com a mesma entrada devolva o resultado anterior — e que uma entrada diferente gere 409 Conflict — exigiu uma restrição única no banco, não apenas uma checagem na aplicação.
  • Valores monetários em centavos. Trabalhar com inteiros evitou problemas de ponto flutuante e simplificou a validação.
  • A stack importa menos que a coerência. NestJS, Prisma e MySQL foram escolhidos por permitirem um fluxo tipado de ponta a ponta, do DTO ao banco, com validação consistente.

Como construí o projeto

A arquitetura segue um fluxo simples e rastreável:

Cliente HTTP / Swagger
        |
        v
NestJS REST API (/api/v1)
        |
DTOs + validação (class-validator)
        |
        v
Transactions Module
        |
        v
Risk Engine (regras explicáveis)
        |
        v
Prisma ORM
        |
        v
MySQL

Built With

Share this project:

Updates

Submission history