Huella Verde del Producto - bootcamp-uchile-2026/grupo-2-backend GitHub Wiki

Huella Verde del Producto

La funcionalidad Huella Verde del Producto permite mostrar información asociada al carácter sustentable de un producto disponible en BuenOrigen.

Esta información puede ser presentada dentro del detalle del producto y permite que Frontend y Mobile comuniquen al usuario aspectos relacionados con los materiales, la elaboración y la evaluación sustentable del producto.

Desde la perspectiva Backend, esta funcionalidad consiste en recibir el identificador de un producto, verificar que exista y devolver la información de Huella Verde asociada.

Objetivo

Proporcionar a Frontend y Mobile información resumida sobre las características sustentables de un producto determinado.

Estado

Implementado

La funcionalidad se encuentra implementada mediante:

ProductosModule
      |
      v
ProductosController
      |
      v
ProductosService
      |
      v
HuellaVerdeProductoDto

Responsabilidad Backend

Actualmente el Backend debe:

  • Recibir el identificador del producto.
  • Transformar productoId a un número entero.
  • Verificar que el producto exista.
  • Consultar la información de Huella Verde asociada al producto.
  • Entregar información relacionada con los materiales utilizados.
  • Entregar información relacionada con la elaboración.
  • Entregar la calificación sustentable cuando exista.
  • Transformar la información a HuellaVerdeProductoDto.
  • Manejar el caso en que el producto exista pero todavía no posea información de Huella Verde.
  • Responder 404 Not Found cuando el producto no exista.

Contrato de API

Endpoint

GET /productos/:productoId/huella-verde

Ejemplo:

GET /productos/1/huella-verde

Parámetro de Ruta

productoId

Tipo esperado:

number

DTO de salida

HuellaVerdeProductoDto

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

Endpoints

La estructura completa del DTO se encuentra documentada en:

DTOs

Parámetro productoId

El Controller recibe el identificador mediante:

@Param('productoId', ParseIntPipe) productoId: number

Los parámetros incluidos en una URL llegan inicialmente como texto.

Por ejemplo:

GET /productos/1/huella-verde

entrega inicialmente:

"1"

ParseIntPipe transforma ese valor en:

1

antes de entregarlo al método del Controller.

Conceptualmente:

HTTP
"1"
 |
 v
ParseIntPipe
 |
 v
1
 |
 v
ProductosController

Validación mediante ParseIntPipe

Si el identificador posee un formato válido:

GET /productos/1/huella-verde

el parámetro puede transformarse correctamente a:

1

Sin embargo, una solicitud como:

GET /productos/abc/huella-verde

no contiene un identificador entero válido.

En ese caso, NestJS responde:

400 Bad Request

antes de ejecutar la lógica de ProductosService.

Conceptualmente:

productoId
    |
    v
ParseIntPipe
    |
 +--+--+
 |     |
Sí     No
 |     |
 v     v
number 400 Bad Request
 |
 v
ProductosService

Verificación del Producto

Una vez recibido un identificador válido, el Service verifica que el producto exista.

Conceptualmente:

Producto[]
    |
    | find()
    v
producto.id === productoId
    |
 +--+--+
 |     |
Sí     No
 |     |
 v     v
Producto  undefined

Si el producto no existe, el Backend genera:

NotFoundException

y responde:

404 Not Found

Información de Huella Verde

La información inicial de Huella Verde está compuesta por:

Huella Verde
    |
    +---- Calificación sustentable
    |
    +---- Materiales
    |
    +---- Elaboración

Estos datos se encuentran representados mediante:

HuellaVerdeProductoDto

HuellaVerdeProductoDto

La estructura utilizada corresponde a:

export class HuellaVerdeProductoDto {
  calificacionSustentable: number | null;
  materiales: string[];
  elaboracion: string | null;
}

Por lo tanto, la respuesta contiene:

Campo Tipo Descripción
calificacionSustentable number | null Evaluación sustentable del producto
materiales string[] Materiales utilizados
elaboracion string | null Descripción resumida de su elaboración

Modelo Backend

La información de Huella Verde se mantiene separada del modelo principal Producto.

Conceptualmente:

Producto
   |
   | id
   |
   v
HuellaVerde
   |
   +---- productoId
   +---- calificacionSustentable
   +---- materiales
   +---- elaboracion

La relación se establece mediante:

productoId: number;

Una representación conceptual es:

export class HuellaVerde {
  productoId: number;
  calificacionSustentable: number | null;
  materiales: string[];
  elaboracion: string | null;
}

Relación entre Producto y Huella Verde

Conceptualmente:

Producto
    |
    | id
    v
HuellaVerde
    |
    | productoId
    v
Información sustentable

Por ejemplo:

{
  productoId: 1,
  calificacionSustentable: 4.8,
  materiales: [
    'Algodón orgánico',
    'Tintes naturales',
  ],
  elaboracion:
    'Producto confeccionado utilizando procesos de bajo impacto ambiental.',
}

indica que esta información corresponde al:

Producto 1

Búsqueda de Huella Verde

Después de verificar que el producto exista, el Service busca la información asociada mediante:

productoId

Conceptualmente:

HuellaVerde[]
      |
      | find()
      v
huella.productoId === productoId
      |
 +----+----+
 |         |
Existe   No existe
 |         |
 v         v
Datos    Valores
reales   vacíos

Producto con Información de Huella Verde

Si existe información asociada al producto, el Backend construye:

HuellaVerdeProductoDto

con los valores disponibles.

Ejemplo:

{
  "calificacionSustentable": 4.8,
  "materiales": [
    "Algodón orgánico",
    "Tintes naturales"
  ],
  "elaboracion": "Producto confeccionado utilizando algodón orgánico y procesos de bajo impacto ambiental."
}

Respuesta HTTP:

200 OK

Producto sin Información de Huella Verde

La ausencia de Huella Verde no significa que el producto no exista.

Si el producto existe pero todavía no posee información asociada, el Backend puede devolver:

{
  "calificacionSustentable": null,
  "materiales": [],
  "elaboracion": null
}

con:

200 OK

Conceptualmente:

Producto existe
       |
       v
Buscar Huella Verde
       |
       v
No existe información
       |
       v
{
  calificacionSustentable: null,
  materiales: [],
  elaboracion: null
}
       |
       v
200 OK

Este comportamiento permite distinguir entre:

Producto inexistente
        |
        v
404 Not Found

y:

Producto existente
sin Huella Verde
        |
        v
200 OK
con datos vacíos

Calificación Sustentable

La propiedad:

calificacionSustentable: number | null;

representa una evaluación resumida de sustentabilidad.

Actualmente se utiliza conceptualmente una escala:

1 a 5

donde valores mayores representan una mejor evaluación sustentable.

Por ejemplo:

4.8

Si todavía no existe una evaluación:

{
  "calificacionSustentable": null
}

Método de Cálculo

Actualmente el Backend no calcula dinámicamente la calificación sustentable.

La información se encuentra almacenada directamente como parte de los datos de Huella Verde.

Por lo tanto:

calificacionSustentable
        |
        v
Dato almacenado

y no:

materiales
+
proceso
+
emisiones
+
otros factores
        |
        v
algoritmo automático
        |
        v
calificación

El mecanismo definitivo para calcular o asignar esta calificación permanece pendiente de definición.

Materiales

La propiedad:

materiales: string[];

contiene los principales materiales utilizados en el producto.

Ejemplo:

[
  "Algodón orgánico",
  "Tintes naturales"
]

Si todavía no existe información:

[]

continúa siendo un valor válido.

Elaboración

La propiedad:

elaboracion: string | null;

permite entregar una descripción resumida del proceso de elaboración.

Ejemplo:

Producto confeccionado utilizando algodón orgánico y procesos de bajo impacto ambiental.

Si todavía no existe información:

{
  "elaboracion": null
}

Flujo Completo de la Operación

GET /productos/1/huella-verde
             |
             v
       ParseIntPipe
             |
             v
      productoId: 1
             |
             v
   ProductosController
             |
             v
    ProductosService
             |
             | find()
             v
     ¿Existe producto?
        |
   +----+----+
   |         |
  Sí         No
   |         |
   v         v
Buscar      404
Huella     Not Found
   |
   v
¿Existe información?
   |
 +--+--+
 |     |
Sí     No
 |     |
 v     v
Datos   null / [] / null
 |          |
 +-----+----+
       |
       v
HuellaVerdeProductoDto
       |
       v
     200 OK

Ejemplo de Solicitud

GET /productos/1/huella-verde

Ejemplo de Respuesta Exitosa

{
  "calificacionSustentable": 4.8,
  "materiales": [
    "Algodón orgánico",
    "Tintes naturales"
  ],
  "elaboracion": "Producto confeccionado utilizando algodón orgánico y procesos de bajo impacto ambiental."
}

Respuesta:

200 OK

Manejo de Errores

Identificador inválido

Ejemplo:

GET /productos/abc/huella-verde

Respuesta:

400 Bad Request

Gestionado mediante:

ParseIntPipe

Producto inexistente

Ejemplo:

GET /productos/999/huella-verde

Si el producto no existe:

404 Not Found

Respuestas HTTP

Código Situación
200 OK Información de Huella Verde obtenida correctamente
200 OK con valores vacíos El producto existe pero todavía no posee información de Huella Verde
400 Bad Request productoId no corresponde a un entero válido
404 Not Found El producto solicitado no existe

Reglas de Negocio Actuales

Actualmente las reglas pueden resumirse como:

1. productoId debe ser un entero válido.

2. El producto debe existir.

3. Si el producto no existe:
      404 Not Found.

4. Si existe:
      buscar Huella Verde mediante productoId.

5. Si existe información:
      devolver sus datos.

6. Si no existe información:
      devolver:
      {
        calificacionSustentable: null,
        materiales: [],
        elaboracion: null
      }.

7. La consulta no modifica la información.

Responsabilidades Pendientes de Definición

Aunque la consulta ya se encuentra implementada, todavía pueden definirse reglas adicionales relacionadas con:

quién registra la información
quién valida la información
quién puede actualizarla
cómo se calcula la calificación
qué criterios sustentables deben considerarse

Estas responsabilidades podrán formar parte posteriormente de funcionalidades administrativas o de la cuenta del emprendedor.

Relación con Detalle de Producto

La Huella Verde corresponde a información ampliada asociada a:

Detalle de Producto

Sin embargo, utiliza un endpoint independiente.

Detalle de Producto
        |
        +----------------------------+
        |                            |
        v                            v
ProductoDetalleDto          Huella Verde
                                  |
                                  v
                   HuellaVerdeProductoDto

Frontend puede construir una misma página utilizando ambos contratos.

Separación de Responsabilidades

El endpoint principal:

GET /productos/:productoId

devuelve:

ProductoDetalleDto

mientras que:

GET /productos/:productoId/huella-verde

devuelve:

HuellaVerdeProductoDto

Conceptualmente:

Producto
   |
   +--> Información general
   |          |
   |          v
   |   ProductoDetalleDto
   |
   +--> Información sustentable
              |
              v
      HuellaVerdeProductoDto

Documentación Swagger

El endpoint se encuentra documentado mediante decoradores de @nestjs/swagger.

Entre ellos:

@ApiOperation()
@ApiParam()
@ApiOkResponse()
@ApiNotFoundResponse()

El parámetro:

productoId

se documenta como:

Number

y la respuesta exitosa utiliza:

HuellaVerdeProductoDto

Para mayor información consultar:

OpenAPI y Swagger

Posibles Mejoras Futuras

Posteriormente podrán evaluarse funcionalidades como:

  • Definir el método de cálculo de la calificación sustentable.
  • Incorporar certificaciones.
  • Incorporar origen de materiales.
  • Incorporar información de reciclabilidad.
  • Incorporar huella de carbono.
  • Incorporar lugar de fabricación.
  • Incorporar validación administrativa de la información.
  • Permitir que un emprendedor registre o actualice los datos.
  • Mantener historial de modificaciones.

Estas mejoras deberán implementarse cuando formen parte de las reglas funcionales de BuenOrigen.

Relación con la Arquitectura

La funcionalidad pertenece actualmente al dominio:

Productos

y utiliza:

ProductosModule
      |
      v
ProductosController
      |
      v
ProductosService
      |
      v
HuellaVerdeProductoDto

Páginas relacionadas: