INV-002 Fase 3 — Despacho multicriterio y auto-selección de almacén
Implementación de la Fase 3 de la mejora INV-002 (Almacenes Múltiples): convertir la elección de bodega para despachar en una recomendación fundamentada.
📋 Alcance
Antes, al despachar una solicitud el almacenista elegía la bodega a mano y el sistema solo decía si esa bodega cubría el pedido entero o no (binario). Con varias bodegas eso es prueba y error, y no contempla repartir un pedido.
Ahora el sistema:
- Puntúa cada almacén activo con varios criterios a la vez.
- Ordena y recomienda, explicando por qué.
- Propone un plan de reparto cuando ninguna bodega cubre todo el pedido.
La decisión final sigue siendo del almacenista (Q3: asistida, no impuesta).
🎯 Criterios y puntaje
Sobre las líneas pendientes de la solicitud:
| Métrica | Descripción |
|---|---|
cobertura | Unidades disponibles ÷ unidades requeridas |
productosCubiertos | Líneas cuyo stock alcanza el faltante completo |
lineasFaltantes | Líneas que obligan a repartir |
holgura | Margen que queda tras despachar |
dejaBajoMinimo | Si al despachar otro producto quedaría bajo stock_minimo |
puntaje = 100 * (0.60 * cobertura
+ 0.25 * (productosCubiertos / totalLineas)
+ 0.15 * holgura)
- 10 * lineasFaltantes
- 5 si dejaBajoMinimo
Acotado a [0, 100]. La cobertura domina (el objetivo es entregar), productosCubiertos evita
premiar el stock concentrado en un solo producto, y holgura / dejaBajoMinimo protegen el inventario
restante.
📦 Plan de reparto (voraz)
Cuando ninguna bodega cubre el pedido:
- Se resuelven primero las líneas más escasas (no gastar el stock fácil en lo difícil).
- Se toma de las bodegas con más stock disponible.
- Primera pasada sin bajar del mínimo; si aún falta, segunda pasada con el resto.
El plan indica cada asignación (producto, almacén, cantidad) y el faltante no cubierto.
🔌 API
| Método | Ruta | Roles |
|---|---|---|
GET | /api/solicitudes/:id/sugerencia-despacho | Admin, Almacenista, Auxiliar inventario, Auditor |
Devuelve mejorAlmacenUnico, el ranking opciones[] con puntajes, motivos[] legibles y
planSugerido. Es una consulta pura: no modifica la solicitud.
GET /api/solicitudes/:id/almacenes-disponibles (Fase 1) se conserva por compatibilidad.
🖥️ UI
En el diálogo de despacho:
- El almacén recomendado aparece preseleccionado.
- Se muestra el ranking con puntaje y cobertura de cada bodega.
- Se muestran los motivos de la recomendación.
- Si hay que repartir, se muestra el plan sugerido producto por producto.
- Se avisa si el pedido no es cubrible con el stock total.
🔑 Archivos clave
Backend (ccf-almacen-api)
src/domains/solicitudes/solicitudes.service.ts— interfacesSugerenciaDespacho,OpcionAlmacenDespacho,PlanDespacho; métodosgetSugerenciaDespacho,construirPlanDespacho,redondear1src/domains/solicitudes/solicitudes.controller.ts—GET /:id/sugerencia-despacho
Frontend (ccf-almacen-web)
src/models/almacen.entity.ts— tipos de la sugerenciasrc/api/almacenes.ts—getSugerenciaDespacho(idSolicitud)src/components/requests/request-dispatch.tsx— preselección, ranking, motivos y plan
Spec: .opencode/skills/ideas/data/docs/superpowers/specs/INV-002-fase-3-despacho-multicriterio.md
✅ Verificación
tsc --noEmit, build y lint en 0 en ccf-almacen-api y ccf-almacen-web.
📌 Pendiente
- Fase 4: roles y permisos por bodega.
- Reportes avanzados por bodega (se tratan por separado).
