Cadastro, cobrança e portaria de um clube num sistema só

O CLIENTE

Um clube de 1964 operado por uma pessoa

A Associação Recreativa dos Tangarás é o clube de Potirendaba, no interior de São Paulo — a cidade onde eu moro. Fundada em 1964, tem piscina, natação e karatê, cerca de 2.400 pessoas com direito de uso entre titulares e dependentes, e um histórico de quase dez mil cadastros acumulados em seis décadas.

Tudo isso passava por uma pessoa só: a secretaria. Ela cadastrava, cobrava, dava baixa nos pagamentos, conferia o caixa e atendia o sócio. E fazia isso em oito lugares diferentes.

A associação me procurou para trocar o sistema financeiro. O que ela precisava era maior do que isso.

DIAGNÓSTICO OPERACIONAL

Como era antes

O levantamento começou com uma entrevista longa com a secretaria e dezesseis prints de tela. O mapa que saiu dali:

• Um sistema desktop antigo para cadastro, parcelas e boletos, que dependia de ligar um “servidor” local e passava por várias telas a cada operação.
• Um segundo módulo do mesmo fornecedor só para o débito automático e para dar baixa, à mão, nos boletos emitidos em outro banco.
• Um livro-caixa num programa descontinuado, instalado numa máquina só — de onde o contador tirava o relatório da prestação de contas.
• Uma planilha paralela, porque ninguém confiava no livro-caixa.
• O WhatsApp pessoal da secretaria para cobrança, avisos e inscrição em torneio.
• Papel para ficha de sócio, contrato (um arquivo de Word por vez) e inscrição de evento.
• O Pix, que tinha sido cortado porque não dava para saber quem pagou — a esposa pagava o título do marido e o dinheiro chegava sem dono.
• A portaria, com catraca e leitores faciais amarrados ao sistema antigo.

Lançar e corrigir uma parcela levava cerca de um minuto. Duas fontes de boleto geravam baixa manual todo dia. Advertência e suspensão de sócio não ficavam registradas em lugar nenhum.

Mas a dor de verdade não era a quantidade de telas. O clube não era dono da própria informação. O banco de dados ficava com o fornecedor, o caixa num programa sem suporte, a cobrança no celular de uma pessoa. Isso não era falha de quem operava — era uma pessoa segurando sozinha o que uma instituição de seis décadas deveria ter estruturado.

O MÉTODO

Entrevista primeiro, especificação depois, código por último

Eu não conhecia gestão de clube. Por isso o projeto começou ao contrário do que costuma começar: antes da primeira linha de código, oito documentos — diagnóstico do sistema atual, requisitos por módulo com identificador e prioridade, arquitetura com as decisões registradas, roteiro por etapas, perguntas abertas com dono, plano de qualidade, um briefing jurídico sobre biometria e um red team de segurança e LGPD feito sobre o desenho, antes de existir sistema para atacar. Quase cinquenta riscos mapeados ali viraram requisitos do módulo de segurança.

Depois vieram outros seis, conforme o projeto andou — entre eles uma leitura do estatuto social confrontada com o que o software antigo fazia, e o levantamento em campo dos equipamentos da portaria.

Cada funcionalidade nova segue o mesmo trilho: uma conversa para fechar o desenho, uma spec escrita e aprovada, um plano quebrado em tarefas pequenas, e a execução por agentes de IA — cada tarefa implementada, revisada e só então integrada. O que a revisão encontra e não é corrigido na hora fica registrado como pendência consciente, com o custo de estar errado escrito ao lado.

ENGENHARIA E ARQUITETURA

O que eu fiz

Um sistema web único, em TypeScript de ponta a ponta — API em NestJS, front em React, PostgreSQL —, organizado em módulos.

Cadastro. Titular e dependente vivem na mesma tabela de pessoa: transferir a titularidade (por falecimento, por exemplo) é trocar o papel do vínculo, não mover a pessoa de lugar. A regra de dependência segue o estatuto, e o que foge dela só entra como exceção justificada e auditada. Ciclo de vida completo do título: desligar, reativar, transferir.

Atualização cadastral por link. O sócio recebe um link único, revisa os próprios dados, anexa documentos e envia a foto para o reconhecimento facial pelo celular. Nada vai direto para o cadastro: tudo cai numa fila, e a secretaria aprova.

Financeiro e tesouraria. Dinheiro guardado em centavos inteiros, nunca em número quebrado. Nada financeiro é apagado: parcela se cancela com motivo, pagamento se estorna, e o próprio banco de dados recusa a exclusão. Geração de mensalidade e de planos em lote, e idempotente — rodar duas vezes não cobra duas vezes. E a importação do retorno bancário nos dois formatos que o clube usa — CNAB 400 do boleto e Febraban 150 do débito automático — no mesmo botão: o sistema reconhece o arquivo e dá a baixa.

Portaria. Um agente de campo — um executável que roda como serviço do Windows na rede do clube, com instalador próprio — conversa com os leitores faciais e com a API. Quando a secretaria aprova uma foto, dá baixa numa parcela ou desliga um título, o leitor é atualizado sozinho. O painel da portaria mostra as passagens em tempo real, avisa quando um leitor sai do ar, e o histórico de acesso de cada pessoa junta o sistema novo aos anos do antigo.

Auditoria e segurança. Toda ação sensível grava autor, data e motivo numa trilha que só aceita inserção — não existe apagar, nem para o administrador. Toda rota exige sessão por padrão, o acesso é por perfil, o monitoramento de erro não leva nenhum dado pessoal para o log, e a foto facial fica cifrada no banco.

Por baixo de tudo, um CI que roda formatação, tipos, testes unitários e de integração com Postgres, checagem de migration, varredura de segredos e auditoria de dependências em todo pull request. A demonstração inteira usa dado fictício — dado real de sócio nunca entra em ambiente de desenvolvimento, de teste ou em ferramenta de IA.

REGRAS QUE NÃO SE NEGOCIAM

O que nenhum agente pode simplificar

Construir com IA nessa velocidade só funciona se existir um chão que não se mexe. Neste projeto, ele é uma lista curta, escrita no próprio repositório, que todo agente lê antes de qualquer tarefa:

• Regra de negócio fica na API, nunca no front nem em ferramenta de automação.
• Dinheiro é inteiro, em centavos.
• Nada financeiro é excluído.
• A trilha de auditoria só aceita inserção.
• Toda rota nega por padrão; rota pública exige justificativa no pull request.
• A baixa de pagamento nunca sai do corpo de um webhook: o sistema reconsulta o banco por um canal autenticado e só baixa o que a reconsulta confirmar.
• A mensagem de bloqueio na portaria é neutra — “procure a secretaria”. O motivo só aparece para quem tem perfil para ver.
• Só dado fictício fora de produção.

A regra da portaria parece detalhe e não é: numa cidade pequena, a catraca anunciar que alguém está com a mensalidade atrasada é cobrança vexatória, na frente de quem estiver na fila.

RESULTADOS

Onde está hoje

Em quatro semanas, com um mantenedor: cadastro completo, financeiro, tesouraria, relatórios, auditoria, atualização cadastral por link e o controle de acesso integrado aos leitores da portaria.

A gestão roda em demonstração, com dado fictício, enquanto a migração é preparada. A portaria já está em campo: as passagens reais chegam ao sistema desde o 17º dia de projeto, em operação paralela — o sistema antigo continua decidindo a catraca até o novo provar que acerta.

O que ainda não está resolvido, e eu não vou chamar de pronto:

• A migração do legado depende de decisões que são da diretoria, não do código — a principal é o que fazer com os cadastros que não cabem na regra do estatuto.
• A cobrança por API direta com os bancos depende de liberação externa, que demora.
• O app nativo do associado está especificado, não construído.
• Nada do sistema antigo é desligado antes de um ciclo inteiro de cobrança batendo com o banco e com o contador.

DINÂMICA DE OPERAÇÃO

Uma coisa que só o dado mostrou

No diagnóstico, a pergunta “quem tem acesso ao clube?” tinha resposta simples: sócio e dependente. O banco antigo contava outra história. Os funcionários estavam cadastrados como dependentes da diretoria — o único jeito que existia de fazer alguém passar na catraca.

Funcionou por anos, e quebraria no primeiro dia do sistema novo: a regra de dependência do estatuto recusaria todos eles na portaria. E misturar as duas coisas contamina o resto — funcionário não paga mensalidade, demissão não é o mesmo fluxo que a saída de um dependente, e a base legal para tratar o dado dele é o contrato de trabalho, não a relação associativa.

Funcionário virou entidade própria, com vínculo, ponto informativo de entrada e saída e uma regra de acesso que o reconhece antes de procurar um título. O remendo que dá certo no sistema antigo é exatamente o que derruba a virada para o novo.