Saltar al contenido principal

🧠 Logica de Negocio - PuntoHack

Reglas funcionales del MVP. Esta seccion alinea producto, backend y frontend.

📋 Índice​

  1. Roles y Permisos (RBAC)
  2. Ciclo de Vida del Hackathon
  3. Registro y Participaciones
  4. Equipos
  5. Invitaciones y Solicitudes
  6. Submissions
  7. Evaluacion de Submissions
  8. Sponsors y Challenges
  9. Leaderboard y Ranking Global
  10. Metricas y Analytics
  11. Notificaciones y Realtime
  12. Exportacion de Reportes
  13. Integridad y Validaciones
  14. Fuentes de Verdad

🔐 Roles y Permisos (RBAC)​

Roles:

  • ADMIN: administracion global.
  • ORGANIZER: crea y gestiona hackathons.
  • PARTICIPANT: se registra, crea equipos, envia submissions.
  • JUDGE: evalua submissions y challenges.
  • SPONSOR: gestiona organizaciones, sponsorships y challenges.

Reglas:

  • Toda accion critica se valida en servidor antes de modificar datos.
  • Los roles determinan acceso a rutas y acciones.

🕒 Ciclo de Vida del Hackathon​

Estados:

  • DRAFT: configuracion inicial, no visible para participantes.
  • REGISTRATION: abierto para registro y creacion de equipos.
  • RUNNING: periodo activo para trabajo y envio de submissions.
  • JUDGING: evaluacion de jueces.
  • FINISHED: cierre final.

Reglas clave:

  • Las fechas deben cumplir orden cronologico.
  • El cron /api/cron/update-hackathon-states actualiza estados segun las fechas.
  • No se permiten cambios de fechas que rompan el orden o restricciones del estado actual.

🧾 Registro y Participaciones​

Reglas:

  • Un perfil solo puede registrarse una vez por hackathon.
  • El registro solo aplica en estado REGISTRATION.
  • El estado del hackathon controla visibilidad y operaciones permitidas.

👥 Equipos​

Reglas:

  • Un equipo pertenece a un hackathon.
  • Cada hackathon define minTeamSize y maxTeamSize.
  • No se puede exceder maxTeamSize.
  • Si existe submission, el equipo no puede quedar debajo de minTeamSize.
  • Un participante no puede estar en mas de un equipo del mismo hackathon.

✉️ Invitaciones y Solicitudes​

Tipos:

  • EMAIL: invitacion enviada por el lider a un email.
  • CODE: solicitud de union con codigo del equipo.

Estados:

  • PENDING: pendiente de respuesta.
  • ACCEPTED: aceptada y aplicada.
  • REJECTED: rechazada.

Reglas:

  • Solo el lider puede invitar.
  • No se aceptan invitaciones si el equipo esta lleno.
  • No se aceptan invitaciones si el hackathon ya paso la fecha de submission.
  • Un usuario solo puede aceptar invitaciones dirigidas a su email o a su perfil.

📤 Submissions​

Reglas:

  • Un equipo puede enviar submission si:
    • Cumple minTeamSize.
    • El hackathon esta en RUNNING.
    • No se ha pasado submissionDeadline.
  • La submission contiene campos tecnicos requeridos por el MVP (stack, arquitectura, features, etc.).

🧪 Evaluacion de Submissions​

Reglas:

  • Los criterios pertenecen a un hackathon y tienen weight y maxScore.
  • Los jueces evalua por criterio con puntajes dentro del rango permitido.
  • El puntaje total considera pesos para el ranking.

🤝 Sponsors y Challenges​

Reglas:

  • Una organizacion puede tener multiples sponsorships.
  • Un sponsorship puede crear challenges.
  • Los challenges se asocian a un hackathon.
  • Jueces evaluan challenges y sponsors pueden aprobar o rechazar evaluaciones.

🏅 Leaderboard y Ranking Global​

Reglas:

  • El leaderboard usa puntajes ponderados por criterio.
  • Se normaliza para mostrar un maximo de 100 puntos.
  • El ranking global calcula:
    • Puntaje promedio por hackathon.
    • Consistencia (rendimiento agregado por participacion).
    • Top 3 por hackathon (segun promedio de puntajes).

📈 Metricas y Analytics​

Reglas:

  • Los dashboards muestran estadisticas por rol.
  • Las metricas de participante incluyen rendimiento, consistencia y distribuciones.
  • Las metricas de organizer incluyen participaciones, submissions y distribuciones de equipos.

🔔 Notificaciones y Realtime​

Reglas:

  • Eventos relevantes generan notificaciones (invitaciones, aprobaciones, etc.).
  • Realtime depende de que Notification tenga replication habilitada en Supabase.
  • Si Realtime no esta activo, la UI debe seguir funcionando con polling o fetch tradicional.

📄 Exportacion de Reportes​

Reglas:

  • Participantes pueden exportar metricas en:
    • CSV (scores por hackathon).
    • Excel (CSV multi-seccion).
    • PDF (HTML imprimible).

✅ Integridad y Validaciones​

Principios:

  • Nunca confiar en el cliente.
  • Validar inputs con Zod antes de acciones criticas.
  • Enforzar restricciones en el servidor (roles, fechas, estados).

📌 Fuentes de Verdad​

  • Modelos: prisma/schema.prisma.
  • Reglas: src/modules/**/actions.ts y validations.ts.
  • Rutas: src/app/**/page.tsx y src/app/api/**/route.ts.