FECOT

O problema e as restrições

O FECOT é o órgão regional que certifica quem tem qual faixa de taekwondo em quatro estados brasileiros. Esse único fato, a graduação, é o motivo de uma federação existir: ela decide em qual categoria um atleta compete, quem pode dar aula, e se o certificado da federação significa alguma coisa para a liga nacional à qual ela responde. Antes dessa reescrita, esse dado vivia num sistema em que a história de como uma mudança aconteceu não fazia parte do desenho.

O cliente, Luciano Bezerra da Cunha, trouxe um monólito em Ruby on Rails que funcionava mas estava envelhecendo, e uma prioridade clara: graduação não podia ser um campo como outro qualquer. Todo o resto (modernizar a stack, tipar as duas pontas da API) importava, mas a restrição de verdade por trás desse projeto era que a autoridade de uma federação depende inteiramente de as pessoas confiarem nos seus registros, e um registro que qualquer um com acesso de admin pode editar em silêncio é só uma opinião com data.

A segunda restrição era quem de fato usa esse sistema e como. Atletas não se auto-cadastram num laptop; são adolescentes e adultos cadastrados em lote pelo próprio professor, muitas vezes ali mesmo no tatame, sem e-mail à mão e sem nenhum momento em que entregar um link de “clique aqui para definir sua senha” faça sentido. Qualquer desenho de autenticação que assumisse um fluxo de auto-registro estaria resolvendo um problema que essa federação não tem, enquanto ignora o que ela tem de verdade.

A terceira restrição era honestidade operacional sobre a escala: um desenvolvedor só, construindo para uma federação esportiva regional numa única VPS, sem ambiente de staging, sem função de segurança dedicada, e sem time de plataforma ou investimento por trás de nada disso. Todo controle (tratamento de senha, autorização, segurança de upload) precisava ser algo que uma pessoa conseguisse raciocinar por completo, porque não existe um segundo revisor nem um time de resposta a incidente por trás.

A quarta restrição veio da própria hierarquia do domínio: professores, gestores de academia e administradores, e cada um deles também é, inevitavelmente, um atleta com a própria faixa e o próprio histórico de treino. Um professor sem pelo menos faixa preta de primeiro grau falha nas regras do próprio esporte para exercer o papel, antes mesmo do software entrar em cena. Qualquer modelo construído precisava representar que um gestor ou professor é uma especialização de “atleta”, a mesma entidade de base carregando um papel a mais.

A última restrição era continuidade: o sistema em Rails já carregava anos de regra de negócio real: qual graduação exige qual faixa para dar aula, como os níveis de graduação são nomeados e ordenados, quem pode cadastrar quem. Uma reescrita que “modernizasse” a stack perdendo uma dessas regras em silêncio seria um resultado pior do que não reescrever. Toda regra visível no código antigo precisava de uma decisão deliberada sobre se ela seguiria adiante.

Arquitetura

Um professor, um gestor de academia ou um admin abre o frontend em Next.js e faz tudo através de um único cliente de API tipado. Não existe outro caminho do navegador até o backend, e nenhum componente atravessa essa fronteira com um fetch solto e sem tipo. Esse gargalo único é o que permite afirmar, com confiança, que uma mudança de contrato de um lado é pega do outro: se o formato de resposta do backend muda, os tipos do frontend param de compilar em vez de simplesmente renderizar undefined em silêncio.

O backend em FastAPI é o único processo com acesso de escrita ao PostgreSQL. Duas camadas de autorização ficam na frente de toda escrita: guardas de papel no nível do endpoint (um endpoint simplesmente recusa um papel que não deveria estar ali), e regras contextuais avaliadas no próprio modelo de domínio: um professor edita os próprios alunos, um gestor de academia edita qualquer um da sua academia, um admin edita qualquer um. As duas camadas rodam no backend, nunca no frontend: a imposição precisa viver onde um usuário não consegue contornar editando o que é renderizado no navegador; a constituição desse projeto diz isso explicitamente, e a suíte de testes é o que de fato cobra isso.

O fluxo de graduação é onde essa arquitetura fica mais visível na prática. Nada no sistema (nenhum endpoint, nenhum atalho de admin, nenhum script interno) escreve direto no campo graduation de um atleta. A única forma dele mudar é por um GraduationRequest: um professor, gestor ou admin cria um, que tira um retrato automático da graduação atual do atleta; só um admin pode aprovar ou rejeitar; e a decisão, o revisor e o horário ficam registrados permanentemente, seja a solicitação aprovada ou recusada. Um atleta pode ter no máximo uma solicitação pendente por vez, o que fecha a única brecha que deixaria alguém contornar o rastro de auditoria de solicitação única simplesmente abrindo outra antes da primeira ser resolvida.

A autenticação fica por baixo de tudo isso como uma camada deliberadamente simples: um JWT stateless, guardado no navegador, revalidado contra o banco a cada requisição em vez de aceito de cara. Essa revalidação é o que faz desativar uma conta significar alguma coisa de verdade. O token em si não expira por até 24h, mas o backend confere se o atleta por trás dele ainda está ativo antes de aceitar qualquer coisa que o token afirme. O upload de avatar segue o mesmo instinto de verificar em vez de confiar: toda imagem é decodificada, achatada sobre fundo branco, redimensionada e regravada como WebP antes de ir para o disco, então nada que um usuário envia é servido de volta byte a byte. Um executável renomeado ou uma imagem com payload embutido não sobrevive inteiro a essa travessia.