Requerimiento funcional — Frontend: combos en el catálogo de productos¶
Audiencia: negocio + dev que trabaje en frontend/.
Contexto: 01-requerimiento.md, 04-diseno-oms.md.
Documento hermano: 06-requerimiento-frontend.md — cubre el combo
dentro del pedido (buscador del pedido, líneas, facturación). Este documento cubre el combo
en el catálogo: la lista de productos y el modal de detalle.
Detalle técnico: frontend/docs/productos-compuestos/ (fuera de esta carpeta de análisis).
Estado: requerimiento acordado 2026-07-16. Alcance nuevo, no contemplado en el análisis original.
Se entrega en dos fases (decisión 2026-07-16):
| Fase | Alcance | Estado |
|---|---|---|
| 1 — Mostrar | Distintivo de combo + lista de componentes (nombre × cantidad), leídos del hit. RF-C1, RF-C2, RF-C3, RF-C6. | En implementación |
| 2 — Chequear | Estado de cada componente (publicado / sin stock / no publicado) y resumen de consistencia. RF-C4, RF-C5. | Diferida |
El corte es natural: la fase 1 no hace ninguna llamada de datos (todo viene en el hit), mientras que la fase 2 requiere resolver cada componente contra el catálogo. Cada RF indica su fase.
1. Por qué existe este documento¶
El análisis de combos se hizo entero desde la óptica del pedido: cómo agregar un combo, cómo lo explota SAP, cómo facturarlo. El catálogo de productos (la pantalla donde el vendedor busca y consulta productos, antes y fuera de cualquier pedido) quedó sin cubrir.
Es una omisión que importa, porque el catálogo es donde el vendedor mira el producto antes de venderlo. Hoy un combo se ve exactamente igual que un producto simple: nada indica que sea un combo, y no hay forma de saber qué trae adentro sin salir del OMS.
2. Objetivo¶
Que el vendedor, desde el catálogo, pueda:
- Distinguir de un vistazo qué productos son combos. (fase 1)
- Ver de qué está compuesto un combo, sin abrirlo y sin salir del OMS. (fase 1)
- Chequear el estado de los componentes contra el catálogo publicado, para detectar combos con datos desactualizados antes de intentar venderlos. (fase 2)
3. El problema real que resuelve el punto 3 — motiva la fase 2¶
La receta de un combo la publica el sistema integrador. Idealmente todos sus componentes también están publicados como productos individuales. En la práctica no siempre pasa.
Medición sobre el catálogo de desarrollo (2026-07-16, 10 combos publicados):
| Métrica | Valor |
|---|---|
| Componentes distintos referenciados por los combos | 31 |
| Componentes no publicados en ningún catálogo | 3 (10%) |
| Componentes publicados pero sin stock | 5 |
| Combos con al menos un componente no publicado | 2 de 10 |
| Combos con al menos un componente sin stock | 6 de 10 |
| Combos totalmente sanos | 2 de 10 |
Solo 2 de 10 combos están completamente sanos. El vendedor hoy no tiene manera de enterarse. Con este cambio, lo ve.
El problema dominante no es el componente ausente (3), sino el componente sin stock (5). El diseño debe tratar el estado "sin stock" como el caso frecuente y darle el peso visual correspondiente; "no publicado" es la excepción.
Los números son de desarrollo y no necesariamente reflejan producción. Además son volátiles: durante el propio análisis, un componente pasó de ausente a publicado entre dos mediciones con minutos de diferencia. Sirven para dimensionar el problema y para exigir que la UI trate ambos casos como situaciones normales, no como errores.
3.1 "El catálogo" son dos catálogos¶
Un componente puede estar publicado en el catálogo principal o en el catálogo de productos de proveedor no vinculados (los que la lista de productos ya muestra con el distintivo COMPULANDIA). Ambos son catálogo válido y vendible.
Esto no es un detalle técnico: 4 de los componentes que parecían ausentes están en el segundo catálogo, con stock real (10, 5, 20 y 31 unidades). Un chequeo que mire solo el catálogo principal reportaría como "no publicado" un componente que está disponible y se vende — exactamente el tipo de mentira que §4 prohíbe.
Un componente solo puede declararse "no publicado" después de buscarlo en ambos catálogos.
4. Qué significa (y qué NO significa) el chequeo¶
Esta distinción es la regla más importante del documento y no debe diluirse al implementar.
El chequeo se hace contra el catálogo publicado (Algolia), que es la fuente de la verdad de la receta. Por lo tanto:
| El chequeo SÍ dice | El chequeo NO dice |
|---|---|
| Si el componente está publicado en el catálogo | Si el componente existe en SAP |
| Cuánto stock declara el catálogo | Si el combo se puede vender |
| Si la receta publicada está completa y consistente | Si el pedido o la factura van a funcionar |
Un componente ausente del catálogo puede existir perfectamente en SAP, y el combo puede ser vendible sin problema. Quien responde "¿esto se puede vender?" es la verificación contra SAP del flujo de pedido (06 RF-2), no esta pantalla.
Consecuencia para la UI: el catálogo informa, no bloquea ni desalienta la venta. El lenguaje debe ser descriptivo ("no publicado en el catálogo"), nunca un veredicto ("no disponible", "no existe", "no se puede vender"). Un cartel rojo de error sobre un combo perfectamente vendible es peor que no mostrar nada.
5. Historias de usuario¶
HU-1 — Identificar un combo en la lista
Como vendedor, quiero distinguir a simple vista qué productos de la lista son combos, para saber que ese producto trae varias cosas adentro.
HU-2 — Ver el contenido del combo desde la lista
Como vendedor, quiero ver en la tarjeta qué componentes trae el combo, para responderle al cliente sin tener que abrir el producto.
HU-3 — Ver el detalle completo del combo
Como vendedor, quiero ver en el detalle del producto la lista completa de componentes con su cantidad, para conocer exactamente qué estoy vendiendo.
HU-4 — Chequear los componentes contra el catálogo
Como vendedor, quiero saber si los componentes de un combo están publicados y con stock, para detectar combos con información desactualizada antes de ofrecerlos.
6. Requerimientos funcionales¶
RF-C1: Distintivo de combo en la lista — fase 1¶
Todo producto que sea un combo se muestra en la lista con un distintivo visual claro ("COMBO"), coherente con los distintivos que ya existen en la tarjeta y sin taparlos ni desplazarlos.
Un producto que no es combo se ve exactamente igual que hoy. Cero regresiones.
RF-C2: Componentes en la tarjeta — fase 1¶
La tarjeta del combo muestra su contenido: nombre y cantidad de cada componente.
- Hay espacio suficiente y el detalle es valioso para el vendedor: se muestra en la tarjeta, no solo en el modal.
- La cantidad de componentes es muy variable (de 1 a 10 en los datos reales). La tarjeta debe resolver el caso largo sin deformarse: se muestra un número acotado de componentes y se indica cuántos quedan ("+3 más"), remitiendo al detalle.
- Los componentes en la tarjeta son informativos y solo lectura. No hay ninguna acción sobre un componente individual.
RF-C3: Detalle del combo en el modal — fase 1¶
El modal de detalle del producto, cuando el producto es un combo:
- Lo identifica como combo.
- Muestra la lista completa de componentes (sin recortar), con nombre y cantidad.
- Los presenta como solo lectura, sin ninguna vía para agregar, quitar o editar componentes (regla inviolable del proyecto — 04 §7.7).
- El precio que se muestra sigue siendo el precio propio del combo, nunca la suma de los componentes.
RF-C4: Estado de cada componente — fase 2 (diferida)¶
Cada componente se muestra con su estado respecto del catálogo publicado. Tres estados posibles, y los tres tienen que existir en la UI:
| Estado | Significado | Tratamiento |
|---|---|---|
| Publicado, con stock | Está en alguno de los dos catálogos (§3.1) y declara stock | Normal, sin alarma |
| Publicado, sin stock | Está en alguno de los dos catálogos, stock 0 | Señalizado como advertencia suave — es el caso más frecuente |
| No publicado | No está en ninguno de los dos catálogos | Señalizado como informativo, con el nombre que trae la receta |
Un componente no publicado igual se muestra (la receta trae su nombre y cantidad). Nunca se oculta ni se omite de la lista: el vendedor tiene que ver el combo completo.
Cuando el componente está publicado, se aprovecha lo que el catálogo ya sabe de él (imagen, precio unitario, stock) para enriquecer la fila.
Regla de identidad: un componente se da por encontrado solo si el resultado corresponde exactamente al componente buscado. Una coincidencia aproximada no cuenta como encontrada: mostrar el stock de otro producto parecido es peor que no mostrar nada, porque el vendedor no tiene forma de detectar el error.
RF-C5: Resumen de estado del combo — fase 2 (diferida)¶
El combo muestra un resumen de la consistencia de su receta, para que el vendedor no tenga que leer componente por componente (relevante con 10 componentes).
- Si todos los componentes están publicados y con stock: sin ruido visual.
- Si hay componentes sin stock o no publicados: un indicador con el conteo ("2 componentes sin stock", "1 componente no publicado").
Este resumen es informativo. Nunca deshabilita la venta ni bloquea el producto (§4).
RF-C6: Sin filtro "solo combos" en esta etapa¶
Un filtro de catálogo para listar únicamente combos queda fuera de alcance: el tipo de producto no es un atributo filtrable del índice hoy, y habilitarlo requiere una configuración del lado de Algolia que no depende de este repo. Si se decide habilitarlo, entra como requerimiento aparte.
7. Fuera de alcance¶
- Editar, armar o modificar combos y sus recetas desde el OMS (regla del proyecto).
- Filtrar o facetar el catálogo por tipo de producto (§RF-C6).
- Verificar o crear el combo en SAP desde el catálogo: eso vive en el flujo del pedido (06 RF-2). Esta pantalla no llama a verify/sync.
- Corregir el catálogo publicado o dar de alta componentes faltantes: es responsabilidad del sistema integrador que publica el índice.
8. Criterios de aceptación¶
Fase 1¶
- Un combo en la lista se distingue de un producto simple sin abrirlo.
- Un producto que no es combo se ve y se comporta exactamente igual que hoy.
- La tarjeta de un combo muestra sus componentes; con 10 componentes la tarjeta no se deforma y se indica cuántos no se muestran.
- El modal de un combo muestra la lista completa de componentes con su cantidad.
- No existe ninguna vía en la UI para modificar los componentes de un combo.
- La fase 1 no afirma nada sobre disponibilidad: muestra la receta, no el estado de los componentes. Ningún texto puede sugerir que el combo o sus componentes estén verificados.
Fase 2¶
- Los componentes publicados muestran su stock; los no publicados se muestran igual, señalizados y con el nombre de la receta.
- Un combo con todos sus componentes publicados y con stock no muestra advertencias.
- Un combo con componentes ausentes o sin stock muestra el resumen con el conteo correcto.
- Ningún mensaje de esta pantalla afirma que el combo no existe, no está disponible o no se puede vender (§4).
- El catálogo no bloquea la venta de ningún combo por resultado del chequeo.
9. Dependencias¶
Ninguna con el backend. Todo lo que necesita este requerimiento ya está publicado en el índice de Algolia y se lee directo desde el frontend. No depende de los endpoints verify/sync ni de la etapa de implementación del backend (05), y puede entregarse antes que el resto del proyecto de combos.