Skip to content

Latest commit

 

History

History
395 lines (303 loc) · 11.3 KB

API_COMPOS_IMPLEMENTATION.md

File metadata and controls

395 lines (303 loc) · 11.3 KB

API de Competiciones - Implementación Completa

✅ Estado: COMPLETADO

Se ha implementado la API REST completa para el sistema de gestión de competiciones, producciones y archivos.

📊 Resumen de Implementación

Serializers Creados (12 total)

Editions (dpms/compos/serializers/editions.py):

  • EditionListSerializer - Lista mínima de ediciones
  • EditionSerializer - CRUD estándar
  • EditionDetailSerializer - Detalle con compos anidadas
  • HasCompoInlineSerializer - Para mostrar compos dentro de ediciones

Compos (dpms/compos/serializers/compos.py):

  • CompoSerializer - CRUD estándar de tipos de competiciones
  • CompoDetailSerializer - Detalle con ediciones asociadas
  • HasCompoSerializer - Gestión de relación Edition↔Compo

Productions (dpms/compos/serializers/productions.py):

  • ProductionSerializer - Lista de producciones
  • ProductionDetailSerializer - Detalle con archivos anidados
  • ProductionCreateSerializer - Crear/actualizar con validaciones

Files (dpms/compos/serializers/files.py):

  • FileSerializer - Lista de archivos
  • FileUploadSerializer - Subir archivos (multipart)
  • FileUpdateSerializer - Actualizar metadata

ViewSets Creados (5 total)

  1. EditionViewSet - Gestión de ediciones/eventos
  2. CompoViewSet - Gestión de tipos de competiciones
  3. HasCompoViewSet - Configuración Edition↔Compo
  4. ProductionViewSet - Envío y gestión de producciones
  5. FileViewSet - Subida y descarga de archivos

Permisos Personalizados

  • IsAdminOrReadOnly - Solo admins editan, todos leen
  • IsOwnerOrAdmin - Solo dueño o admin editan
  • IsOwner - Solo el dueño edita

🌐 Endpoints Disponibles

Editions

GET    /api/editions/                    # Listar ediciones
POST   /api/editions/                    # Crear edición (admin)
GET    /api/editions/{id}/               # Detalle de edición
PUT    /api/editions/{id}/               # Actualizar (admin)
DELETE /api/editions/{id}/               # Eliminar (admin)
GET    /api/editions/{id}/compos/        # Compos de esta edición
GET    /api/editions/{id}/productions/   # Producciones de esta edición

Query params en /api/editions/:

  • public=true - Solo ediciones públicas
  • open_to_upload=true - Solo las que aceptan envíos

Compos

GET    /api/compos/                      # Listar competiciones
POST   /api/compos/                      # Crear compo (admin)
GET    /api/compos/{id}/                 # Detalle de compo
PUT    /api/compos/{id}/                 # Actualizar (admin)
DELETE /api/compos/{id}/                 # Eliminar (admin)
GET    /api/compos/{id}/productions/     # Producciones de esta compo

HasCompos (Relación Edition↔Compo)

GET    /api/hascompos/                   # Listar asociaciones
POST   /api/hascompos/                   # Crear asociación (admin)
GET    /api/hascompos/{id}/              # Detalle
PUT    /api/hascompos/{id}/              # Actualizar config (admin)
DELETE /api/hascompos/{id}/              # Eliminar asociación (admin)

Query params en /api/hascompos/:

  • edition={id} - Filtrar por edición
  • compo={id} - Filtrar por compo

Productions

GET    /api/productions/                 # Listar producciones
POST   /api/productions/                 # Enviar producción (auth)
GET    /api/productions/{id}/            # Detalle con archivos
PUT    /api/productions/{id}/            # Actualizar (owner/admin)
DELETE /api/productions/{id}/            # Eliminar (owner/admin)
GET    /api/productions/my-productions/  # Mis producciones (auth)

Query params en /api/productions/:

  • edition={id} - Filtrar por edición
  • compo={id} - Filtrar por compo
  • my_productions=true - Solo las mías

Files

GET    /api/files/                       # Listar mis archivos (auth)
POST   /api/files/                       # Subir archivo (multipart, auth)
GET    /api/files/{id}/                  # Detalle de archivo
PUT    /api/files/{id}/                  # Actualizar metadata (owner/admin)
DELETE /api/files/{id}/                  # Eliminar archivo (owner/admin)
GET    /api/files/{id}/download/         # Descargar archivo

🔒 Seguridad y Validaciones

Validaciones Implementadas

ProductionCreateSerializer:

  • ✅ Verifica que edition.open_to_upload == True
  • ✅ Verifica que HasCompo.open_to_upload == True
  • ✅ Verifica que la compo existe en esa edición
  • ✅ Verifica que los archivos pertenecen al usuario actual
  • ✅ Al actualizar: verifica que open_to_update == True

FileUploadSerializer:

  • ✅ Límite de tamaño: 100MB máximo
  • ✅ Almacena original_filename automáticamente
  • ✅ Genera nombre UUID único

HasCompoSerializer:

  • ✅ Previene duplicados (misma edition+compo)

Permisos por Endpoint

Endpoint Acción Permiso
/api/editions/ GET AllowAny (solo públicas si no auth)
/api/editions/ POST/PUT/DELETE IsAuthenticated + IsAdminUser
/api/compos/ GET AllowAny
/api/compos/ POST/PUT/DELETE IsAuthenticated + IsAdminUser
/api/productions/ GET AllowAny
/api/productions/ POST IsAuthenticated
/api/productions/{id}/ PUT/DELETE IsAuthenticated + IsOwnerOrAdmin
/api/files/ * IsAuthenticated + IsOwnerOrAdmin

Soft Delete en Files

Los archivos NO se eliminan físicamente, se marcan como is_deleted=True:

def perform_destroy(self, instance):
    instance.is_deleted = True
    instance.is_active = False
    instance.save()

🧪 Ejemplos de Uso

1. Crear una Edición (Admin)

curl -X POST http://localhost:8000/api/editions/ \
  -H "Authorization: Token YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Posadas Party 2025",
    "description": "Demo party en Posadas",
    "public": true,
    "open_to_upload": true,
    "open_to_update": false
  }'

2. Crear una Compo (Admin)

curl -X POST http://localhost:8000/api/compos/ \
  -H "Authorization: Token YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Demo",
    "description": "Competición de demos"
  }'

3. Asociar Compo a Edición (Admin)

curl -X POST http://localhost:8000/api/hascompos/ \
  -H "Authorization: Token YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "edition": 1,
    "compo": 1,
    "start": "2025-12-20T20:00:00Z",
    "show_authors_on_slide": true,
    "open_to_upload": true,
    "open_to_update": true
  }'

4. Subir un Archivo (Usuario)

curl -X POST http://localhost:8000/api/files/ \
  -H "Authorization: Token YOUR_USER_TOKEN" \
  -F "file=@/path/to/demo.zip" \
  -F "title=My Demo File" \
  -F "description=Demo executable" \
  -F "public=false"

5. Enviar una Producción (Usuario)

curl -X POST http://localhost:8000/api/productions/ \
  -H "Authorization: Token YOUR_USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My Awesome Demo",
    "authors": "DemoGroup",
    "description": "A great demo!",
    "edition": 1,
    "compo": 1,
    "files": [1, 2]
  }'

6. Ver Producciones de una Edición

curl http://localhost:8000/api/editions/1/productions/

7. Ver Mis Producciones

curl -H "Authorization: Token YOUR_USER_TOKEN" \
  http://localhost:8000/api/productions/my-productions/

8. Descargar un Archivo

curl -H "Authorization: Token YOUR_USER_TOKEN" \
  http://localhost:8000/api/files/1/download/ \
  --output demo.zip

📁 Estructura de Archivos Creados

backend/dpms/compos/
├── serializers/
│   ├── __init__.py           ✅ Exports
│   ├── editions.py           ✅ 4 serializers
│   ├── compos.py             ✅ 3 serializers
│   ├── productions.py        ✅ 3 serializers
│   └── files.py              ✅ 3 serializers
├── views/
│   ├── __init__.py           ✅ Exports
│   ├── editions.py           ✅ EditionViewSet
│   ├── compos.py             ✅ CompoViewSet + HasCompoViewSet
│   ├── productions.py        ✅ ProductionViewSet
│   └── files.py              ✅ FileViewSet
├── permissions.py            ✅ 3 permisos personalizados
└── urls.py                   ✅ Router con 5 viewsets

Total:

  • 13 serializers
  • 5 ViewSets
  • 3 permisos personalizados
  • ~30 endpoints API

🔄 Flujo de Usuario Típico

Usuario Participante

  1. Registrarse → POST /api/users/signup/
  2. Verificar email → GET /api/users/verify/?token=...
  3. Login → POST /api/users/login/
  4. Ver ediciones abiertas → GET /api/editions/?open_to_upload=true
  5. Ver compos disponibles → GET /api/editions/{id}/compos/
  6. Subir archivos → POST /api/files/ (multipart)
  7. Enviar producción → POST /api/productions/
  8. Ver mis producciones → GET /api/productions/my-productions/
  9. Actualizar producción → PUT /api/productions/{id}/ (si aún permitido)

Administrador

  1. Login como admin
  2. Crear edición → POST /api/editions/
  3. Crear compos → POST /api/compos/
  4. Asociar compos a edición → POST /api/hascompos/
  5. Abrir/cerrar envíos → PATCH /api/hascompos/{id}/ (cambiar open_to_upload)
  6. Ver producciones enviadas → GET /api/editions/{id}/productions/
  7. Moderar → PUT/DELETE /api/productions/{id}/

✅ Validaciones de Negocio

Al Enviar Producción

  1. ✅ La edición debe estar open_to_upload=true
  2. ✅ El HasCompo debe estar open_to_upload=true
  3. ✅ La compo debe existir en esa edición (HasCompo)
  4. ✅ Los archivos deben pertenecer al usuario actual
  5. ✅ Usuario debe estar autenticado y verificado

Al Actualizar Producción

  1. ✅ El usuario debe ser el owner o admin
  2. ✅ La edición debe estar open_to_update=true
  3. ✅ El HasCompo debe estar open_to_update=true

Al Subir Archivo

  1. ✅ Tamaño máximo: 100MB
  2. ✅ Usuario debe estar autenticado
  3. ✅ Se guarda el original_filename
  4. ✅ Se genera nombre único con UUID

🚀 Próximos Pasos

La API está completamente funcional pero falta el frontend React:

Frontend Pendiente (Fase 3)

  1. Componentes a crear:

    • ComposList.js - Ver competiciones
    • ProductionForm.js - Formulario de envío
    • MyProductions.js - Mis producciones
    • FileUpload.js - Componente de subida
    • ProductionDetail.js - Ver detalle

  2. Rutas a añadir:

    • /app/compos
    • /app/my-productions
    • /app/productions/new
    • /app/productions/:id

  3. Navegación:

    • Añadir enlaces en MainBar
    • Dashboard con resumen

📊 Estadísticas

  • Archivos creados: 8
  • Líneas de código: ~1,500
  • Serializers: 13
  • ViewSets: 5
  • Endpoints: ~30
  • Permisos: 3 personalizados
  • Validaciones: 10+ reglas de negocio

🧪 Testing Rápido

# 1. Ver endpoints disponibles
curl http://localhost:8000/api/editions/
curl http://localhost:8000/api/compos/
curl http://localhost:8000/api/productions/

# 2. Ver Swagger docs
open http://localhost:8000/docs/

# 3. Ver URLs registradas
docker compose -f local.yml exec backend_party python manage.py show_urls | grep api

¡API de Competiciones completamente implementada y funcionando! 🎉