Nuestros Emprendedores - bootcamp-uchile-2026/grupo-2-backend GitHub Wiki

Nuestros Emprendedores

La funcionalidad Nuestros Emprendedores permite presentar información pública y resumida de los emprendedores disponibles en BuenOrigen.

Esta funcionalidad puede utilizarse tanto para representar una selección de emprendedores en la página de inicio como para obtener el listado general de emprendimientos.

Desde la perspectiva Backend, consiste en consultar los emprendedores disponibles, seleccionar únicamente la información pública necesaria y devolverla mediante EmprendedorResumenDto.

La construcción visual de tarjetas, carruseles o listados corresponde a Frontend y Mobile.

Objetivo

Proporcionar a Frontend y Mobile información pública resumida de los emprendedores disponibles en BuenOrigen.

La operación permite:

  • Obtener todos los emprendedores disponibles.
  • Limitar opcionalmente la cantidad de resultados.
  • Entregar únicamente información pública.
  • Utilizar los resultados tanto en la página de inicio como en un directorio de emprendedores.

Estado

Implementado

La funcionalidad se encuentra implementada mediante:

EmprendedoresModule
        |
        v
EmprendedoresController
        |
        v
EmprendedoresService
        |
        v
EmprendedorResumenDto[]

Responsabilidad Backend

Actualmente el Backend debe:

  • Consultar los emprendedores disponibles.
  • Recibir opcionalmente el Query Parameter cantidad.
  • Limitar los resultados cuando cantidad sea enviado.
  • Mantener el orden actual de los emprendedores.
  • Seleccionar únicamente los campos públicos necesarios.
  • Transformar los resultados a EmprendedorResumenDto.
  • Devolver una lista de emprendedores.

Contrato de API

Endpoint

GET /emprendedores

Query Parameter

cantidad

El parámetro es:

opcional

Por ejemplo:

GET /emprendedores

devuelve todos los emprendedores disponibles.

Mientras que:

GET /emprendedores?cantidad=4

limita la respuesta a los primeros cuatro emprendedores disponibles.

DTO de salida

EmprendedorResumenDto[]

Página relacionada:

Nuestros Emprendedores

La definición general del endpoint se encuentra centralizada en:

Endpoints

La estructura del DTO se encuentra documentada en:

DTOs

Funcionamiento sin cantidad

Cuando el cliente realiza:

GET /emprendedores

sin enviar el Query Parameter cantidad, el Backend utiliza todos los emprendedores disponibles.

Conceptualmente:

GET /emprendedores
        |
        v
¿Existe cantidad?
        |
       No
        |
        v
Todos los emprendedores
        |
        v
EmprendedorResumenDto[]

Funcionamiento con cantidad

Cuando Frontend o Mobile envían:

GET /emprendedores?cantidad=2

el Backend limita la colección utilizando:

slice(0, cantidadNumero)

Conceptualmente:

Emprendedores
     |
     | cantidad = 2
     v
slice(0, 2)
     |
     v
Primeros 2 emprendedores

Conversión del Query Parameter

Los Query Parameters recibidos mediante HTTP llegan originalmente como texto.

Por ejemplo:

GET /emprendedores?cantidad=4

el valor recibido inicialmente corresponde conceptualmente a:

"4"

Actualmente el Service realiza la conversión mediante:

Number(cantidad)

Conceptualmente:

HTTP
"4"
 |
 v
Number()
 |
 v
4
 |
 v
slice(0, 4)

Implementación Actual de cantidad

La lógica utilizada actualmente corresponde conceptualmente a:

let emprendedoresSeleccionados = this.emprendedores;

if (cantidad !== undefined) {
  const cantidadNumero = Number(cantidad);

  emprendedoresSeleccionados =
    this.emprendedores.slice(0, cantidadNumero);
}

Por lo tanto:

cantidad no enviada
        |
        v
Todos los emprendedores


cantidad enviada
        |
        v
Number(cantidad)
        |
        v
slice(0, cantidadNumero)

Validación Actual de cantidad

Actualmente cantidad se convierte mediante:

Number()

pero no existe todavía una validación específica que compruebe que:

cantidad sea un número entero
cantidad sea mayor que 0
cantidad tenga un máximo permitido

Por ejemplo, actualmente no se utiliza:

ParseIntPipe

en este endpoint.

Esta validación podrá mejorarse posteriormente para mantener un comportamiento más controlado ante valores incorrectos.

Una posible evolución sería:

Query Parameter
      |
      v
ParseIntPipe
      |
      v
Validar valor positivo
      |
      v
Service

Criterio de Selección Actual

Actualmente no existe una regla de negocio adicional para seleccionar emprendedores destacados.

No se utilizan todavía propiedades como:

destacado
habilitado
actividadReciente
cantidadVentas
puntuacion

El comportamiento actual consiste simplemente en utilizar los emprendedores disponibles en la colección.

Conceptualmente:

Emprendedores disponibles
          |
          v
Limitar por cantidad
si fue solicitada
          |
          v
EmprendedorResumenDto[]

Orden de los Emprendedores

Actualmente no existe un:

sort()

para esta funcionalidad.

Por lo tanto, los emprendedores mantienen el orden en el que están almacenados actualmente.

Por ejemplo:

1. EcoRaíz
2. Verde Hogar
3. Naturaleza Viva

Si se solicita:

GET /emprendedores?cantidad=2

la respuesta corresponderá a:

1. EcoRaíz
2. Verde Hogar

Información Pública

El modelo Emprendedor contiene actualmente:

id: number;
nombre: string;
descripcion: string;
imagenUrl: string;
historia: string;

Sin embargo, para el listado resumido no es necesario entregar todos estos datos.

La operación utiliza:

EmprendedorResumenDto

que contiene:

export class EmprendedorResumenDto {
  id: number;
  nombre: string;
  descripcion: string;
  imagenUrl: string;
}

La propiedad:

historia

no se incluye en esta respuesta resumida.

Modelo vs DTO

Conceptualmente:

Emprendedor
     |
     | id
     | nombre
     | descripcion
     | imagenUrl
     | historia
     |
     v
Seleccionar información pública resumida
     |
     v
EmprendedorResumenDto
     |
     | id
     | nombre
     | descripcion
     | imagenUrl
     |
     v
Frontend / Mobile

La información detallada del emprendedor se obtiene mediante otra funcionalidad:

Perfil de Emprendedor

Flujo de la Operación

GET /emprendedores?cantidad=4
             |
             v
  EmprendedoresController
             |
             v
   EmprendedoresService
             |
             v
¿Se recibió cantidad?
       |
   +---+---+
   |       |
  Sí       No
   |       |
   v       v
Number()  Todos
   |
   v
slice()
   |
   +-------+
       |
       v
      map()
       |
       v
EmprendedorResumenDto[]
       |
       v
     200 OK

Transformación al DTO

Después de seleccionar los emprendedores, el Service transforma cada elemento mediante map().

Conceptualmente:

Emprendedor[]
      |
      | map()
      v
EmprendedorResumenDto[]

Para cada emprendedor se seleccionan:

id
nombre
descripcion
imagenUrl

y se omite:

historia

porque corresponde a información utilizada en el perfil detallado.

Ejemplo de Solicitud sin Límite

GET /emprendedores

Ejemplo de Respuesta

[
  {
    "id": 1,
    "nombre": "EcoRaíz",
    "descripcion": "Emprendimiento dedicado a la elaboración de productos sustentables.",
    "imagenUrl": "https://ejemplo.cl/imagenes/emprendedores/ecoraiz.jpg"
  },
  {
    "id": 2,
    "nombre": "Verde Hogar",
    "descripcion": "Emprendimiento enfocado en productos ecológicos para el hogar.",
    "imagenUrl": "https://ejemplo.cl/imagenes/emprendedores/verde-hogar.jpg"
  },
  {
    "id": 3,
    "nombre": "Naturaleza Viva",
    "descripcion": "Emprendimiento dedicado al bienestar y cuidado personal sustentable.",
    "imagenUrl": "https://ejemplo.cl/imagenes/emprendedores/naturaleza-viva.jpg"
  }
]

Respuesta HTTP:

200 OK

Ejemplo Utilizado por la Página de Inicio

La página de inicio podría solicitar:

GET /emprendedores?cantidad=2

y recibir:

[
  {
    "id": 1,
    "nombre": "EcoRaíz",
    "descripcion": "Emprendimiento dedicado a la elaboración de productos sustentables.",
    "imagenUrl": "https://ejemplo.cl/imagenes/emprendedores/ecoraiz.jpg"
  },
  {
    "id": 2,
    "nombre": "Verde Hogar",
    "descripcion": "Emprendimiento enfocado en productos ecológicos para el hogar.",
    "imagenUrl": "https://ejemplo.cl/imagenes/emprendedores/verde-hogar.jpg"
  }
]

Resultado sin Emprendedores

Si no existen emprendedores disponibles, el Backend devuelve:

[]

con:

200 OK

Esto corresponde a una respuesta válida y no a un error.

Diferencia entre Listado y Perfil

Existen dos operaciones distintas dentro del dominio Emprendedores.

Listado

GET /emprendedores

devuelve:

EmprendedorResumenDto[]

y está pensado para representar múltiples emprendedores.

Perfil

GET /emprendedores/:emprendedorId

devuelve:

EmprendedorDetalleDto

y proporciona información pública más detallada de un emprendedor específico.

Conceptualmente:

GET /emprendedores
        |
        v
Listado
        |
        v
EmprendedorResumenDto[]


GET /emprendedores/1
        |
        v
Perfil público
        |
        v
EmprendedorDetalleDto

Uso en Distintas Secciones

El mismo endpoint puede ser reutilizado en distintas partes de la aplicación.

Por ejemplo:

Página de Inicio
      |
      | cantidad limitada
      v
GET /emprendedores?cantidad=4

Mientras que un directorio completo podría utilizar:

Directorio de Emprendedores
      |
      v
GET /emprendedores

Esto evita crear endpoints distintos únicamente porque Frontend presenta los mismos datos en componentes diferentes.

Documentación Swagger

La operación se encuentra documentada mediante decoradores de @nestjs/swagger.

Entre ellos:

@ApiTags()
@ApiOperation()
@ApiQuery()
@ApiOkResponse()

El parámetro:

cantidad

se documenta como opcional.

La respuesta exitosa corresponde a:

EmprendedorResumenDto[]

Para mayor información consultar:

OpenAPI y Swagger

Reglas de Negocio Actuales

Actualmente pueden resumirse como:

1. Obtener emprendedores disponibles.

2. Si existe cantidad:
      convertir mediante Number()
      limitar mediante slice().

3. Si no existe cantidad:
      utilizar todos.

4. Transformar los resultados a
   EmprendedorResumenDto[].

Actualmente no se aplican:

filtros por estado
ordenamiento especial
selección de destacados
priorización por ventas
selección aleatoria

Posibles Mejoras Futuras

Posteriormente podrán evaluarse reglas como:

  • Validar cantidad mediante un Pipe.
  • Exigir que cantidad sea mayor que cero.
  • Definir una cantidad máxima.
  • Incorporar emprendedores destacados.
  • Incorporar estado público o habilitado.
  • Ordenar según ventas.
  • Ordenar según puntuación.
  • Incorporar selección manual.
  • Incorporar paginación.
  • Incorporar filtros o búsqueda.

Estas mejoras deberán implementarse únicamente cuando sean requeridas por las reglas de negocio de BuenOrigen.

Relación con la Página de Inicio

Página de Inicio
      |
      v
Nuestros Emprendedores
      |
      v
GET /emprendedores?cantidad=...
      |
      v
EmprendedoresController
      |
      v
EmprendedoresService
      |
      v
EmprendedorResumenDto[]
      |
      v
Frontend / Mobile

Relación con la Arquitectura

La funcionalidad pertenece al dominio:

Emprendedores

y utiliza:

EmprendedoresModule
        |
        v
EmprendedoresController
        |
        v
EmprendedoresService
        |
        v
EmprendedorResumenDto[]

Páginas relacionadas: