rckrdmrd/workspace
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
main
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

308 lines
9.5 KiB
Markdown
Raw Permalink 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
Reference in New Issue View Git Blame Copy Permalink