rckrdmrd/workspace
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
0f29d35578
workspace/projects/gamilit/docs/90-transversal/api/API-SOCIAL-MODULE.md
rckrdmrd 05cd7aa966 docs: Correcciones P2 completas - Social API, componentes, views, inventarios 
Fase 5 completada (21/21 correcciones ejecutadas):

P2-001: Documentar Social API (10 controllers, 106 endpoints)
P2-002: Documentar componentes Frontend (497 componentes, 103 hooks)
P2-003: Actualizar FRONTEND_INVENTORY.yml a v4.0
P2-004: Documentar views Database (17 views en 7 schemas)
P2-005: Documentar rutas duplicadas Auth (requiere refactor)
P2-006: Documentar código muerto Teacher (requiere refactor)

Archivos creados:
- docs/90-transversal/api/API-SOCIAL-MODULE.md
- docs/frontend/COMPONENTES-INVENTARIO.md
- docs/database/VIEWS-INVENTARIO.md

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2025-12-26 15:57:07 -06:00

9.5 KiB
Raw Blame History

API SOCIAL MODULE

Proyecto: GAMILIT - Plataforma Educativa Gamificada Modulo: Social Version: 1.0 Fecha: 2025-12-23 Base URL: /api/v1/social

RESUMEN

Metrica Valor
Controllers 10
Services 10
Endpoints 106
Entidades 13

CONTROLLERS

  1. SchoolsController - Instituciones educativas
  2. ClassroomsController - Aulas virtuales
  3. ClassroomMembersController - Membresia en aulas
  4. TeamsController - Equipos colaborativos
  5. TeamMembersController - Membresia en equipos
  6. TeamChallengesController - Desafios de equipos
  7. FriendshipsController - Amistades
  8. PeerChallengesController - Desafios peer-to-peer
  9. ChallengeParticipantsController - Participantes en desafios
  10. UserActivitiesController - Activity Feed

1. SCHOOLS ENDPOINTS

Base: /social/schools

Method Endpoint Descripcion
GET /schools Listar escuelas
GET /schools/:id Obtener escuela por ID
GET /schools/code/:code Obtener por codigo
POST /schools Crear escuela
PATCH /schools/:id Actualizar escuela
DELETE /schools/:id Desactivar escuela
GET /schools/:id/stats Estadisticas
PATCH /schools/:id/settings Actualizar config

2. CLASSROOMS ENDPOINTS

Base: /social/classrooms

Method Endpoint Descripcion
GET /classrooms Listar aulas
GET /classrooms/:id Obtener aula
GET /classrooms/code/:code Obtener por codigo
POST /classrooms Crear aula
PATCH /classrooms/:id Actualizar aula
DELETE /classrooms/:id Desactivar aula
GET /classrooms/:id/stats Estadisticas
GET /classrooms/:id/members Listar miembros
POST /classrooms/:id/students/:studentId Inscribir estudiante
DELETE /classrooms/:id/students/:studentId Retirar estudiante
PATCH /classrooms/:id/schedule Actualizar horario
GET /teachers/:teacherId/classrooms/active Aulas del profesor

3. CLASSROOM MEMBERS ENDPOINTS

Base: /social/classroom-members

Method Endpoint Descripcion
GET /classrooms/:id Obtener miembros
GET /users/:userId Aulas del usuario
GET /classrooms/:id/users/:userId Membresia especifica
POST / Inscribir estudiante
PATCH /:id/status Actualizar estado
PATCH /:id/grade Registrar calificacion
PATCH /:id/attendance Actualizar asistencia
POST /:id/withdraw Marcar retirado
GET /classrooms/:id/active Miembros activos
GET /classrooms/:id/leaderboard Leaderboard del aula

Estados: active, inactive, withdrawn, completed

4. TEAMS ENDPOINTS

Base: /social/teams

Method Endpoint Descripcion
GET /teams Listar equipos
GET /teams/:id Obtener equipo
GET /teams/code/:code Obtener por codigo
POST /teams Crear equipo
PATCH /teams/:id Actualizar equipo
DELETE /teams/:id Eliminar equipo
POST /teams/:id/members/:userId Agregar miembro
DELETE /teams/:id/members/:userId Remover miembro
PATCH /teams/:id/score Actualizar puntuacion
POST /teams/:id/xp Agregar XP
GET /teams/:id/stats Estadisticas
GET /teams/:id/members Listar miembros
GET /classrooms/:id/teams/leaderboard Leaderboard equipos

5. TEAM MEMBERS ENDPOINTS

Base: /social/team-members

Method Endpoint Descripcion
GET /teams/:teamId Miembros del equipo
GET /users/:userId Equipos del usuario
GET /teams/:id/users/:userId Membresia especifica
POST / Unirse a equipo
PATCH /:id/role Actualizar rol
DELETE /:id Salir del equipo
GET /teams/:id/active Miembros activos
POST /teams/:id/transfer-ownership Transferir propiedad

Roles: owner, admin, member

6. TEAM CHALLENGES ENDPOINTS

Base: /social/team-challenges

Method Endpoint Descripcion
GET /teams/:teamId Desafios del equipo
GET /challenges/:id Equipos en desafio
GET /teams/:id/challenges/:id Registro especifico
POST / Asignar desafio
PATCH /:id/status Actualizar estado
PATCH /:id/score Registrar puntuacion
POST /:id/complete Completar
POST /:id/fail Marcar fallido
GET /challenges/:id/leaderboard Leaderboard

Estados: active, in_progress, completed, failed

7. FRIENDSHIPS ENDPOINTS

Base: /social/users/:userId/friends

Method Endpoint Descripcion
GET /users/:userId/friends Listar amigos
GET /users/:userId/friends/pending Solicitudes pendientes
GET /users/:userId/friends/sent Solicitudes enviadas
POST /friendships/request Enviar solicitud
PATCH /friendships/:id/accept Aceptar
PATCH /friendships/:id/reject Rechazar
POST /users/:userId/block/:friendId Bloquear usuario
DELETE /users/:userId/block/:friendId Desbloquear
DELETE /users/:userId/friends/:friendId Eliminar amistad
GET /users/:id1/:id2/friendship Verificar estado

Estados: pending, accepted, rejected, blocked

8. PEER CHALLENGES ENDPOINTS (EPIC EXT-009)

Base: /social/peer-challenges

Method Endpoint Descripcion
POST / Crear desafio P2P
GET / Listar desafios
GET /open Desafios abiertos
GET /active Desafios activos
GET /:id Obtener desafio
GET /creator/:userId Desafios del creador
PATCH /:id Actualizar desafio
PATCH /:id/start Iniciar desafio
PATCH /:id/complete Completar
PATCH /:id/cancel Cancelar
PATCH /mark-expired Marcar expirados
DELETE /:id Eliminar
GET /stats/by-type Stats por tipo
GET /stats/by-status Stats por estado

Tipos: head_to_head, multiplayer, tournament, leaderboard Estados: open, full, in_progress, completed, cancelled, expired

9. CHALLENGE PARTICIPANTS ENDPOINTS (EPIC EXT-009)

Base: /social/challenge-participants

Method Endpoint Descripcion
POST / Agregar participante
GET /challenge/:id Participantes
GET /challenge/:id/user/:userId Participacion especifica
GET /user/:userId Desafios del usuario
PATCH /challenge/:id/user/:userId/accept Aceptar invitacion
PATCH /challenge/:id/user/:userId/status Actualizar estado
PATCH /challenge/:id/user/:userId/score Actualizar score
PATCH /challenge/:id/rankings Calcular rankings
PATCH /challenge/:id/winner Determinar ganador
POST /challenge/:id/user/:userId/rewards Distribuir recompensa
POST /challenge/:id/rewards Distribuir a todos
PATCH /challenge/:id/user/:userId/forfeit Abandonar
PATCH /challenge/:id/user/:userId/disqualify Descalificar
DELETE /challenge/:id/user/:userId Eliminar participante
GET /user/:userId/stats Estadisticas usuario

Estados: invited, accepted, in_progress, completed, forfeit, disqualified

10. USER ACTIVITIES ENDPOINTS (TASK 2.5)

Base: /social/activities

Method Endpoint Descripcion
GET /users/:userId/activities/me Mis actividades
GET /activities/feed Feed de amigos
POST /activities Crear actividad
GET /activities/:id Obtener actividad
GET /activities/public/all Actividades publicas

Tipos: achievement, exercise, rankup, level_up

ENTIDADES

Entidad Descripcion
School Instituciones educativas
Classroom Aulas virtuales
ClassroomMember Membresia en aulas
Team Equipos colaborativos
TeamMember Membresia en equipos
TeamChallenge Desafios de equipos
Friendship Relaciones de amistad
PeerChallenge Desafios peer-to-peer
ChallengeParticipant Participantes en desafios
UserActivity Activity Feed
TeacherClassroom Relacion profesor-aula
AssignmentClassroom Asignaciones a aulas
DiscussionThread Hilos de discusion

SERVICES

  1. SchoolsService - CRUD escuelas, estadisticas
  2. ClassroomsService - CRUD aulas, inscripcion
  3. ClassroomMembersService - Membresia, calificaciones
  4. TeamsService - CRUD equipos, leaderboards
  5. TeamMembersService - Membresia, roles
  6. TeamChallengesService - Asignacion desafios
  7. FriendshipsService - Gestión amistades
  8. PeerChallengesService - Desafios P2P
  9. ChallengeParticipantsService - Participantes, recompensas
  10. UserActivitiesService - Activity Feed

CARACTERISTICAS

Multi-Tenancy

  • Escuelas asociadas a tenant_id
  • Filtrado automatico en consultas

Gamificacion

  • Puntuaciones (score, total_score)
  • Experiencia (XP, total_xp)
  • Leaderboards por aula, equipo, desafio
  • Recompensas (XP + ML Coins)

Gestion de Miembros

  • Estados: active, inactive, withdrawn, completed
  • Calificaciones y asistencia
  • Roles: owner, admin, member

Validaciones

  • Codigos unicos por escuela, aula, equipo
  • Capacidad maxima
  • Control de permisos

Generado por: Requirements-Analyst Fecha: 2025-12-23 Version: 1.0