Módulos y Dominios - bootcamp-uchile-2026/grupo-2-backend GitHub Wiki

Módulos y Dominios

Esta página documenta la organización del Backend de BuenOrigen mediante dominios y módulos de NestJS.

La organización se explica a partir de las funcionalidades definidas en UX/UI y de la implementación documentada del backend hasta el 13 de octubre de 2026.

Se distinguen los módulos documentados como implementados de los dominios previstos. Una pantalla del sitemap no implica por sí misma un módulo NestJS.

Dominios Identificados

Dominio Módulo NestJS Responsabilidad principal Estado
Productos ProductsModule Gestionar las funcionalidades asociadas al catálogo de productos Implementado
Subcategorías SubcategoriesModule Gestionar subcategorías y consultas de productos asociadas a ellas Implementado
Emprendedores EntrepreneursModule Gestionar la información pública de los emprendedores y sus productos Implementado
Favoritos FavoritesModule Gestionar los productos guardados como favoritos Pendiente
Usuarios UsersModule Gestionar usuarios, perfiles y funcionalidades asociadas a sus cuentas Pendiente
Carrito CartModule Gestionar los productos y cantidades incorporados al carrito Pendiente
Artículos ArticlesModule Gestionar los contenidos publicados en el blog Pendiente
Autenticación y registro Sin módulo definido (dominio conceptual) Identificación, creación de cuentas y mecanismos de acceso Identificado en UX/UI; implementación por comprobar
Direcciones Sin módulo definido (dominio conceptual) Mantener direcciones asociadas a cuentas de compradores Pendiente de definición e implementación
Pedidos y compras Sin módulo definido (dominio conceptual) Registrar y consultar compras, pedidos y su seguimiento Pendiente de definición e implementación
Devoluciones y reembolsos Sin módulo definido (dominio conceptual) Solicitudes y seguimiento de devoluciones o reembolsos Pendiente de definición e implementación
Puntos Verdes Sin módulo definido (dominio conceptual) Consulta y administración de puntos o beneficios verdes Pendiente de definición e implementación
Pagos y métodos de pago Sin módulo definido (dominio conceptual) Métodos y operaciones de pago asociados a compras Pendiente de definición e implementación
Envíos Sin módulo definido (dominio conceptual) Información de despacho y entrega de pedidos Pendiente de definición e implementación
Gestión del emprendedor Sin módulo independiente definido Dashboard, edición de perfil privado, productos y ventas Identificado en UX/UI; alcance por definir
Reseñas, métricas, facturación e inbox Sin módulo independiente definido Funciones complementarias de la cuenta de emprendedor Identificado en antecedentes del sitemap; alcance por definir

La estructura podrá continuar evolucionando a medida que se incorporen nuevas funcionalidades de BuenOrigen.

Productos

Módulo

ProductsModule

Estado

Implementado

Responsabilidades

El módulo concentra las funcionalidades relacionadas con la consulta y representación de productos del catálogo de BuenOrigen.

Actualmente considera:

También proporciona operaciones relacionadas con productos que pueden ser reutilizadas por otros dominios, como la obtención de productos asociados a un emprendedor.

Estructura Actual

ProductsModule
├── ProductsController
└── ProductsService

Los modelos y DTOs asociados se encuentran organizados en src/models/ y src/dto/.

Operaciones principales

ProductsService concentra las consultas del catálogo necesarias para búsqueda, ofertas, productos más vendidos, novedades, detalle, Huella Verde, valoraciones y relacionados. También proporciona consultas reutilizables de productos por emprendedor.

Para los nombres exactos de los métodos, consultar el archivo vigente products.service.ts, ya que la firma de los métodos debe corresponder al código y no a una traducción de la documentación anterior.

Relación con otros módulos

ProductsService es exportado por ProductsModule para permitir su utilización desde otros módulos.

Actualmente:

ProductsModule
       |
       | exports
       v
ProductsService
       |
       | utilizado por
       v
EntrepreneursModule

Esto permite reutilizar la lógica de productos sin duplicar los datos o las operaciones dentro de EntrepreneursService.

Subcategorías

Módulo

SubcategoriesModule

Estado

Implementado

Responsabilidades

El módulo gestiona las funcionalidades relacionadas con las subcategorías del catálogo y la consulta de productos asociados a ellas.

Actualmente considera:

Estructura Actual

SubcategoriesModule
├── SubcategoriesController
└── SubcategoriesService

Operaciones Implementadas

El módulo permite realizar las siguientes operaciones principales:

Obtener las subcategorías asociadas a una categoría

Obtener los productos asociados a una subcategoría

Obtener los productos populares de una subcategoría

Los endpoints asociados se encuentran documentados en Endpoints.

Relación entre Categorías y Subcategorías

Actualmente la consulta de subcategorías pertenecientes a una categoría se gestiona mediante este módulo:

GET /categorias/:categoriaId/subcategorias

Por lo tanto, aunque existe el concepto de Categoria, actualmente no se ha definido un CategoriesModule (hipotético) independiente.

La necesidad de crear un módulo específico para Categorías podrá evaluarse si aparecen nuevas responsabilidades propias de dicho dominio.

Emprendedores

Módulo

EntrepreneursModule

Estado

Implementado

Responsabilidades

El módulo gestiona la información pública de los emprendedores registrados en BuenOrigen.

Actualmente considera:

Estructura Actual

EntrepreneursModule
├── EntrepreneursController
└── EntrepreneursService

Los modelos y DTOs se encuentran organizados en src/models/ y src/dto/. La representación resumida de productos utiliza el contrato ProductSummaryDto, compartido con las consultas del catálogo.

Operaciones principales

El servicio de emprendedores atiende el listado público, el detalle público por identificador y la consulta de productos asociados. La búsqueda de productos se delega al servicio del catálogo para no duplicar datos ni reglas de negocio.

Relación con Productos

Un emprendedor puede poseer múltiples productos.

Conceptualmente:

Emprendedor
     |
     | 1
     |
     | N
     v
Producto

Cada producto incorpora:

entrepreneurId: number;

para identificar al emprendedor al cual pertenece.

Para obtener sus productos, EntrepreneursService utiliza ProductsService.

EntrepreneursController
          |
          v
EntrepreneursService
          |
          v
ProductsService
          |
          v
ProductSummaryDto[]

Favoritos

Módulo conceptual (no confirmado como implementado)

FavoritesModule

Estado

Pendiente de implementación

Responsabilidades

Gestionar la relación entre el usuario y los productos almacenados como favoritos.

Funcionalidad asociada:

Favoritos

Actualmente se han identificado las siguientes operaciones:

  • Consultar favoritos.
  • Agregar un producto a favoritos.
  • Eliminar un producto de favoritos.

Posible organización (referencial)

FavoritesModule
├── FavoritesController
└── FavoritesService

Operaciones identificadas

Las operaciones planteadas en esta sección son requerimientos funcionales, no métodos confirmados del repositorio. Su contrato se definirá al implementarse.

Los contratos preliminares se encuentran documentados en Endpoints y DTOs.

Usuarios

Módulo conceptual (no confirmado como implementado)

UsersModule

Alcance documental

Los módulos y contratos específicos de clientes o usuarios deben comprobarse en la versión vigente de develop, ya que el documento original antecede a cambios de integración de clientes. No se deben inferir endpoints privados de autenticación o perfil a partir del sitemap.

Responsabilidades

Gestionar la información asociada a los usuarios y sus cuentas dentro de BuenOrigen.

Entre las funcionalidades identificadas se encuentran:

A partir del sitemap también se han identificado futuras responsabilidades relacionadas con:

  • Datos de cuenta.
  • Direcciones.
  • Compras.
  • Devoluciones.
  • Puntos Verdes.
  • Roles de usuario.

Posible organización (referencial)

UsersModule
├── UsersController
└── UsersService

Pendiente de definición: determinar qué funcionalidades pertenecerán directamente a UsersModule y cuáles requerirán módulos independientes, por ejemplo Autenticación, Pedidos o Direcciones.

Carrito

Módulo conceptual (no confirmado como implementado)

CartModule

Estado

Pendiente de implementación

Responsabilidades

Gestionar el estado del carrito de compras y los productos incorporados durante el proceso de compra.

Funcionalidad asociada:

Carrito de Compras

Actualmente considera:

  • Consultar el carrito.
  • Agregar productos.
  • Actualizar cantidades.
  • Eliminar productos.

Posible organización (referencial)

CartModule
├── CartController
└── CartService

Operaciones identificadas

Las operaciones planteadas en esta sección son requerimientos funcionales, no métodos confirmados del repositorio. Su contrato se definirá al implementarse.

Los DTO preliminares asociados al carrito se encuentran definidos en DTOs.

Artículos

Módulo conceptual (no confirmado como implementado)

ArticlesModule

Estado

Pendiente de implementación

Responsabilidades

Gestionar los contenidos publicados en el blog de BuenOrigen.

Funcionalidad asociada:

Artículos de nuestro Blog

Actualmente se identifica la consulta pública de artículos. El nombre del método y sus parámetros deberán definirse con la implementación.

Posible organización (referencial)

ArticlesModule
├── ArticlesController
└── ArticlesService

A partir del sitemap podrán incorporarse posteriormente funcionalidades relacionadas con:

  • Noticias.
  • Consejos o Tips.
  • Ideas.
  • Detalle de artículo.

Pendientes funcionales identificados en UX/UI

Además de Favoritos, Carrito y Artículos, los antecedentes compartidos del wireframe y sitemap contemplan funcionalidades de las cuentas de compradores y emprendedores que todavía no están desarrolladas como dominios independientes en esta documentación.

Las siguientes agrupaciones son propuestas de responsabilidad de negocio, no una instrucción de crear un módulo por cada pantalla ni una afirmación de que existan clases o endpoints:

Área UX/UI Funcionalidades identificadas Posible responsabilidad backend Situación documental
Cuenta de usuario Registro de Usuario, Autenticación, Perfil de Usuario Cuentas, identidad, información del perfil y permisos Revisar el soporte vigente de clientes; autenticación no confirmada
Cuenta de usuario Direcciones Dirección de contacto, despacho y asociación con cuenta Pendiente
Cuenta de usuario Mis Compras Historial y detalle de pedidos o compras Pendiente
Cuenta de usuario Devoluciones Solicitudes de devolución y seguimiento Pendiente
Cuenta de usuario Puntos Verdes Saldo, movimientos o beneficios, según definición de producto Pendiente de reglas de negocio
Compra Métodos de pago y pagos Registro de información necesaria para el pago, según definición posterior Pendiente de reglas y contratos
Compra Envíos Datos de entrega y seguimiento, si el flujo de compra lo requiere Pendiente de definición
Cuenta de emprendedor Dashboard del Emprendedor Resúmenes e indicadores privados Pendiente
Cuenta de emprendedor Perfil del Emprendedor Consulta y edición de información privada del emprendimiento Pendiente
Cuenta de emprendedor Mis Productos Gestión de catálogo propio por emprendedor Pendiente
Cuenta de emprendedor Mis Ventas Consulta y administración de ventas Pendiente
Cuenta de emprendedor Métricas, reseñas, facturación, devoluciones/reembolsos e inbox Funciones administrativas identificadas en antecedentes del sitemap Pendiente de definición
Contenido Artículos de nuestro Blog Consulta y publicación de contenido editorial Pendiente

Criterios para convertir estos pendientes en módulos

  1. Revisar si las operaciones ya están cubiertas por un módulo existente, especialmente clientes/usuarios, productos y emprendedores.
  2. Definir reglas de negocio, propiedad de los datos y operaciones antes de crear controllers, services o DTOs.
  3. Evitar replicar un módulo por cada componente visual del wireframe.
  4. Registrar cualquier desarrollo nuevo en el backlog y comprobar que no exista un issue equivalente.
  5. Incorporar a Endpoints y DTOs solamente los contratos efectivamente definidos, distinguiendo propuestas de implementaciones.

Relación conceptual entre áreas

flowchart TD
    UX["Wireframes y sitemap UX/UI"] --> PUBLIC["Catálogo público"]
    UX --> BUYER["Cuenta de comprador"]
    UX --> SELLER["Cuenta de emprendedor"]
    PUBLIC --> PROD["ProductsModule"]
    PUBLIC --> SUB["SubcategoriesModule"]
    PUBLIC --> ENT["EntrepreneursModule"]
    BUYER -. "Por definir" .-> ACCOUNT["Cuentas, carrito, favoritos, pedidos, pagos y devoluciones"]
    SELLER -. "Por definir" .-> ADMIN["Perfil privado, productos, ventas y dashboard"]

La representación es conceptual: los nodos de áreas pendientes no equivalen a módulos implementados.

Organización General Actual

Los módulos de catálogo que se documentan en esta página son:

AppModule
│
├── ProductsModule
├── SubcategoriesModule
└── EntrepreneursModule

Los demás dominios se incorporan según las decisiones del equipo y las necesidades de la API. Esta enumeración no reemplaza la revisión de AppModule, particularmente para componentes de clientes o usuarios incorporados en otros cambios.

Conceptualmente, la arquitectura proyectada podrá evolucionar hacia:

AppModule
│
├── ProductsModule                  
├── SubcategoriesModule              
├── EntrepreneursModule              
├── FavoritesModule                  
├── UsersModule                   
├── CartModule                    
└── ArticlesModule

Organización de Modelos y DTOs

Como resultado de la normalización del código, los modelos y DTOs utilizan nombres en inglés y se organizan en directorios independientes.

src/
├── models/
│   ├── product.model.ts
│   ├── entrepreneur.model.ts
│   └── ...
├── dto/
│   ├── product-summary.dto.ts
│   ├── product-search.dto.ts
│   ├── product-detail.dto.ts
│   └── ...
├── productos/
├── subcategorias/
├── emprendedores/
├── common/
├── app.module.ts
└── main.ts

La estructura es ilustrativa, no un inventario exhaustivo de archivos. Para conocer las clases, propiedades y contratos precisos, consultar el código integrado en develop y la página DTOs.

Las rutas HTTP pueden conservar su nomenclatura en español aun cuando las clases, DTOs y propiedades internas se encuentren nombrados en inglés.

Relación entre Funcionalidades y Módulos

Funcionalidad Dominio / Módulo Estado
Búsqueda de Productos ProductsModule Implementado
Carrusel de Ofertas ProductsModule Implementado
Productos más Populares ProductsModule Implementado
Novedades o Nuevos Productos ProductsModule Implementado
Detalle de Producto ProductsModule Implementado
Huella Verde del Producto ProductsModule Implementado
Valoraciones de Producto ProductsModule Implementado
Productos Relacionados ProductsModule Implementado
Subcategorías Existentes SubcategoriesModule Implementado
Productos por Subcategoría SubcategoriesModule Implementado
Productos más Populares por Subcategoría SubcategoriesModule Implementado
Nuestros Emprendedores EntrepreneursModule Implementado
Perfil de Emprendedor EntrepreneursModule Implementado
Productos del Emprendedor EntrepreneursModule / ProductsModule Implementado
Favoritos FavoritesModule Pendiente
Perfil de Usuario Usuarios / clientes: verificar contrato vigente Por comprobar
Autenticación Identificación / autorización Sin contrato confirmado
Carrito de Compras CartModule Pendiente
Artículos de nuestro Blog ArticlesModule Pendiente
Registro de Usuario Cuentas / autenticación por definir Por comprobar
Direcciones Direcciones / cuenta de usuario Pendiente
Mis Compras Pedidos / compras Pendiente
Devoluciones Devoluciones / pedidos Pendiente
Puntos Verdes Beneficios / cuenta de usuario Pendiente
Dashboard del Emprendedor Administración del emprendedor Pendiente
Perfil del Emprendedor Administración del emprendedor Pendiente
Mis Productos Productos / emprendedores Pendiente
Mis Ventas Ventas / pedidos Pendiente

Relación entre Módulos

Los módulos pueden utilizar servicios proporcionados por otros módulos cuando una funcionalidad cruza responsabilidades de dominio.

La relación documentada para la consulta de productos de un emprendedor es:

EntrepreneursModule
        |
        | imports
        v
ProductsModule
        |
        | exports
        v
ProductsService

Esto permite que:

GET /emprendedores/:emprendedorId/productos

pueda ser recibido por EntrepreneursController, mientras que la lógica de búsqueda de productos permanece dentro de ProductsService.

De esta forma se evita duplicar responsabilidades entre servicios.

Crear un Módulo

Que una funcionalidad aparezca en el sitemap o en Frontend no implica automáticamente que deba existir un módulo Backend independiente.

La creación de un módulo deberá evaluarse principalmente según:

  • Responsabilidad de negocio propia.
  • Datos o modelos que administra.
  • Reglas de negocio específicas.
  • Operaciones que expone.
  • Necesidad de encapsular servicios relacionados.

Por ejemplo:

Productos
    |
    v
Muchas operaciones y reglas propias
    |
    v
ProductsModule

Mientras que una sección exclusivamente visual de Frontend podría no requerir un módulo Backend específico.

Referencias de documentación

La descripción de arquitectura corresponde a los antecedentes disponibles hasta el 13 de octubre de 2026. Los nombres y contratos específicos que no se han contrastado directamente con los archivos más recientes se presentan como referencias conceptuales, no como garantías de implementación.

Componentes transversales

Además de los módulos de negocio, el backend incorpora componentes compartidos para el tratamiento de solicitudes HTTP. La trazabilidad mediante middleware, la gestión de excepciones y la validación de contratos REST forman parte del trabajo integrado hasta el 13 de octubre de 2026.

Estos componentes no deben representarse como dominios comerciales independientes; se documentan de forma transversal en Componentes Transversales.