Saltar al contenido principal

🔍 Revisión de Flujos por Rol - PuntoHack MVP

Fecha: 10 de Enero, 2025
Objetivo: Revisar y mejorar los flujos y acciones de cada rol de forma modular

📋 Roles del Sistema​

  1. PARTICIPANT - Participantes de hackathons
  2. ORGANIZER - Organizadores de hackathons
  3. JUDGE - Jueces que evalúan proyectos
  4. SPONSOR - Sponsors y organizaciones
  5. ADMIN - Administradores del sistema

🎯 Metodología de Revisión​

Para cada rol, revisaremos:

  1. Dashboard/Vista principal - ¿Está completo y funcional?
  2. Acciones principales - ¿Todas las acciones están implementadas?
  3. Validaciones - ¿Están todas las validaciones necesarias?
  4. Feedback al usuario - ¿Hay toasts/notificaciones apropiadas?
  5. Manejo de errores - ¿Los errores se manejan correctamente?
  6. UX/UI - ¿La experiencia es fluida y clara?
  7. Consistencia - ¿Sigue los mismos patrones que otros roles?

1️⃣ PARTICIPANT​

Dashboard​

  • ✅ Vista principal: /participant o /dashboard
  • ✅ Muestra: hackathons activos, equipos, notificaciones
  • ✅ Empty states implementados
  • ✅ Loading states con skeleton

Acciones Principales​

1.1 Registrarse en Hackathon​

  • Ruta: /hackathons/[slug]
  • Action: registerForHackathon() (¿existe?)
  • Validaciones necesarias:
    • ✅ Rol = PARTICIPANT
    • ✅ Hackathon status = REGISTRATION
  • ✅ Fechas válidas (registrationOpensAt <= now <= registrationClosesAt)
    • ✅ No registrado previamente
  • Feedback: Toast de éxito/error
  • Estado: ⚠️ Revisar implementación

1.2 Crear Equipo​

  • Ruta: /hackathons/[slug]/teams/create
  • Action: createTeam() en src/modules/teams/actions.ts
  • Validaciones necesarias:
    • ✅ Usuario registrado en hackathon
    • ✅ Hackathon status IN (REGISTRATION, RUNNING)
    • ✅ now < submissionDeadline
    • ✅ No pertenece a otro equipo
  • Feedback: Toast de éxito con código del equipo
  • Estado: ⚠️ Revisar validaciones completas

1.3 Unirse a Equipo​

  • Ruta: /hackathons/[slug]/teams/join
  • Action: joinTeamByCode() en src/modules/teams/actions.ts
  • Validaciones necesarias:
    • ✅ Código existe
    • ✅ Equipo pertenece al hackathon
    • ✅ Equipo no lleno (maxTeamSize)
    • ✅ Usuario registrado en hackathon
    • ✅ No pertenece a otro equipo
    • ✅ Hackathon status IN (REGISTRATION, RUNNING)
    • ✅ now < submissionDeadline
  • Feedback: Toast de éxito/error
  • Estado: ⚠️ Revisar validaciones completas

1.4 Salir del Equipo​

  • Ruta: /hackathons/[slug]/teams/[teamId]
  • Action: leaveTeam() (¿existe?)
  • Validaciones necesarias:
    • ✅ Usuario es miembro del equipo
    • ✅ Hackathon status IN (REGISTRATION, RUNNING)
    • ✅ now < submissionDeadline
    • ✅ Si equipo tiene submission y es último miembro: BLOQUEAR
    • ✅ Si equipo vacío y sin submission: eliminar equipo
  • Feedback: Toast de éxito/error con advertencia si aplica
  • Estado: ⚠️ Revisar implementación

1.5 Enviar Submission​

  • Ruta: /hackathons/[slug]/teams/[teamId]/submit
  • Action: createSubmission() en src/modules/submissions/actions.ts
  • Validaciones necesarias:
    • ✅ Usuario es miembro del equipo
    • ✅ Hackathon status = RUNNING
    • ✅ now < submissionDeadline
    • ✅ Equipo no tiene submission previa
    • ✅ Equipo tiene >= minTeamSize miembros
    • ✅ Si challengeId, pertenece al hackathon
  • Feedback: Toast de éxito/error
  • Estado: ⚠️ Revisar validaciones completas

1.6 Editar Submission​

  • Ruta: /hackathons/[slug]/teams/[teamId]/submit
  • Action: updateSubmission() en src/modules/submissions/actions.ts
  • Validaciones necesarias:
    • ✅ Usuario es miembro del equipo
    • ✅ now < submissionDeadline
    • ✅ Hackathon status != JUDGING/FINISHED
  • Feedback: Toast de éxito/error
  • Estado: ⚠️ Revisar bloqueo después de deadline

1.7 Ver Leaderboard​

  • Ruta: /hackathons/[slug]/leaderboard
  • Query: calculateLeaderboard() en src/modules/evaluation/queries.ts
  • Validaciones necesarias:
    • ✅ Hackathon status = FINISHED (o permitir ver en JUDGING)
  • Feedback: N/A (solo lectura)
  • Estado: ✅ Implementado

Mejoras Identificadas​

  • Verificar que todas las validaciones estén implementadas
  • Agregar validación de minTeamSize al crear equipo
  • Mejorar feedback cuando no puede salir del equipo (último miembro con submission)
  • Agregar countdown visual para submissionDeadline
  • Verificar que el bloqueo de edición después de deadline funcione correctamente

2️⃣ ORGANIZER​

Dashboard​

  • ✅ Vista principal: /organizer
  • ✅ Muestra: hackathons, estadísticas
  • ✅ Empty states implementados
  • ✅ Loading states con skeleton

Acciones Principales​

2.1 Crear Hackathon​

  • Ruta: /admin/hackathons/create
  • Action: createHackathon() en src/modules/hackathons/actions.ts
  • Validaciones necesarias:
    • ✅ Rol = ORGANIZER/ADMIN
    • ✅ Slug único
    • ✅ Orden de fechas válido
    • ✅ Datos válidos (Zod)
  • Feedback: Toast de éxito/error
  • Estado: ✅ Implementado

2.2 Editar Hackathon​

  • Ruta: /admin/hackathons/[slug]/edit
  • Action: updateHackathon() en src/modules/hackathons/actions.ts
  • Validaciones necesarias:
    • ✅ Ownership o ADMIN
    • ✅ Orden de fechas válido
    • ✅ Si extiende fechas: solo fase siguiente, máximo +7d
  • Feedback: Toast de éxito/error
  • Estado: ⚠️ Revisar validación de extensión de fechas

2.3 Publicar Hackathon​

  • Ruta: /admin/hackathons/[slug]/dashboard
  • Action: publishHackathon() (¿existe?)
  • Validaciones necesarias:
    • ✅ Tiene al menos 1 criterio
    • ✅ Tiene al menos 1 juez asignado
    • ✅ now >= registrationOpensAt
    • ✅ Orden de fechas válido
  • Feedback: Toast de éxito/error con advertencia si falta algo
  • Estado: ⚠️ Revisar implementación

2.4 Asignar Jueces​

  • Ruta: /admin/hackathons/[slug]/judges
  • Action: assignJudge() en src/modules/evaluation/actions.ts
  • Validaciones necesarias:
    • ✅ Rol = ORGANIZER/ADMIN
    • ✅ Juez tiene rol JUDGE
    • ✅ Juez NO participa en el hackathon (bloqueo)
    • ✅ Juez no está ya asignado
  • Feedback: Toast de éxito/error con razón si se bloquea
  • Estado: ⚠️ Revisar validación de conflicto de interés

2.5 Eliminar Participación​

  • Ruta: /admin/hackathons/[slug]/dashboard
  • Action: removeParticipation() (¿existe?)
  • Validaciones necesarias:
    • ✅ Ownership o ADMIN
    • ✅ Si usuario tiene TeamMember: eliminar también
    • ✅ Si equipo queda vacío y sin submission: eliminar equipo
    • ✅ Si equipo tiene submission: BLOQUEAR eliminación del último miembro
  • Feedback: Toast de éxito/error con advertencia
  • Estado: ⚠️ Revisar implementación

2.6 Expulsar Miembro de Equipo​

  • Ruta: /admin/hackathons/[slug]/dashboard
  • Action: removeTeamMember() (¿existe?)
  • Validaciones necesarias:
    • ✅ Ownership o ADMIN
    • ✅ Si equipo queda vacío y sin submission: eliminar equipo
    • ✅ Si equipo tiene submission: BLOQUEAR si es último miembro
  • Feedback: Toast de éxito/error con advertencia
  • Estado: ⚠️ Revisar implementación

Mejoras Identificadas​

  • Verificar validación de extensión de fechas (solo fase siguiente, +7d max)
  • Agregar validación de conflicto de interés al asignar jueces
  • Mejorar feedback cuando no puede eliminar participación (último miembro con submission)
  • Agregar validación de publicación (criterios, jueces, fechas)
  • Verificar que todas las acciones de gestión de participantes estén implementadas

3️⃣ JUDGE​

Dashboard​

  • ✅ Vista principal: /judge
  • ✅ Muestra: asignaciones, progreso de evaluación
  • ✅ Empty states implementados
  • ✅ Loading states con skeleton

Acciones Principales​

3.1 Ver Submissions​

  • Ruta: /judge/hackathons/[slug]
  • Query: getHackathonSubmissionsForJudge() (¿existe?)
  • Validaciones necesarias:
    • ✅ Juez asignado al hackathon
    • ✅ Hackathon status = JUDGING (o permitir ver antes)
  • Feedback: N/A (solo lectura)
  • Estado: ⚠️ Revisar implementación

3.2 Evaluar Submission (General)​

  • Ruta: /judge/hackathons/[slug]/submissions/[submissionId]/evaluate
  • Action: submitScores() en src/modules/evaluation/actions.ts
  • Validaciones necesarias:
    • ✅ Juez asignado al hackathon
    • ✅ Hackathon status = JUDGING
    • ✅ Submission pertenece al hackathon
    • ✅ Score value entre 0 y maxScore
    • ✅ No ha evaluado previamente (unique constraint)
  • Feedback: Toast de éxito/error
  • Estado: ✅ Implementado

3.3 Evaluar Challenge​

  • Ruta: /judge/hackathons/[slug]/submissions/[submissionId]/evaluate
  • Action: submitChallengeEvaluation() en src/modules/evaluation/actions.ts
  • Validaciones necesarias:
    • ✅ Juez asignado al hackathon
    • ✅ Challenge pertenece al hackathon
    • ✅ Submission eligió el challenge
    • ✅ Scores entre 0-10
  • Feedback: Toast de éxito/error
  • Estado: ✅ Implementado

Mejoras Identificadas​

  • Verificar que no pueda ver submissions antes de JUDGING
  • Verificar que no pueda ver scores de otros jueces durante JUDGING
  • Agregar validación de que no puede participar en el mismo hackathon
  • Mejorar feedback cuando intenta evaluar algo que ya evaluó
  • Verificar que todas las validaciones de evaluación estén implementadas

4️⃣ SPONSOR​

Dashboard​

  • ✅ Vista principal: /sponsor
  • ✅ Muestra: organizaciones, sponsorships, challenges, shortlist
  • ✅ Empty states implementados
  • ✅ Loading states con skeleton

Acciones Principales​

4.1 Crear Organización​

  • Ruta: /sponsor/organizations/create
  • Action: createOrganization() en src/modules/sponsors/actions.ts
  • Validaciones necesarias:
    • ✅ Rol = SPONSOR/ADMIN
    • ✅ Datos válidos (Zod)
  • Feedback: Toast de éxito/error
  • Estado: ✅ Implementado

4.2 Crear Sponsorship​

  • Ruta: /sponsor/sponsorships/create
  • Action: createSponsorship() en src/modules/sponsors/actions.ts
  • Validaciones necesarias:
    • ✅ Usuario es miembro de la organización (OWNER/ADMIN)
    • ✅ Hackathon existe y no está FINISHED
    • ✅ Datos válidos (Zod)
  • Feedback: Toast de éxito/error
  • Estado: ⚠️ Revisar validación de membership

4.3 Crear Challenge​

  • Ruta: /sponsor/challenges/create
  • Action: createChallenge() en src/modules/sponsors/actions.ts
  • Validaciones necesarias:
    • ✅ Sponsorship existe
    • ✅ Usuario puede gestionar la organización
    • ✅ Hackathon no está FINISHED
    • ✅ Datos válidos (Zod)
  • Feedback: Toast de éxito/error
  • Estado: ⚠️ Revisar validaciones completas

4.4 Agregar a Shortlist​

  • Ruta: /sponsor/challenges/[id]/submissions
  • Action: shortlistSubmission() en src/modules/sponsors/actions.ts
  • Validaciones necesarias:
    • ✅ Submission pertenece al challenge
    • ✅ Usuario puede gestionar la organización
    • ✅ No duplicado (unique constraint)
  • Feedback: Toast de éxito/error
  • Estado: ✅ Implementado

4.5 Aprobar Evaluación de Challenge​

  • Ruta: /sponsor/evaluations o /sponsor/challenges/[id]/evaluations
  • Action: approveChallengeEvaluation() en src/modules/evaluation/actions.ts
  • Validaciones necesarias:
    • ✅ Evaluación pertenece a challenge de la organización
    • ✅ Usuario puede gestionar la organización
    • ✅ Estado = PENDING
  • Feedback: Toast de éxito/error
  • Estado: ✅ Implementado

Mejoras Identificadas​

  • Verificar validación de membership en todas las acciones
  • Agregar validación de que no puede ver scores durante JUDGING
  • Mejorar feedback cuando no puede gestionar organización
  • Verificar que todas las acciones de shortlist estén implementadas
  • Agregar validación de que challenge pertenece al hackathon correcto

5️⃣ ADMIN​

Dashboard​

  • ✅ Vista principal: /admin
  • ✅ Muestra: estadísticas globales, usuarios, hackathons
  • ✅ Empty states implementados
  • ✅ Loading states con skeleton

Acciones Principales​

5.1 Cambiar Rol de Usuario​

  • Ruta: /admin/users
  • Action: updateUserRole() (¿existe?)
  • Validaciones necesarias:
    • ✅ Rol = ADMIN
    • ✅ Nuevo rol válido
    • ✅ No puede quitarse su propio rol ADMIN
  • Feedback: Toast de éxito/error con advertencia
  • Estado: ⚠️ Revisar implementación

5.2 Eliminar Usuario​

  • Ruta: /admin/users
  • Action: deleteUser() (¿existe?)
  • Validaciones necesarias:
    • ✅ Rol = ADMIN
    • ✅ Cascade: participations, team members, scores, etc.
    • ✅ Advertencia antes de eliminar
  • Feedback: Toast de éxito/error con advertencia
  • Estado: ⚠️ Revisar implementación

5.3 Gestionar Hackathons​

  • Ruta: /admin/hackathons
  • Actions: createHackathon(), updateHackathon(), deleteHackathon() (¿existe?)
  • Validaciones necesarias:
    • ✅ Rol = ADMIN
    • ✅ Puede override validaciones (con advertencia)
  • Feedback: Toast de éxito/error con advertencia si override
  • Estado: ⚠️ Revisar implementación completa

Mejoras Identificadas​

  • Verificar que todas las acciones de gestión de usuarios estén implementadas
  • Agregar advertencias cuando hace override de validaciones
  • Agregar validación de que no puede quitarse su propio rol ADMIN
  • Verificar que todas las acciones de gestión de hackathons estén implementadas
  • Agregar confirmaciones para acciones destructivas

📊 Resumen de Mejoras por Prioridad​

🔴 Alta Prioridad​

  1. Validaciones faltantes en acciones críticas
  2. Feedback mejorado para acciones que pueden fallar
  3. Validación de conflictos de interés (juez participante)
  4. Validación de extensión de fechas (solo fase siguiente, +7d)
  5. Validación de membership en acciones de sponsor

🟡 Media Prioridad​

  1. Countdown visual para deadlines
  2. Confirmaciones para acciones destructivas
  3. Advertencias cuando se bloquean acciones
  4. Validación de publicación de hackathons
  5. Mejoras de UX en flujos complejos

🟢 Baja Prioridad​

  1. Optimizaciones de queries
  2. Mejoras visuales menores
  3. Documentación de flujos
  4. Tests adicionales

🎯 Próximos Pasos​

  1. Revisar cada acción identificada
  2. Implementar validaciones faltantes
  3. Mejorar feedback al usuario
  4. Agregar confirmaciones donde sea necesario
  5. Verificar consistencia entre roles

Última actualización: 10 de Enero, 2025