Refinamiento Arquitectónico - Sprint 3

Visión General de la Arquitectura

El Sprint 3 se enfoca en la implementación de los flujos centrales del sistema: la Solicitud de Feedback por parte de los colaboradores y la Respuesta de Feedback por los evaluadores externos. Esta fase es crucial para materializar el core business de la aplicación, involucrando la creación y orquestación de funcionalidades en los microservicios de FeedbackRequestService y FeedbackResponseService, además de interacciones significativas con el Frontend, el API Gateway y el servicio de notificaciones por correo electrónico.

La arquitectura continuará siguiendo los principios de microservicios, Domain-Driven Design (DDD) y comunicación vía API RESTful, garantizando escalabilidad, mantenibilidad y claridad en las responsabilidades de cada componente.

Componentes Arquitectónicos Clave para el Sprint 3

Durante el Sprint 3, los siguientes componentes serán desarrollados o tendrán sus funcionalidades expandidas:

1. Microservicio de Solicitud de Feedback (FeedbackRequestService - Java/Spring Boot)

Responsable de todo el ciclo de vida de la solicitud de feedback:

• Creación y Edición de Solicitudes: Permitir que los colaboradores creen y editen borradores de solicitudes, añadiendo preguntas personalizadas e indicando evaluadores externos.
• Gestión de Estado: Controlar los estados de la solicitud ("en creación", "pendiente aprobación", "esperando respuestas", "finalizado", "rechazado").
• Envío para Aprobación: Enviar la solicitud al PDM correspondiente.
• Proceso de Aprobación/Rechazo: Permitir que los PDM aprueben o rechacen solicitudes, con justificación para el rechazo.
• Generación de Hash para Formularios: Crear un identificador único (hash) para cada formulario, que se usará en los enlaces enviados a los evaluadores.
• Validaciones de Negocio:
  • Mínimo de 3 preguntas personalizadas.
  • Mínimo de 2 y máximo de 9 evaluadores.
  • El correo del evaluador no puede ser del dominio @ciandt.com.br.
  • Un colaborador solo puede crear un nuevo formulario 6 meses después de la finalización del último.
• Notificaciones: Enviar correos a los PDM (nueva solicitud), colaboradores (estado de la solicitud) y evaluadores (invitación para feedback).

2. Microservicio de Respuesta de Feedback (FeedbackResponseService - Java/Spring Boot)

Responsable de gestionar el proceso de respuesta de los evaluadores externos:

• Autenticación del Evaluador:
  • Validar el correo del evaluador (no puede ser @ciandt.com.br).
  • Generar y enviar un código de acceso único por correo electrónico.
  • Validar el código de acceso informado.
• Visualización del Formulario: Presentar el formulario de feedback (preguntas) con base en el hash de la solicitud.
• Validación de Plazo: Verificar si el formulario está dentro del período de 3 meses para responder (a partir de la fecha de aprobación del PDM).
• Recolección y Almacenamiento de Respuestas:
  • Permitir que el evaluador responda a las preguntas o indique "no sabe evaluar".
  • Guardar respuestas como borrador.
  • Finalizar y enviar la evaluación.
• Notificaciones: Informar al colaborador cuando un feedback sea finalizado (si es el último evaluador).
• Actualización de Estado: Señalar al FeedbackRequestService cuando una respuesta es enviada para que el estado general de la solicitud pueda ser actualizado.

3. Frontend (Next.js) - Roles e Interacciones

Se desarrollarán interfaces de usuario específicas para:

• Colaborador:
  • Listar sus solicitudes de feedback (con estado y acciones).
  • Crear un nuevo formulario de solicitud (añadir preguntas, evaluadores).
  • Editar formularios en borrador o rechazados.
  • Eliminar solicitudes (según reglas de estado).
  • Visualizar el estado de la aprobación y de las respuestas.
• PDM (People Development Manager):
  • Listar solicitudes pendientes de su aprobación.
  • Analizar detalles de la solicitud (preguntas, evaluadores).
  • Aprobar o rechazar solicitudes, añadiendo comentarios si se rechaza.
• Evaluador Externo:
  • Página de "login" para ingresar correo y recibir código de acceso.
  • Página para ingresar el código de acceso.
  • Formulario de feedback para responder a las preguntas.
  • Opciones para guardar borrador o finalizar la evaluación.

4. Servicio de Correo Electrónico

Un componente crucial para las notificaciones. Puede ser un servicio interno dedicado o la integración con un proveedor de correo externo. Se utilizará para:

• Enviar código de acceso a los evaluadores.
• Notificar a los PDM sobre nuevas solicitudes de feedback.
• Notificar a los colaboradores sobre el estado de sus solicitudes (aprobada, rechazada, respondida).
• Enviar invitaciones con el enlace (conteniendo el hash) del formulario a los evaluadores.

Diagrama de Componentes del Sprint 3

Decisiones Arquitectónicas del Sprint 3

1. Autenticación de Evaluador Externo vía Código de Acceso por Correo Electrónico:

   • Decisión: Los evaluadores externos se autentican proporcionando su correo electrónico (previamente registrado en la solicitud) y un código de acceso único enviado a ese correo.
   • Justificación: Mecanismo simple y de baja fricción para el evaluador, que no necesita crear una cuenta formal. Garantiza que solo el dueño del correo invitado pueda responder. Evita que colaboradores internos (@ciandt.com.br) respondan, ya que el sistema valida el dominio en el registro y puede reforzarlo en el login.
   • Implicaciones: Fuerte dependencia del servicio de correo electrónico para el flujo de respuesta. Necesidad de gestionar la generación, envío, validez y unicidad de los códigos de acceso.

2. Hashing de ID de Formulario para Enlaces Externos:

   • Decisión: El identificador de la solicitud de feedback usado en los enlaces enviados a los evaluadores será un hash no secuencial y difícil de adivinar, en lugar de un ID numérico directo.
   • Justificación: Aumenta la seguridad por oscuridad, dificultando que terceros intenten adivinar URLs de formularios válidos.
   • Implicaciones: El FeedbackRequestService debe generar y almacenar este hash. El FeedbackResponseService (y el Frontend) utilizarán este hash para buscar e identificar los formularios.

3. Validación de Plazo de Respuesta (3 meses):

   • Decisión: Las respuestas de feedback solo serán aceptadas si se envían dentro de un período de 3 meses a contar desde la fecha de aprobación de la solicitud por el PDM.
   • Justificación: Garantiza que el feedback recolectado sea temporalmente relevante para el desarrollo del colaborador.
   • Implicaciones: El FeedbackResponseService necesita consultar la fecha de aprobación de la solicitud (probablemente vía FeedbackRequestService o directamente de la base de datos compartida/replicada) y compararla con la fecha actual antes de permitir la respuesta.

4. Notificaciones por Correo Electrónico para Eventos Clave:

   • Decisión: Utilizar correos electrónicos para notificar a los usuarios (colaboradores, PDMs, evaluadores) sobre eventos importantes en el ciclo de vida del feedback.
   • Justificación: Mantiene a los usuarios informados e involucrados en el proceso. Es un medio de comunicación estándar y esperado para tales interacciones.
   • Implicaciones: Necesidad de un servicio de correo electrónico confiable y resiliente. Las operaciones de envío de correo deben ser, preferiblemente, asíncronas para no bloquear los flujos principales de la aplicación.

5. Separación Funcional entre FeedbackRequestService y FeedbackResponseService:

   • Decisión: Mantener las lógicas de negocio para la creación/gestión de solicitudes y para el proceso de respuesta en microservicios distintos.
   • Justificación: Alineación con los Bounded Contexts de DDD (Solicitud de Feedback y Respuesta de Feedback). Permite desarrollo, despliegue y escalabilidad independientes para cada contexto.
   • Implicaciones: Necesidad de comunicación inter-servicios (ej., FeedbackResponseService puede necesitar consultar a FeedbackRequestService para obtener detalles del formulario o para notificar sobre una respuesta finalizada). Esta comunicación debe ser diseñada para ser resiliente.

Patrones Arquitectónicos Aplicados

• Domain-Driven Design (DDD):
  • Agregados: SolicitudFeedback (englobando Preguntas, Evaluadores Invitados, estado, hashId) y RespuestaFeedback (englobando las respuestas individuales a las preguntas de una solicitud por un evaluador).
  • Servicios de Dominio: Lógica de aprobación/rechazo, generación de código de acceso, validación de plazo, orquestación de notificaciones.
  • Bounded Contexts: Claramente delineados para FeedbackRequest y FeedbackResponse, cada uno con su microservicio.
• API Gateway: Punto único de entrada para el frontend, manejando enrutamiento, autenticación inicial y agregación ligera, si es necesario.
• Microservicios: Descomposición de la aplicación en servicios más pequeños, cohesivos e independientes.
• Arquitectura en Capas (dentro de cada microservicio):
  • Presentación (Controllers): Endpoints REST.
  • Aplicación (Services): Orquestación de los casos de uso.
  • Dominio (Entities, Value Objects, Domain Services): Reglas de negocio y estado.
  • Infraestructura (Repositories, Email Clients): Persistencia, comunicación externa.

Consideraciones de Seguridad

• Protección de Endpoints de Respuesta y Autenticación del Evaluador:
  • Acceso a los formularios de respuesta solo vía enlace con hash único.
  • Autenticación de dos factores implícita para el evaluador (correo + código de acceso enviado al correo).
  • Los códigos de acceso deben ser de un solo uso y tener un tiempo de expiración corto.
• Validación de Datos de Entrada:
  • Validación rigurosa de todos los datos recibidos vía API (ej., formato de correo, número de preguntas/evaluadores, contenido de las respuestas).
  • Impedir correos del dominio @ciandt.com.br para evaluadores externos.
• Autorización en los Flujos de Solicitud y Aprobación:
  • Los colaboradores solo pueden gestionar (crear, editar, eliminar) sus propias solicitudes.
  • Los PDM solo pueden analizar y aprobar/rechazar solicitudes de colaboradores bajo su gestión.
  • Se consultará al UserService para verificar roles y jerarquías.
• Anonimato de la Respuesta: Conforme a lo especificado en las épicas, el sistema debe garantizar que, aunque el colaborador indique los evaluadores, las respuestas individuales no sean directamente atribuibles a un evaluador específico en la vista del colaborador (a menos que el modelo de visualización lo permita). El proceso de respuesta en sí está autenticado para garantizar que solo el evaluador invitado responda.
• Protección contra Abuso: Considerar rate limiting para el envío de códigos de acceso y el envío de formularios para mitigar riesgos de abuso.