descrição do projeto - LucasXRosas/utfprarena GitHub Wiki

O sistema proposto é uma solução de infraestrutura back-end focada em otimizar a administração operacional de complexos esportivos e arenas de beach tennis. A plataforma automatiza a jornada dos alunos desde o momento da autenticação até a verificação ativa de sua saúde financeira na instituição. O software trata de forma transparente as cobranças recorrentes e implementa uma rotina rigorosa de controle de entrada, protegendo a receita do negócio por meio de um algoritmo inteligente que suspende de forma automática os privilégios dos usuários em situação irregular prolongada.

---

Desenvolvimento de um ecossistema de Back-End em PHP para o gerenciamento operacional e controle financeiro automatizado de Arenas Esportivas de Beach Tennis. O foco central está na automação do ciclo de vida das mensalidades, autenticação segura de usuários e mitigação de inadimplência por meio de um motor de regras de bloqueio e reativação automática de acessos.

O objetivo principal deste projeto é desenvolver uma API de back-end robusta e escalável, utilizando o ecossistema PHP, capaz de centralizar e automatizar a gestão operacional e financeira de complexos esportivos de beach tennis. A plataforma atua de forma estratégica na jornada do aluno e na saúde financeira do negócio através dos seguintes objetivos específicos:

• Automação do Fluxo de Caixa: Substituir processos manuais de cobrança por um ciclo automatizado de faturamento recorrente, garantindo previsibilidade financeira para a arena.
• Mitigação Ativa da Inadimplência: Implementar um motor de regras estritas que monitora o status de pagamento em tempo real, aplicando restrições lógicas de acesso (bloqueio automático) assim que o teto de tolerância (1 mês de atraso) é atingido.
• Segurança e Rastreabilidade de Acessos: Garantir a integridade dos dados e o controle de acesso ao ecossistema através de autenticação tradicional segura e arquitetura baseada em tokens (JWT), impedindo o uso da infraestrutura por usuários irregulares.
• Reativação Instantânea de Operações: Eliminar o gargalo operacional do desbloqueio manual, restabelecendo as permissões e o status ativo do aluno de forma imediata assim que a pendência financeira mínima for liquidada.

A implementação da API do projeto Arena UTFPR trará um impacto positivo direto tanto para a gestão do complexo esportivo quanto para a experiência dos praticantes:

• Para a Gestão e Organização:

  • Redução Significativa da Inadimplência: O motor automatizado de bloqueio reduz o risco de uso continuado das instalações por usuários com pendências financeiras prolongadas, protegendo a saúde financeira e o fluxo de caixa do empreendimento.
  • Eficiência Operacional: Elimina a necessidade de conferência manual de planilhas e extratos por parte dos administradores, liberando a equipe para focar no atendimento, manutenção das quadras e expansão do negócio.
  • Decisões Baseadas em Dados: Centraliza o histórico financeiro e relatórios de alunos, permitindo um acompanhamento preciso da receita e da taxa de adimplência.

• Para os Usuários (Alunos e Professores):

  • Transparência e Autonomia: Alunos ganham visibilidade clara sobre o status de suas mensalidades e histórico financeiro, sabendo exatamente suas obrigações sem constrangimentos presenciais.
  • Desbloqueio Instantâneo: Ao regularizar débitos, o acesso e a permissão de reserva de quadras são reestabelecidos de forma imediata e automatizada, sem depender da intervenção de um atendente.
  • Previsibilidade: A régua de cobrança preventiva alerta os alunos em prazos estratégicos (0, 7, 14 e 21 dias), evitando bloqueios surpresa.

No cenário real de gestão de complexos esportivos, foram mapeadas as seguintes dores que o sistema visa solucionar:

• Evasão de Receita por Inadimplência: Alunos frequentando a arena e utilizando os espaços mesmo com mensalidades atrasadas por longos períodos.
• Sobrecarga na Gestão Manual: Administradores gastando tempo revisando planilhas para descobrir quem pagou, quem está devendo e quem deve ter o acesso barrado.
• Falhas de Segurança no Acesso: Falta de um controle digital centralizado, permitindo que usuários não cadastrados ou irregulares utilizem as dependências da arena sem validação prévia.

• Autenticação Segura: Fluxo tradicional de cadastro e login com criptografia e tokens de sessão.
• Gestão de Mensalidades: Geração de faturas mensais e controle do fluxo de caixa dos alunos.
• Bloqueio Automatizado: Motor de regras que restringe o acesso de alunos com mais de 1 mês de mensalidades em atraso.

Para garantir a entrega do projeto dentro do prazo letivo da universidade, as seguintes funcionalidades foram explicitamente definidas como fora de escopo do back-end:

• Desenvolvimento de Interface Visual (Front-End): O projeto limita-se estritamente ao desenvolvimento da API (rotas, regras e banco de dados), não incluindo telas, aplicativos mobile ou interfaces web.
• Integração Real com Gateways de Pagamento: O sistema não fará chamadas reais para operadoras de cartão ou bancos (ex: API do Stripe, Mercado Pago ou bancos tradicionais). Os pagamentos serão simulados via endpoints de testes ou webhooks simulados para testes de integração.
• Gateway Físico de Catracas: O bloqueio é lógico (rejeição de requisições na API). O projeto não contempla a integração com hardware de catracas físicas ou leitores biométricos de portarias.
• Agendamento Avulso de Quadras por Não-Alunos: O sistema foca no modelo de mensalistas regulares da arena. Aluguéis avulsos de quadras por usuários externos não serão processados nesta versão.

No desenvolvimento da especificação, documentação e estruturação da API Arena UTFPR, foram utilizadas ferramentas de Inteligência Artificial Generativa como apoio técnico, validação de arquitetura e auxílio na escrita de requisitos.

Gemini: Utilizado para apoio na modelagem da especificação de requisitos, definição do escopo acadêmico, estruturação de regras de negócio financeiras e apoio técnico de arquitetura back-end.

• Modelagem e Especificação do Sistema: Auxílio na estruturação formal dos Requisitos Funcionais (RF), Requisitos Não Funcionais (RNF) e Regras de Negócio (RN).

• Delimitação de Escopo: Apoio na tomada de decisão do que deveria ser mantido no core da API e o que deveria ficar explicitamente como fora de escopo (ex: hardware de catracas, gateways reais de pagamento).

• Escrita da Documentação: Formatação padronizada em Markdown para o repositório no GitHub, geração da Wiki e criação do roteiro da apresentação em vídeo.

Exemplo 1: Definição da Regra de Negócio de Bloqueio Prompt Enviado:

"Estou criando uma API em Node.js para uma arena de Beach Tennis e preciso de uma regra de negócio clara para suspender o acesso do aluno inadimplente de forma automatizada, sem ser injusto na primeira fatura. Como posso detalhar essa regra e a régua de cobrança?"

• Resultado Obtido (IA):

A IA sugeriu a criação de um critério de tolerância baseado no acúmulo de 2 ou mais faturas vencidas simultaneamente (RN001), além de propor uma régua de notificações preventivas em 0, 7, 14 e 21 dias de atraso (RN002) e a lógica para o desbloqueio automático instantâneo (RN003).

Exemplo 2: Estruturação dos Requisitos Não Funcionais Prompt Enviado:

"Escreva requisitos não funcionais técnicos para uma API que lida com transações financeiras recorrentes e bloqueio de usuários, cobrindo segurança, integridade de dados e rotinas diárias em horários de baixo tráfego."

• Resultado Obtido (IA):

A IA gerou a especificação dos requisitos RNF001 (Hash de senhas), RNF002 (Autenticação stateless/JWT), RNF003 (Execução de rotinas no horário de baixo impacto de madrugada) e RNF004 (Transações ACID em banco relacional).

Exemplo 3: Elaboração da Seção de Requisitos Técnicos e Impacto Prompt Enviado:

"Monte uma tabela de requisitos técnicos especificando linguagem, framework, banco de dados e justificativas para o projeto Arena UTFPR. Monte também os pontos de impacto esperado para os alunos e para os gestores."

• Resultado Obtido (IA):

A IA elaborou a tabela comparativa com PostgreSQL, JWT, rotinas agendadas (Cron/BullMQ) e detalhou o impacto focado na redução de inadimplência, automação da gestão e clareza para os alunos.