Búsqueda de Productos - bootcamp-uchile-2026/grupo-2-backend GitHub Wiki
Búsqueda de Productos
La funcionalidad Búsqueda de Productos permite que los usuarios encuentren productos del catálogo de BuenOrigen utilizando un término de búsqueda.
Esta funcionalidad puede utilizarse desde el Header y desde otras secciones de la aplicación que necesiten consultar el catálogo.
Desde la perspectiva Backend, consiste en recibir un término mediante un Query Parameter, buscar coincidencias dentro del catálogo y devolver los productos encontrados.
Objetivo
Permitir que Frontend y Mobile consulten productos del catálogo utilizando un texto ingresado por el usuario.
Estado
Implementado
La funcionalidad se encuentra implementada actualmente en:
ProductosModule
|
v
ProductosController
|
v
ProductosService
Responsabilidad Backend
Actualmente el Backend debe:
- Recibir el término de búsqueda mediante el Query Parameter
buscar. - Verificar que el término exista.
- Verificar que el término no corresponda únicamente a espacios en blanco.
- Consultar los productos disponibles.
- Comparar el término con el nombre de cada producto.
- Permitir coincidencias parciales.
- Realizar la comparación sin distinguir entre mayúsculas y minúsculas.
- Transformar los productos encontrados a
ProductoBusquedaDto. - Retornar una lista vacía cuando no existan coincidencias.
Contrato de API
Endpoint
GET /productos
Query Parameter
buscar
El parámetro es obligatorio.
Ejemplo:
GET /productos?buscar=bolsa
DTO de salida
ProductoBusquedaDto[]
Página relacionada:
La definición general de la operación también se encuentra centralizada en:
Flujo de la Operación
Conceptualmente:
GET /productos?buscar=bolsa
|
v
ProductosController
|
| validar buscar
v
ProductosService
|
| filter()
v
Buscar por nombre
|
| map()
v
ProductoBusquedaDto[]
|
v
200 OK
Validación del Término de Búsqueda
El Query Parameter:
buscar
es obligatorio.
El Controller verifica actualmente:
if (!buscar || buscar.trim() === '') {
throw new BadRequestException(
'El término de búsqueda es obligatorio',
);
}
Por lo tanto, solicitudes como:
GET /productos
o:
GET /productos?buscar=
no son consideradas búsquedas válidas.
El Backend responde:
400 Bad Request
con el mensaje:
El término de búsqueda es obligatorio
Criterio de Búsqueda Actual
Actualmente la búsqueda se realiza utilizando:
nombre del producto
El Service compara el nombre de cada producto con el término recibido.
Conceptualmente:
producto.nombre
.toLowerCase()
.includes(buscar.toLowerCase())
Esto produce dos comportamientos importantes.
No distingue mayúsculas y minúsculas
Por ejemplo:
buscar = "bolsa"
puede encontrar:
Bolsa Reutilizable de Algodón
porque ambos textos son convertidos temporalmente a minúsculas antes de compararse.
Ejemplos equivalentes:
bolsa
Bolsa
BOLSA
BoLsA
Permite coincidencias parciales
La búsqueda utiliza:
includes()
por lo tanto no es necesario escribir el nombre completo del producto.
Por ejemplo:
GET /productos?buscar=algodón
podría encontrar:
Bolsa Reutilizable de Algodón
si el término está contenido dentro del nombre.
Campos Considerados Actualmente
Actualmente la búsqueda considera únicamente:
Producto.nombre
No se utilizan todavía como criterios de búsqueda:
marca
descripcion
categoria
subcategoria
palabras clave
Por ejemplo, si existe:
Marca: EcoRaíz
Nombre: Bolsa Reutilizable de Algodón
la búsqueda:
GET /productos?buscar=EcoRaíz
no necesariamente encontrará el producto, porque actualmente el Service compara el término únicamente contra:
nombre
Tratamiento de Tildes
Actualmente la implementación convierte los textos a minúsculas, pero no realiza una normalización especial de tildes.
Por lo tanto:
algodon
y:
algodón
no deben considerarse automáticamente equivalentes.
La normalización de caracteres podrá incorporarse posteriormente si los requerimientos de búsqueda lo necesitan.
Procesamiento en ProductosService
La lógica principal se encuentra en:
buscarProductos(buscar: string): ProductoBusquedaDto[]
El proceso puede representarse como:
this.productos
|
| filter()
v
Coincidencias por nombre
|
| map()
v
ProductoBusquedaDto[]
Primero se seleccionan los productos coincidentes.
Luego se transforman los productos encontrados al contrato de salida.
DTO de Salida
La operación utiliza:
ProductoBusquedaDto
con la siguiente estructura:
export class ProductoBusquedaDto {
id: number;
marca: string;
nombre: string;
precio: number;
imagenUrl: string;
}
La búsqueda no devuelve directamente el modelo completo Producto.
Conceptualmente:
Producto
|
| seleccionar campos necesarios
v
ProductoBusquedaDto
|
v
Frontend / Mobile
Esto permite entregar únicamente la información necesaria para representar los resultados de búsqueda.
Ejemplo de Solicitud
GET /productos?buscar=bolsa
Ejemplo de Respuesta
[
{
"id": 1,
"marca": "EcoRaíz",
"nombre": "Bolsa Reutilizable de Algodón",
"precio": 5990,
"imagenUrl": "https://ejemplo.cl/imagenes/bolsa-algodon.jpg"
}
]
Respuesta HTTP:
200 OK
Resultado sin Coincidencias
Si el término es válido pero ningún producto contiene dicho texto dentro de su nombre, la operación retorna:
[]
Esto no corresponde a un error.
Conceptualmente:
GET /productos?buscar=termino
|
v
¿Término válido?
|
+-----+-----+
| |
No Sí
| |
v v
400 Bad Buscar productos
Request |
v
¿Hay coincidencias?
|
+-----+-----+
| |
Sí No
| |
v v
ProductoBusquedaDto[] []
|
v
200 OK
Respuestas HTTP
| Código | Situación |
|---|---|
200 OK |
La búsqueda fue procesada correctamente |
200 OK con [] |
El término es válido, pero no existen coincidencias |
400 Bad Request |
El parámetro buscar no fue enviado o está vacío |
Documentación Swagger
La operación se encuentra documentada utilizando decoradores de @nestjs/swagger.
Entre ellos:
@ApiOperation()
@ApiQuery()
@ApiOkResponse()
@ApiBadRequestResponse()
El Query Parameter se documenta como:
buscar
de tipo:
string
y obligatorio.
La respuesta exitosa se documenta mediante:
ProductoBusquedaDto[]
Para mayor información consultar:
Posibles Mejoras Futuras
La implementación actual cubre una búsqueda simple por nombre.
Posteriormente podrán evaluarse mejoras como:
- Buscar también por marca.
- Buscar por descripción.
- Buscar por categoría.
- Buscar por subcategoría.
- Incorporar palabras clave.
- Ignorar tildes.
- Normalizar caracteres.
- Incorporar filtros adicionales.
- Incorporar ordenamiento.
- Incorporar paginación.
Estas mejoras deberán implementarse únicamente cuando sean requeridas por las reglas funcionales de BuenOrigen.
Relación con la Arquitectura
La funcionalidad pertenece al dominio:
Productos
y actualmente utiliza:
ProductosModule
|
v
ProductosController
|
v
ProductosService
|
v
ProductoBusquedaDto[]
Las páginas relacionadas son: