AGENTS.md - Guía para Agentes de IA en Tarea5PAUF-PeliculasMongo

Arquitectura General

Esta es una API REST de películas construida con Spring Boot 4.0.3, Java 25 y MongoDB. La arquitectura sigue el patrón MVC con servicios de negocio e integra autenticación JWT con Spring Security.

Componentes principales:

• Modelos (models/): Entidades de dominio con documentos embebidos (comentarios, valoraciones en películas; favoritas en usuarios) y referencias DBRef.
• Repositorios (repositories/): Interfaces que extienden MongoRepository para operaciones CRUD básicas.
• Servicios (services/): Lógica de negocio, conversiones DTO y manejo de relaciones embebidas.
• Controladores (controllers/): Endpoints REST con CORS habilitado globalmente.
• DTOs (dtos/): Objetos de transferencia para respuestas, evitando exponer entidades internas.
• Seguridad (security/): NUEVO - Componentes JWT (generación, validación, filtro).
• Configuración (config/): NUEVO - Configuración de Spring Security con JWT.

Patrones de datos:

• Documentos embebidos para listas (ej. Pelicula.comentarios como List<Comentario>).
• Referencias DBRef en embebidos (ej. Comentario.autor con @DBRef y @JsonIdentityReference(alwaysAsId = true)).
• Inicialización de listas vacías en servicios al guardar entidades nuevas.

Convenciones de Código

• Lombok obligatorio: Todas las clases usan @Setter, @Getter, @AllArgsConstructor, @NoArgsConstructor, @Builder. Ver Pelicula.java.
• Inyección de dependencias: Usa @Autowired en servicios y controladores. Ejemplo en PeliculaService.java.
• Manejo de fechas: Servicios preservan fechas existentes en actualizaciones; asignan LocalDate.now() en creaciones. Ver PeliculaService.save().
• Conversiones DTO: Servicios convierten entidades a DTOs para respuestas. Ejemplo: PeliculaService.convertirDTO() mapea listas embebidas a DTOs.
• CORS: Controladores anotados con @CrossOrigin(origins = "*") para desarrollo.
• Seguridad: NUEVO - Contraseñas cifradas con BCrypt. Tokens JWT de 24 horas. Rutas públicas: /api/auth/login, /api/auth/register. Resto requiere JWT válido en header Authorization: Bearer <token>.

Flujos de Trabajo Críticos

• Construcción: mvn clean install para compilar; mvn spring-boot:run para ejecutar. Requiere Maven wrapper (mvnw).
• Base de datos: MongoDB en localhost:27017, colecciones "peliculas" y "usuarios". Configurado en application.properties con spring.mongodb.uri.
• Pruebas: Ejecutar con mvn test. Ver ApiPaginaPeliculasApplicationTests.java para pruebas básicas.
• Debugging: Usar logs de Spring; verificar serialización JSON con @JsonIdentityInfo comentado en modelos.
• Autenticación: NUEVO - Registrar usuario en /api/auth/register, obtener token en /api/auth/login, enviar token en header Authorization de requests posteriores.

Puntos de Integración

• Relaciones embebidas: Agregar comentarios/valoraciones actualiza el documento padre. Ejemplo: PeliculaService.addComentario() busca usuario por ID y embebido en película.
• Favoritas: Simples objetos embebidos en Usuario.favoritas, sin referencias complejas. Ver UsuarioService.addFavorita().
• Serialización: Evita ciclos con @JsonIdentityReference en referencias DBRef.
• Autenticación: NUEVO - JwtTokenProvider genera/valida tokens; JwtAuthenticationFilter extrae e inyecta en contexto de seguridad; SecurityConfig define rutas públicas/protegidas.

Archivos clave para entender flujos:

• PeliculaService.java: Lógica de embebidos y conversiones. MODIFICADO - Incluye conversión a ComentarioDTO/ValoracionDTO con autorNombre y método findAllPaginated().
• PeliculaController.java: Endpoints REST y manejo de DTOs. MODIFICADO - GET /api/peliculas soporta paginación opcional (page, size, sortBy, direction) sin romper el comportamiento sin parámetros.
• UsuarioService.java: MODIFICADO - Incluye métodos register(), authenticateUser(), emailExists(), getFavoritasPeliculas(), updateUsuario() (cifra contraseña con BCrypt si se envía nueva).
• UsuarioController.java: MODIFICADO - updateUsuario() delega al servicio. Incluye endpoints /me, /me/favoritas y delete de favoritas.
• AuthController.java: NUEVO - Endpoints /api/auth/login y /api/auth/register.
• application.properties: Configuración MongoDB y JWT (app.jwt.secret, app.jwt.expiration).
• pom.xml: Dependencias (Lombok, Spring Data MongoDB, Spring Security, JJWT 0.12.3).

IMPLEMENTACIÓN DE JWT (2026-04-01)

Clases Creadas:

1. com.ricardo.peliculas.security.JwtTokenProvider

   • Genera tokens JWT con userId y expiración de 24h
   • Valida y extrae información de tokens
   • Usa JJWT 0.12.3 y SecretKey de 256 bits

2. com.ricardo.peliculas.security.JwtAuthenticationFilter

   • Filtro que se ejecuta en cada request
   • Extrae token del header Authorization: Bearer <token>
   • Inyecta autenticación en SecurityContextHolder

3. com.ricardo.peliculas.config.SecurityConfig

   • Configura Spring Security con política STATELESS
   • Define rutas públicas: /api/auth/login, /api/auth/register
   • Resto de rutas requieren autenticación JWT
   • Bean PasswordEncoder (BCryptPasswordEncoder)

4. com.ricardo.peliculas.controllers.AuthController

   • NUEVO - Controlador específico para autenticación
   • Endpoints: POST /api/auth/register, POST /api/auth/login
   • Responsable de registro y login públicos

5. com.ricardo.peliculas.dtos.LoginRequest

   • DTO con campos email y password

6. com.ricardo.peliculas.dtos.RegisterRequest

   • DTO con campos nombre, email, password

7. com.ricardo.peliculas.dtos.AuthResponse

   • DTO de respuesta con token, id, nombre, email, fechaRegistro

Archivos Modificados:

1. pom.xml

   • Agregadas dependencias: spring-boot-starter-security, jjwt-api, jjwt-impl, jjwt-jackson, spring-security-test

2. UsuarioRepository.java

   • Agregado método Optional<Usuario> findByEmail(String email) para búsqueda en login/register

3. UsuarioService.java

   • Inyectado PasswordEncoder
   • Agregado Optional<Usuario> register(RegisterRequest) - registra usuario con contraseña cifrada
   • Agregado Optional<Usuario> authenticateUser(String email, String password) - valida credenciales
   • Agregado boolean emailExists(String email) - verifica email duplicado

4. UsuarioController.java

   • MODIFICADO - Removidos endpoints de autenticación (movidos a AuthController)
   • Solo mantiene CRUD de usuarios y gestión de favoritas
   • Incluye nuevos endpoints para usuario autenticado: /me, /me/favoritas
   • MODIFICADO - updateUsuario() preserva campos no enviados

5. application.properties

   • Agregadas propiedades: app.jwt.secret, app.jwt.expiration=86400000 (24h)

Objetivo del Cambio:

Implementar autenticación y autorización con JWT manteniendo la estructura existente del proyecto. Permitir registro e inicio de sesión seguro con contraseñas cifradas en BCrypt. Proteger endpoints sensibles mediante tokens JWT sin romper endpoints existentes.

HISTORIAL COMPLETO DE IMPLEMENTACIONES (2026-04-01)

1) Reubicación de autenticación en AuthController

Clases Creadas:

1. com.ricardo.peliculas.controllers.AuthController
   • Endpoint público POST /api/auth/register
   • Endpoint público POST /api/auth/login

Archivos Modificados:

1. UsuarioController.java
   • Removidos endpoints de auth que estaban bajo /api/usuarios/...
   • Mantenido solo CRUD de usuarios y favoritas

Objetivo del Cambio:

Alinear rutas públicas reales con SecurityConfig (/api/auth/login y /api/auth/register) para resolver acceso no público por path incorrecto.

2) Endpoints del usuario autenticado

Archivos Modificados:

1. UsuarioController.java

   • Agregado GET /api/usuarios/me
   • Agregado GET /api/usuarios/me/favoritas
   • Obtención de userId desde SecurityContextHolder

2. UsuarioService.java

   • Agregado método getFavoritasPeliculas(String userId)
   • Reutiliza PeliculaService para devolver PeliculaValComDTO

Objetivo del Cambio:

Permitir al frontend consultar datos y favoritas del usuario autenticado sin exponer contraseña ni requerir el id por URL.

3) Enriquecimiento de respuesta de películas con nombre de autor

Clases Creadas:

1. com.ricardo.peliculas.dtos.ComentarioDTO

   • Campos: autorId, autorNombre, texto, fechaComentario

2. com.ricardo.peliculas.dtos.ValoracionDTO

   • Campos: autorId, autorNombre, puntuacion, fechaValoracion

Archivos Modificados:

1. PeliculaValComDTO.java

   • Cambiado comentarios a List<ComentarioDTO>
   • Cambiado valoraciones a List<ValoracionDTO>

2. PeliculaService.java

   • convertirDTO() ahora incluye autorNombre para comentarios y valoraciones

Objetivo del Cambio:

Evitar llamadas extra desde React para resolver nombres de autores al mostrar comentarios y valoraciones.

4) Corrección de CORS para frontend React

Archivos Modificados:

1. SecurityConfig.java
   • Añadido bean CorsConfigurationSource
   • Origen permitido: http://localhost:5174
   • Métodos permitidos: GET, POST, PUT, DELETE, OPTIONS
   • Headers permitidos: Authorization, Content-Type, Accept, X-Requested-With
   • Integrado con .cors(...) en SecurityFilterChain

Objetivo del Cambio:

Resolver bloqueo de preflight y habilitar login/register desde React sin romper JWT ni rutas protegidas.

5) Actualización parcial segura de usuario (PUT)

Archivos Modificados:

1. UsuarioController.java

   • updateUsuario() delega al servicio

2. UsuarioService.java

   • Agregado updateUsuario(String id, Usuario usuarioData)
   • Preserva campos no enviados (nombre, email, password, más favoritas/fechaRegistro según lógica existente)
   • Si llega contraseña nueva, la cifra con PasswordEncoder (BCrypt)

Objetivo del Cambio:

Mantener comportamiento de actualización parcial sin pérdida de datos y evitando persistir contraseñas en texto plano.

6) Eliminación de favoritas por endpoint REST

Archivos Modificados:

1. UsuarioController.java
   • Agregado DELETE /api/usuarios/{usuarioId}/favoritas/{peliculaId}
   • Reutiliza usuarioService.removeFavorita(...)

Objetivo del Cambio:

Completar CRUD de favoritas con eliminación explícita mediante endpoint dedicado.

7) Paginación opcional en GET /api/peliculas

Archivos Modificados:

1. PeliculaController.java

   • GET /api/peliculas acepta params opcionales: page, size, sortBy, direction
   • Sin page/size: devuelve todo (comportamiento original)
   • Con page/size: devuelve contenido paginado + metadatos

2. PeliculaService.java

   • Agregado findAllPaginated(int page, int size, String sortBy, String direction)
   • Usa PageRequest y Sort

Objetivo del Cambio:

Agregar paginación/ordenación sin romper integraciones existentes que dependen de la lista completa sin parámetros.

Resumen Global del Día

• Se mantuvo la estructura MVC y paquetes existentes.
• Se evitó romper endpoints previos; los cambios fueron incrementales y compatibles.
• Se centralizó la lógica sensible (cifrado/actualización) en servicios.
• Se reforzó integración frontend-backend (CORS, JWT, respuestas enriquecidas).