Componentes Transversales - bootcamp-uchile-2026/grupo-2-backend GitHub Wiki

Componentes Transversales

Esta página reúne los mecanismos comunes del BuenOrigen Backend, desarrollados con NestJS y TypeScript. Complementa los documentos Módulos y Dominios, Endpoints, DTOs y OpenAPI y Swagger.

Propósito

Los componentes transversales concentran responsabilidades comunes a múltiples rutas: registrar solicitudes, validar datos, gestionar errores y mantener contratos HTTP consistentes. No corresponden a pantallas independientes del wireframe de UX/UI.

Middleware y trazabilidad HTTP

En las integraciones documentadas hasta el 13 de octubre se incorporó registro transversal de solicitudes HTTP mediante middleware. El archivo referido por el historial es src/common/middleware/request-tracing.middleware.ts.

La implementación contempla trazabilidad de solicitudes, con un identificador x-request-id y registro de información útil para el diagnóstico. También se realizaron cambios para registrar de forma segura la estructura del cuerpo HTTP, sin asumir que sea adecuado registrar sus valores o datos sensibles.

La información exacta emitida en cada registro, el tratamiento de cabeceras y la estrategia de ocultación deben verificarse en el archivo vigente antes de documentar ejemplos de logs.

Pipes y validación de solicitudes

Los pipes de NestJS permiten transformar y validar valores durante el procesamiento de solicitudes. Los DTOs y validadores establecen restricciones específicas de cada contrato; las declaraciones Swagger no reemplazan las validaciones.

Las modificaciones recientes de contratos REST incluyeron correcciones de validación de entradas. Para las restricciones exactas de cantidad, identificadores y demás parámetros debe consultarse Endpoints y el controller correspondiente; no se deducen de ejemplos generales.

Exception filters

Los filtros de excepciones permiten convertir errores de aplicación en respuestas HTTP coherentes. El backend dispone de trabajo integrado de manejo de excepciones; el código concreto define el formato y los campos efectivamente enviados al cliente.

No se debe documentar una estructura JSON uniforme que no esté respaldada por la implementación actual.

Guards y control de acceso

Los guards pueden controlar si una operación está autorizada, pero su presencia en el framework no implica que todas las rutas tengan autenticación. La autenticación de compradores o emprendedores identificada en UX/UI debe diferenciarse de lo que ya está implementado.

Orden conceptual de una solicitud

flowchart TD
    A[Cliente HTTP] --> B[Middleware]
    B --> C[Guards, cuando existan]
    C --> D[Pipes y validaciones]
    D --> E[Controller]
    E --> F[Service]
    F --> G[Respuesta HTTP]
    C -. Excepción .-> H[Exception filter]
    D -. Excepción .-> H
    E -. Excepción .-> H
    F -. Excepción .-> H
    H --> G

El flujo es conceptual; interceptores y otros mecanismos del ciclo NestJS pueden intervenir cuando se configuran.

Buenas prácticas de documentación

  • Describir únicamente componentes presentes en el código vigente.
  • Referenciar rutas y contratos sin cambiar su nomenclatura pública.
  • Mantener los nombres de clases, métodos, DTOs y modelos en inglés.
  • No registrar contraseñas, tokens ni datos sensibles en ejemplos de trazabilidad.
  • Mantener sincronizadas las modificaciones transversales con Endpoints y OpenAPI y Swagger.

Referencias