Site de Inscrições do 8th BCSMIF

Versão: 0.2.0
Data: 2025-08-13

1. Introdução

Este repositório contém o código-fonte do site de inscrições para o 8th Brazilian Conference on Statistical Modeling in Insurance and Finance (8th BCSMIF). O evento será realizado de 28 de setembro a 3 de outubro de 2025, no Maresias Beach Hotel em Maresias, SP, e é organizado pelo Instituto de Matemática e Estatística da Universidade de São Paulo (IME-USP).

O objetivo do 8th BCSMIF é fornecer um fórum para a apresentação de pesquisas de ponta no desenvolvimento e implementação de métodos recentes no campo de Finanças e Seguros, com ênfase nas aplicações práticas de Ciência de Dados e Aprendizado de Máquina. O evento também busca promover a discussão e o intercâmbio de ideias entre jovens pesquisadores e cientistas seniores.

Este projeto de site de inscrições é construído sobre o Laravel 12 USP Starter Kit, aproveitando sua base robusta para autenticação, integração com sistemas USP e boas práticas de desenvolvimento.

2. Público-Alvo (deste Repositório)

Este README e o código-fonte são destinados principalmente a:

• Desenvolvedores trabalhando no desenvolvimento e manutenção do site de inscrições do 8th BCSMIF.
• Administradores do evento que possam precisar de informações técnicas sobre o sistema.

3. Principais Funcionalidades do Site de Inscrições

O site de inscrições do 8th BCSMIF visa oferecer as seguintes funcionalidades:

• Páginas Públicas Informativas:
  • Página Inicial com a descrição do evento, datas e local.
  • Página de Workshops detalhando os eventos satélites (Risk Analysis and Applications e Dependence Analysis).
  • Página de Taxas de Inscrição apresentando a tabela de preços completa.
  • Página de Informações de Pagamento com instruções para participantes brasileiros e internacionais.
• Sistema de Inscrição Online:
  • Formulário de inscrição completo e intuitivo para participantes (requer login e email verificado).
  • Diferenciação entre participantes USP e externos, com validação de Nº USP (codpes) para usuários USP.
  • Seleção de participação no evento principal (8th BCSMIF) e/ou workshops.
  • Cálculo dinâmico das taxas de inscrição baseado na categoria do participante, eventos selecionados e prazos (early bird/late).
• Gerenciamento de Pagamentos:
  • Instruções claras para pagamento (transferência/PIX para brasileiros).
  • Informação sobre envio de invoice para participantes internacionais.
  • Funcionalidade para upload de comprovante de pagamento para participantes brasileiros.
• Área do Usuário Logado:
  • Visualização das próprias inscrições realizadas.
  • Acesso aos detalhes da inscrição.
  • Upload de comprovante de pagamento (para inscrições elegíveis).
• Área Administrativa Completa:
  • Dashboard Administrativo: Visão geral com métricas em tempo real, estatísticas de inscrições por categoria, receita, comprovantes pendentes e necessidades de transporte.
  • Widgets Interativos: Total de inscrições, receita gerada, aprovações pendentes, distribuição por categorias e necessidades de transporte.
  • Feed de Atividades: Monitoramento em tempo real das ações do sistema (novas inscrições, uploads de comprovantes, mudanças de status).
  • Gerenciamento de Inscrições: Listagem completa com filtros avançados, visualização detalhada e ferramentas de aprovação/rejeição.
  • Sistema de Status: Controle completo do status das inscrições com workflow de aprovação.
  • Navegação por Breadcrumbs: Interface intuitiva com navegação contextual.
  • Design Responsivo: Otimizado para desktop e dispositivos móveis com carregamento progressivo.
• Notificações por Email:
  • Confirmação de nova inscrição para o participante e coordenador.
  • Notificação de upload de comprovante para o coordenador.
  • (Opcional) Notificação de confirmação de pagamento.

(Para um detalhamento completo do plano de implementação, consulte docs/plano_inscricao_8thBCSMIF.md)

4. Stack Tecnológica

Este projeto utiliza a stack tecnológica fornecida pelo Laravel 12 USP Starter Kit:

• Framework: Laravel 12
• Linguagem: PHP >= 8.2
• Frontend (Stack TALL via Laravel Breeze):
  • Livewire 3 (Class API)
  • Alpine.js 3
  • Tailwind CSS 4 (com suporte a Dark Mode)
  • Vite
• Banco de Dados: MySQL (preferencialmente), com suporte padrão do Laravel para outros (MariaDB, PostgreSQL, SQLite).
• Integrações USP (via Starter Kit):
  • uspdev/senhaunica-socialite para autenticação Senha Única.
  • uspdev/replicado para acesso a dados corporativos (usado na validação de registro).
• Autenticação Scaffolding: laravel/breeze (adaptado).
• Permissões: spatie/laravel-permission.
• Internacionalização: Sistema completo de i18n com formatação de moedas e datas por localidade (pt_BR, en).
• Testes: PHPUnit, Laravel Dusk (com cobertura abrangente: Browser, Feature e Unit tests).
• Qualidade: Laravel Pint, Larastan.
• Ferramentas Dev: Python 3.x, google-genai, python-dotenv, tqdm (para scripts LLM auxiliares).

5. Instalação (Para Desenvolvedores)

Siga os passos abaixo para configurar o ambiente de desenvolvimento deste projeto:

1. Pré-requisitos:

   • PHP >= 8.2 (com extensões comuns do Laravel).
   • Composer
   • Node.js (v18+) e NPM
   • Git
   • Google Chrome ou Chromium instalado (para testes Dusk).
   • (Opcional, para ferramentas de dev) Python >= 3.10, Pip, gh CLI, jq.

2. Clonar o Repositório:

   git clone https://github.com/ime-usp-br/8thBCSMIF.git
   cd 8thBCSMIF

3. Instalar Dependências PHP:

   composer install

4. Instalar Dependências Frontend:

   npm install

5. Configurar Ambiente:

   • Copie o arquivo de exemplo .env:

     cp .env.example .env

   • Gere a chave da aplicação:

     php artisan key:generate

   • Edite o arquivo .env: Configure as variáveis de ambiente, especialmente:
     • APP_NAME="8thBCSMIF" (ou similar).
     • APP_URL: URL base local (ex: http://8thbcsmif.test ou http://localhost:8000).
     • Credenciais do banco de dados (DB_CONNECTION, DB_HOST, etc.).
     • Configurações de e-mail (MAIL_*).
     • Credenciais para uspdev/senhaunica-socialite e uspdev/replicado (veja a Seção 7).
     • (Opcional) GEMINI_API_KEY para scripts LLM.

6. Banco de Dados e Dados Iniciais:

   • Execute as migrações:

     php artisan migrate

   • (Opcional, mas recomendado) Execute os seeders (incluindo os seeders de Events e Fees que serão criados para o 8thBCSMIF):

     php artisan db:seed

7. Compilar Assets Frontend:

   npm run build

   (Ou use npm run dev durante o desenvolvimento).

8. Configuração Inicial do Dusk (Importante):

   • Verifique a instalação do Dusk (já deve estar no composer.json).
   • Instale o ChromeDriver: php artisan dusk:chrome-driver --detect.
   • Crie/Verifique .env.dusk.local (exemplo fornecido) com APP_URL e DB_DATABASE (ex: database/testing/dusk.sqlite) para testes Dusk.

9. (Opcional) Configurar Ferramentas de Desenvolvimento Python:

   • pip install -r requirements-dev.txt
   • chmod +x scripts/*.py scripts/tasks/*.py (se necessário).

6. Uso Básico (Desenvolvimento)

1. Iniciar Servidores:
   • Servidor web PHP: php artisan serve
   • Servidor Vite: npm run dev
2. Acessar a Aplicação: Abra a APP_URL no navegador.

7. Configurações Específicas da USP

Configure as seguintes variáveis no seu arquivo .env para as integrações USP:

• Senha Única: SENHAUNICA_CALLBACK, SENHAUNICA_KEY, SENHAUNICA_SECRET.
• Replicado: REPLICADO_HOST, REPLICADO_PORT, REPLICADO_DATABASE, REPLICADO_USERNAME, REPLICADO_PASSWORD, REPLICADO_CODUND, REPLICADO_CODBAS.

Consulte a documentação dos pacotes uspdev/senhaunica-socialite e uspdev/replicado para detalhes sobre como obter estas credenciais.

8. Ferramentas e Qualidade de Código

Este projeto utiliza as ferramentas de qualidade e desenvolvimento herdadas do Laravel 12 USP Starter Kit:

• Laravel Pint: Formatador PSR-12 (vendor/bin/pint).
• Larastan (PHPStan): Análise estática (vendor/bin/phpstan analyse).
• EditorConfig: Consistência de estilo.
• Scripts Python (scripts/):
  • create_issue.py: Para automação de criação/edição de Issues no GitHub.
  • generate_context.py: Para coletar contexto do projeto para LLMs (com execução seletiva via --stages).
  • llm_interact.py (dispatcher) e scripts/tasks/llm_task_*.py (tarefas individuais): Para interações com a API Gemini, auxiliando em diversas tarefas de desenvolvimento. Uma funcionalidade notável para a tarefa resolve-ac é que, ao usar as flags --only-prompt (-op) e --select-context (-sc) juntas, os arquivos de contexto selecionados (essenciais + escolhidos pela LLM) são copiados para context_llm/temp/ (sem estrutura de diretórios e com extensão .txt), e o prompt final exibido é construído para referenciar esses arquivos, facilitando o uso manual com LLMs externas como o Google AI Studio.

9. Testes

• PHPUnit (Unitários e Feature): php artisan test
• Laravel Dusk (Browser): Requer setup específico (servidor app e ChromeDriver rodando). Veja o Guia de Desenvolvimento para instruções detalhadas de execução local. Comando principal: php artisan dusk

10. Deploy e Produção

10.1. Configuração do Laravel Scheduler

IMPORTANTE: Este projeto utiliza o Laravel Scheduler para executar tarefas automatizadas (como envio de lembretes de early bird). Para que funcione em produção, é obrigatório configurar o crontab do sistema.

10.1.1. Tarefas Agendadas

O sistema possui as seguintes tarefas agendadas em routes/console.php:

• Early Bird Reminders: app:send-early-bird-reminders - Executa diariamente à meia-noite para enviar lembretes de prazo early bird.

10.1.2. Configuração do Crontab (OBRIGATÓRIA)

O Laravel Scheduler é apenas uma abstração - você precisa do crontab do sistema para executar o scheduler.

1. Adicionar entrada no crontab do servidor:

# Editar crontab (como usuário que roda a aplicação)
crontab -e

# Adicionar esta linha (substituir /path-to-your-project pelo caminho real):
* * * * * cd /path-to-your-project && php artisan schedule:run >> /dev/null 2>&1

2. Verificar configuração:

# Listar crontab atual
crontab -l

# Verificar tarefas agendadas no Laravel
php artisan schedule:list

3. Exemplo para servidor de produção:

# Para o projeto 8thBCSMIF no servidor de produção
* * * * * cd /var/www/8thBCSMIF && php artisan schedule:run >> /dev/null 2>&1

10.1.3. Como Funciona

1. Crontab executa php artisan schedule:run a cada minuto
2. Laravel verifica quais comandos agendados devem rodar no momento atual
3. Se for a hora certa (ex: 0:00 para daily()), executa o comando correspondente

10.1.4. Desenvolvimento Local

Para testes locais, use:

# Simula o scheduler em foreground (não requer crontab)
php artisan schedule:work

# Ou execute comandos manualmente para testes
php artisan app:send-early-bird-reminders

10.1.5. Monitoramento

# Verificar logs do sistema para problemas de crontab
tail -f /var/log/syslog | grep CRON

# Verificar logs da aplicação Laravel
tail -f storage/logs/laravel.log

# Testar execução manual do scheduler
php artisan schedule:run --verbose

⚠️ ATENÇÃO: Sem a configuração do crontab, as tarefas agendadas (como lembretes de early bird) NUNCA serão executadas automaticamente, mesmo estando configuradas no código.

10.2. Outras Configurações de Deploy

• Siga as melhores práticas do Laravel para deploy em produção
• Configure adequadamente as variáveis de ambiente (.env)
• Execute composer install --optimize-autoloader --no-dev
• Execute npm run build para assets de produção
• Configure cache: php artisan config:cache, php artisan route:cache, php artisan view:cache

11. Documentação

• Este README.md: Visão geral do projeto do site de inscrições.
• Diretório docs/:
  • descricao_evento.md: Detalhes sobre o 8th BCSMIF.
  • formulario_inscricao.md: Especificação do formulário de inscrição.
  • plano_inscricao_8thBCSMIF.md: Plano de implementação detalhado do site.
  • Documentos herdados do Starter Kit (guia_de_desenvolvimento.md, padroes_codigo_boas_praticas.md, etc.) que guiam o desenvolvimento deste projeto.

12. Como Contribuir

Siga o fluxo descrito no Guia de Estratégia de Desenvolvimento (herdado e adaptado do Starter Kit) para contribuições.

13. Licença

Este projeto é licenciado sob a Licença MIT. Veja o arquivo LICENSE para mais detalhes.