RELATÓRIO DE ROTAS DE INSCRIÇÃO EM EVENTOS ============================================= Idea Football - Laravel API Data: 2024 --------------------------------------------------------------- 1. ROTAS PÚBLICAS DE EVENTOS --------------------------------------------------------------- Todas as rotas abaixo estão em: GET /api/events/ - GET /api/events/ - Lista todos os eventos - GET /api/events/search - Busca eventos - GET /api/events/statistics - Estatísticas de eventos - GET /api/events/category/{category} - Eventos por categoria - GET /api/events/type/{type} - Eventos por tipo - GET /api/events/institution/{institutionId} - Eventos de uma instituição - GET /api/events/age-range - Eventos por faixa etária - GET /api/events/gender - Eventos por gênero - GET /api/events/free - Eventos gratuitos - GET /api/events/paid - Eventos pagos - GET /api/events/available - Eventos disponíveis - GET /api/events/price-range - Eventos por faixa de preço - GET /api/events/date-range - Eventos por período - GET /api/events/ongoing - Eventos em andamento - GET /api/events/finished - Eventos finalizados - GET /api/events/early-bird - Eventos com desconto early-bird - GET /api/events/{event} - Detalhes de um evento específico --------------------------------------------------------------- 2. ROTAS DE INSCRIÇÃO (COM AUTENTICAÇÃO) --------------------------------------------------------------- Todas as rotas abaixo requerem autenticação JWT (Bearer token). Middleware: auth:api Autenticação: GET /api/auth/me --------------------------------------------------------------- 2.1. CONSULTA DE INSCRIÇÃO - GET /api/events/{event}/eligibility Controle: EventRegistrationController::checkEligibility() Descrição: Verifica se o usuário pode se inscrever no evento Validações: - Evento está ativo - Inscrições estão abertas (dentro do período) - Há vagas disponíveis - Usuário não está já inscrito - Usuário é elegível (role compatível com target_audience) Retorna: { can_register: boolean, event_id: int, user_id: int, user_role: string, target_audience: string, event_category: string, event_status: string, registration_start: datetime, registration_end: datetime, available_spots: int, total_capacity: int, checks: object, reason: string } - GET /api/events/{event}/registration-status Controle: EventRegistrationController::getRegistrationStatus() Descrição: Verifica o status da inscrição do usuário autenticado no evento Retorna: { is_registered: boolean, event_id: int, user_id: int, registration: { id: int, status: string (pending/confirmed/cancelled/waitlist/rejected), status_label: string, registration_code: string, registered_at: datetime, updated_at: datetime, additional_info: json, special_requirements: json, payment_status: string, payment_required: boolean } ou null, message: string } --------------------------------------------------------------- 2.2. REALIZAR INSCRIÇÃO - POST /api/events/{event}/register Controle: EventRegistrationController::store() Service: EventRegistrationService::registerUser() Request: EventRegistrationRequest Descrição: Inscreve o usuário autenticado em um evento Payload esperado: { additional_info?: json, special_requirements?: json } Retorna: Objeto de inscrição com: - id - status (pending/confirmed/cancelled/waitlist) - registration_code (código único gerado) - user_id - event_id - created_at - updated_at Mensagem: "Inscrição realizada com sucesso" Status HTTP: 201 Created --------------------------------------------------------------- 2.3. CANCELAR INSCRIÇÃO - DELETE /api/registrations/{registrationId} [PREFERENCIAL] Controle: EventRegistrationController::destroy() Service: EventRegistrationService::cancelRegistrationById() Descrição: Cancela uma inscrição do usuário autenticado Retorna: null Mensagem: "Inscrição cancelada com sucesso" Status HTTP: 200 OK - DELETE /api/events/registrations/{registrationId} [ALTERNATIVA] Controle: EventRegistrationController::destroy() Service: EventRegistrationService::cancelRegistrationById() Descrição: Variante da rota acima (dentro do grupo com prefixo 'events') Nota: Ambas as rotas apontam para o mesmo método --------------------------------------------------------------- 2.4. CONSULTAR MINHAS INSCRIÇÕES - GET /api/events/my/registrations Controle: EventRegistrationController::myRegistrations() Service: EventRegistrationService::getUserRegistrations() Descrição: Lista todas as inscrições do usuário autenticado Retorna: Array de inscrições com detalhes completos incluindo: - Informações do evento - Status da inscrição - Datas de inscrição e atualização - Código de inscrição - Informações de pagamento Mensagem: "Minhas inscrições listadas com sucesso" --------------------------------------------------------------- 3. ROTAS DE GERENCIAMENTO DE INSCRIÇÕES (APENAS INSTITUIÇÕES) --------------------------------------------------------------- Todas as rotas abaixo requerem: - Autenticação JWT (auth:api) - Middleware: institution Verificação de Instituição: Usuário deve ter role = 'institution' e status aprovado --------------------------------------------------------------- 3.1. LISTAR INSCRIÇÕES DO EVENTO - GET /api/events/{event}/registrations Controle: EventRegistrationController::eventRegistrations() Service: EventRegistrationService::getEventRegistrations() Descrição: Lista todas as inscrições de um evento Acesso: Apenas a instituição dona do evento Retorna: Array com todas as inscrições incluindo: - Informações do usuário inscrito - Status da inscrição - Datas de inscrição - Informações adicionais fornecidas - Histórico de alterações Mensagem: "Inscrições do evento listadas com sucesso" --------------------------------------------------------------- 3.2. LISTAR INSCRIÇÕES PENDENTES - GET /api/events/{event}/registrations/pending Controle: EventRegistrationController::pendingRegistrations() Service: EventRegistrationService::getPendingRegistrations() Descrição: Lista apenas as inscrições com status 'pending' de um evento Acesso: Apenas a instituição dona do evento Retorna: Array de inscrições pendentes Mensagem: "Inscrições pendentes listadas com sucesso" --------------------------------------------------------------- 3.3. CONFIRMAR INSCRIÇÃO - POST /api/events/registrations/{registrationId}/confirm Controle: EventRegistrationController::confirm() Service: EventRegistrationService::confirmRegistrationById() Descrição: Confirma uma inscrição pendente, alterando status para 'confirmed' Acesso: Apenas a instituição dona do evento Retorna: Objeto da inscrição atualizada Mensagem: "Inscrição confirmada com sucesso" --------------------------------------------------------------- 3.4. REJEITAR INSCRIÇÃO - POST /api/events/registrations/{registrationId}/reject Controle: EventRegistrationController::reject() Service: EventRegistrationService::rejectRegistrationById() Descrição: Rejeita uma inscrição pendente Acesso: Apenas a instituição dona do evento Retorna: null Mensagem: "Inscrição rejeitada com sucesso" --------------------------------------------------------------- 4. ROTAS DE FREQUÊNCIA/PRESENÇA (ATTENDANCE) --------------------------------------------------------------- Acompanhamento de presença em eventos (check-in/check-out) Todas as rotas abaixo requerem autenticação JWT (auth:api) --------------------------------------------------------------- 4.1. CHECK-IN (MARCA PRESENÇA) - POST /api/events/{event}/attendance/check-in Controle: EventAttendanceController::checkIn() Service: EventAttendanceService::checkInParticipant() Request: EventAttendanceRequest Descrição: Registra a presença de um participante no evento Payload esperado: { registration_id: int (ID da inscrição) } Retorna: Objeto de presença com: - id - registration_id - check_in_time - check_out_time (null) - notes (observações opcionais) Mensagem: "Check-in realizado com sucesso" --------------------------------------------------------------- 4.2. CHECK-OUT (SAÍDA) - POST /api/events/{event}/attendance/check-out/{registrationId} Controle: EventAttendanceController::checkOut() Service: EventAttendanceService::checkOutParticipant() Descrição: Registra a saída de um participante do evento Retorna: Objeto de presença atualizado com check_out_time Mensagem: "Check-out realizado com sucesso" --------------------------------------------------------------- 4.3. LISTAR PRESENÇAS DO EVENTO - GET /api/events/{event}/attendance Controle: EventAttendanceController::eventAttendance() Service: EventAttendanceService::getEventAttendance() Descrição: Lista todas as presenças registradas em um evento Retorna: Array de presenças com: - Dados do participante - Código de inscrição - Horário de check-in - Horário de check-out - Duração de participação Mensagem: "Presenças do evento listadas com sucesso" --------------------------------------------------------------- 4.4. RELATÓRIO DE PRESENÇA - GET /api/events/{event}/attendance/report Controle: EventAttendanceController::attendanceReport() Service: EventAttendanceService::generateAttendanceReport() Descrição: Gera relatório completo de presença do evento Retorna: { total_registered: int, total_checked_in: int, total_checked_out: int, checked_in_rate: float (%), average_participation_time: string, attendance_list: array, summary: object } Mensagem: "Relatório de presença gerado com sucesso" --------------------------------------------------------------- 4.5. BUSCAR PARTICIPANTE POR CÓDIGO - GET /api/events/{event}/attendance/participant/{registrationCode} Controle: EventAttendanceController::findParticipant() Service: EventAttendanceService::findParticipantByCode() Descrição: Busca participante pelo código de inscrição (útil para check-in rápido) Retorna: { participant: object, registration: object, attendance: object (se já teve check-in) } Mensagem: "Participante encontrado com sucesso" --------------------------------------------------------------- 5. STATUS POSSÍVEIS DE INSCRIÇÃO --------------------------------------------------------------- - pending: Pendente de aprovação - confirmed: Confirmada/Ativa - cancelled: Cancelada pelo usuário - waitlist: Em lista de espera (quando vagas esgotam) - rejected: Rejeitada pela instituição --------------------------------------------------------------- 6. VALIDAÇÕES IMPLEMENTADAS --------------------------------------------------------------- 6.1. Verificação de Elegibilidade (checkEligibility) - Evento está ativo - Período de inscrições está aberto - Há vagas disponíveis - Usuário não está já inscrito - Role do usuário é compatível com target_audience do evento 6.2. Verificação de Inscrição (store) - Request validado (EventRegistrationRequest) - Verificação de elegibilidade automática - Geração automática de código de inscrição único - Validação de capacidade máxima do evento 6.3. Verificação de Cancelamento (destroy) - Usuário só pode cancelar suas próprias inscrições - Validação de status para permitir cancelamento - Atualização automática de vagas disponíveis --------------------------------------------------------------- 7. AUTENTICAÇÃO E PERMISSÕES --------------------------------------------------------------- Todas as rotas de inscrição requerem: - Header: Authorization: Bearer {token} - Token válido e não expirado - Usuário autenticado Rotas de instituição requerem adicionalmente: - Usuário com role = 'institution' - Instituição aprovada pelo admin --------------------------------------------------------------- 8. MODELOS RELACIONADOS --------------------------------------------------------------- Event (app/Models/Event.php) - status, capacity, target_audience - registration_start, registration_end - category, type, location - price, early_bird_price EventRegistration (app/Models/EventRegistration.php) - user_id, event_id - status, registration_code - additional_info, special_requirements - payment_status, payment_required EventAttendance (app/Models/EventAttendance.php) - registration_id - check_in_time, check_out_time - notes User (app/Models/User.php) - role (athlete/coach/institution/fan) - status (active/suspended) --------------------------------------------------------------- 9. SERVIÇOS UTILIZADOS --------------------------------------------------------------- EventRegistrationService (app/Services/EventRegistrationService.php) - registerUser() - cancelRegistrationById() - getUserRegistrations() - getEventRegistrations() - getPendingRegistrations() - confirmRegistrationById() - rejectRegistrationById() EventAttendanceService (app/Services/EventAttendanceService.php) - checkInParticipant() - checkOutParticipant() - getEventAttendance() - generateAttendanceReport() - findParticipantByCode() - getUserAttendance() --------------------------------------------------------------- 10. OBSERVAÇÕES TÉCNICAS --------------------------------------------------------------- - Todas as respostas seguem o padrão JSON com estrutura: { "success": boolean, "data": object/array, "message": string, "timestamp": datetime } - Erros retornam: { "success": false, "message": string, "errors": object (opcional), "timestamp": datetime } - Códigos de status HTTP: - 200: Sucesso - 201: Criado com sucesso - 400: Erro de validação - 401: Não autenticado - 403: Sem permissão - 404: Não encontrado - 500: Erro interno - Rate limiting aplicado nas rotas de autenticação - Logging automático de todas as operações importantes --------------------------------------------------------------- FIM DO RELATÓRIO =============================================