ALURA LATAM - ONE - Oracle Next Education.

ForoHub API: Foro educativo de programación y desarrollo de software.

Desarrollado por: Mariana Andrea Lois (Lady Marianne).

ForoHub es un foro educativo para discutir y aprender sobre diferentes tópicos relacionados con los siguientes temas:

• Desarrollo backend y frontend.
• DevOps.
• Ingeniería de software.
• Bases de datos.

Los usuarios pueden crear tópicos, responder a ellos, y editar tanto tópicos como respuestas dentro de un marco de reglas de tiempo específicas. La API está construida con Spring Boot y utiliza JWT para su autenticación.

Descripción:

Esta aplicación es un foro donde los usuarios pueden:

• Crear y editar tópicos.
• Responder a los tópicos existentes.
• Editar los tópicos y las respuestas dentro de una hora desde la publicación.
• Respetar restricciones de horario para realizar publicaciones (7:00 AM a 11:59 PM).

Funcionalidades:

Tópicos (TopicController):

• POST /topics: Crear un nuevo tópico que será moderado automáticamente por OpenAI.
• GET /topics: Listar todos los tópicos activos, cerrados o archivados.
• GET /topics/{id}: Obtener detalles de un tópico específico.
• PUT /topics/{id}: Editar un tópico dentro de la primera hora después de su creación.
• DELETE /topics/{id}: Eliminar un tópico (cambiar estado a DELETED). Si el algoritmo de OpenAI dejó un tópico y se detecta que no cumple con las reglas, un adminsitrador puede eliminarlo.
• PUT /topics/{topidId}/status: Aprobar un tópico (cambiar estado a ACTIVE). Si el algoritmo de OpenAI eliminó un tópico y se detecta que cumple con las reglas, un administrador puede aprobarlo.

Respuestas (AnswerController):

• POST /answers: Crear una respuesta a un tópico por topicId.
• GET /answers/{topicId}: Obtener respuestas de un tópico.
• PUT /answers/{id}: Editar una respuesta dentro de la primera hora después de su creación.
• PATCH /answers/{answerId}/solution: Marcar una respuesta como solución, lo cual cierra el tópico.

Autenticación (AuthenticationController):

• POST /login: Iniciar sesión y obtener un token JWT.

Usuarios (UserController):

• POST /users: Crear un nuevo usuario.
• POST /users/admins: Crear un nuevo usuario con rol de administrador.

Cursos (CourseController):

• POST /courses: Crear un nuevo curso por parte de un administrador.
• GET /courses: Listar todos los cursos disponibles.

Reglas de Negocio (BusinessRulesService):

1. Restricciones de horario para publicaciones: Sólo se pueden hacer publicaciones entre las 7:00 AM y las 11:59 PM.
2. Tiempo para editar tópicos: Los tópicos y respuesta sólo se pueden editar dentro de la primera hora después de su creación.

Integración con OpenAI, usando SpringAI, para moderar contenido (ModerationService):

En el proyecto ForoHub, hemos implementado una integración con OpenAI para moderar los contenidos generados por los usuarios antes de que se almacenen en la base de datos. Este sistema asegura que los tópicos creados cumplan con las reglas del foro, promoviendo un ambiente respetuoso y relevante para todos los participantes.

Objetivo de la moderación:

El objetivo principal de esta funcionalidad es validar que:

1. No se publiquen contenidos discriminatorios, ofensivos o insultantes: Por ejemplo, mensajes que fomenten estereotipos o ataquen a personas por su género, etnia, religión u otras características personales.
2. El contenido sea relevante para las temáticas del foro: ForoHub está enfocado en temas relacionados con desarrollo backend y frontend, DevOps, bases de datos e ingeniería de software. Mensajes fuera de estas áreas serán rechazados.

Cómo funciona la integración:

1. Creación del prompt: Cuando un usuario intenta registrar un tópico, el sistema genera un prompt que describe las reglas del foro y presenta el contenido del tópico (título y mensaje) como texto a evaluar.

2. Consulta al modelo de OpenAI: El servicio ModerationService envía el prompt al modelo de lenguaje de OpenAI utilizando la dependencia SpringAI para realizar una solicitud al API.

3. Evaluación del contenido: OpenAI responde con un veredicto: “CUMPLE” o “NO CUMPLE”, indicando si el contenido respeta o no las reglas establecidas.

4. Decisión basada en el resultado:

   • Si el contenido “CUMPLE” con las reglas, el estado del tópico cambia de su estado por default (PENDING) a ACTIVE (activo).
   • Si el contenido “NO CUMPLE”, el estado del tópico cambia a DELETED (eliminado) para evitar su publicación.
   • Si el algoritmo comete un error, un administrador puede revisar el tópico y aprobarlo o rechazarlo.

Código involucrado:

1. Clase ModerationService: Contiene la lógica principal para interactuar con el modelo de OpenAI, enviar el prompt y procesar la respuesta.

2. Clase OpenAIService: Define la configuración y la comunicación directa con la API de OpenAI, utilizando el modelo gpt-4o-mini y configurando los parámetros necesarios para cada solicitud.

3. Clase TopicController: Invoca la moderación desde el endpoint de creación de tópicos (registerTopic) para determinar si el contenido es aceptable.

4. Clase OpenAIconfig: Esta clase configura la integración con la API de OpenAI. Es fundamental

5. para conectar el sistema de moderación del foro con los servicios de OpenAI. A continuación,

6. sus principales características:

• Propósito: Proveer una instancia de OpenAiApi utilizando la clave de API proporcionada por OpenAI.
• Implementación:
  • Define un bean de tipo OpenAiApi mediante la anotación @Bean.
  • Obtiene la clave API desde la variable de entorno OPENAI_API_KEY, asegurando que esta clave esté correctamente configurada. Si no lo está, lanza una excepción para advertir al desarrollador.
  • Devuelve una instancia de OpenAiApi que se utiliza en el servicio de moderación para validar contenidos de los tópicos antes de ser almacenados en la base de datos.
• Seguridad: Se asegura de que la clave API no sea nula ni vacía antes de instanciar el cliente de OpenAI, minimizando posibles errores de configuración.

Esta clase es un componente esencial para garantizar una integración fluida y segura con la API de OpenAI.

Beneficios de la integración:

• Automatización: La moderación automática ahorra tiempo al equipo administrativo del foro.
• Consistencia: Se aplica un conjunto uniforme de reglas a todos los tópicos.
• Prevención proactiva: Los contenidos inapropiados no llegan a ser publicados, manteniendo la calidad del foro.

Con esta implementación, ForoHub se asegura de ofrecer un espacio seguro y útil para su comunidad técnica.

Gestión de Usuarios y Administradores:

En el diseño del proyecto, la clase Admin extiende a la clase base User. Esta herencia nos permite reutilizar los atributos y comportamientos comunes de los usuarios en general, al tiempo que agregamos la distinción necesaria para los administradores.

Modelo de datos:

• Tabla users: Almacena toda la información común a usuarios y administradores, como nombre, correo electrónico, contraseña, y el campo role, que distingue si un usuario es un "USER" o un "ADMIN".

• Tabla admins: Específica para administradores, contiene únicamente las claves foráneas (user_id) que apuntan a las entradas correspondientes en la tabla users. Esto asegura que todos los datos de los administradores, como nombre y correo electrónico, se gestionen en la tabla users.

Implementación en código:

• Clase User:

Es la clase base para todos los usuarios. Incluye atributos como id, name, email, y role (del tipo enum Role, con valores "USER" y "ADMIN"). Es una entidad con su propia tabla en la base de datos (users).

• Clase Admin:

Hereda de User, lo que permite reutilizar sus métodos y atributos. Está anotada con @PrimaryKeyJoinColumn, lo que asegura que cada entrada en la tabla admins corresponde a un user_id en users que tiene el rol ADMIN.

@PrimaryKeyJoinColumn(name = "user_id")

Esto permite que, aunque los datos principales estén en la tabla users, los administradores tengan una tabla específica (admins) para gestionar claves únicas y facilitar futuras expansiones o diferenciaciones.

• Ejemplo de uso:

Al registrar un administrador, el constructor de la clase Admin asegura que el campo "role" se configure automáticamente como ADMIN. Los administradores tienen acceso a funcionalidades exclusivas, como la visualización de tópicos con estados sensibles (por ejemplo, DELETED y PENDING), la creación de cursos, y la aprobación o rechazo de tópicos.

Ventajas de esta implementación:

• Reutilización de código: Los métodos y atributos compartidos entre usuarios y administradores están centralizados en la clase User.
• Flexibilidad: Al mantener una tabla admins, es fácil agregar funcionalidades específicas para administradores en el futuro sin modificar la tabla users.
• Claridad en la base de datos: La separación lógica entre usuarios y administradores es clara gracias al uso de la tabla admins y al campo "role" en users.

Testing (TopicControllerTest):

En el proyecto ForoHub, implementé pruebas utilizando JUnit y Mockito para garantizar el correcto funcionamiento algunos controladores y servicios principales. A continuación, se detalla un resumen de las pruebas realizadas en el controlador TopicController:

1. Prueba de validación de datos (HTTP 400):
   Se asegura que el sistema responda con un código de estado HTTP 400 cuando se intenta registrar un tópico sin datos válidos. Esto garantiza que las validaciones en los DTO y controladores funcionan correctamente.

   • Clase: TopicControllerTest
   • Método: registerTopic_invalidData()
   • Resultado esperado: Respuesta con código de estado 400 Bad Request.

2. Prueba de registro exitoso (HTTP 201):
   Se valida que, al registrar un tópico con datos válidos, el sistema devuelva un código de estado HTTP 201 y el tópico se almacene correctamente en la base de datos.

   • Clase: TopicControllerTest
   • Método: registerTopic_validData()
   • Descripción del proceso:
     • Se crea un mock de usuario autenticado y un mock del curso.
     • Se simula el guardado del tópico utilizando Mockito para interceptar la llamada al repositorio.
     • Se valida la respuesta del controlador para confirmar que el contenido del tópico creado coincide con el esperado.
   • Resultado esperado: Respuesta con código de estado 201 Created y un JSON que representa el tópico registrado.

Tecnologías utilizadas:

• Herramientas de desarrollo:

  • IntelliJ IDEA (IDE).
  • GitHub (control de versiones).
  • GitHub Copilot (asistente de programación).
  • ChatGPT, alias "Ada" (ayudante y compañera de trabajo).

• Backend:

  • Spring Boot 3.x.
  • Spring Security.
  • JPA (Java Persistence API).
  • JWT (JSON Web Token).
  • Lombok (anotaciones para reducir código boilerplate).

• Base de datos:

  • MySQL.
  • Migraciones Flyway.

• Integraciones externas:

  • SpringAI (integración con OpenAI).

• Testing:

  • JUnit.
  • Mockito.

• Documentación:

  • SpringDoc/Swagger UI.

• Probador de API:

  • Insomnia.

Requisitos:

• Java 17 o superior.
• Spring Boot 3.x.
• Maven.
• MySQL (o cualquier base de datos compatible con JPA).

Base de Datos (foro_hub):

Instalación:

1. Clonar el repositorio:

git clone https://github.com/Lady-Marianne/forohub.git

2. Configurar la base de datos y agregar las credenciales en el archivo application.properties:

spring.application.name=forohub

spring.datasource.url=jdbc:mysql://localhost:3306/foro_hub?createDatabaseIfNotExist=true
spring.datasource.username=${DATASOURCE_USERNAME}
spring.datasource.password=${DB_PASSWORD}
forohub.security.secret=${JWT_SECRET_FOROHUB:mi_clave_secreta}
spring.jpa.hibernate.ddl-auto=validate