Saltar a contenido

SOURCE-002D - Stock intradiario liviano cada 10 minutos

Fecha: 2026-06-07

Estado: FUENTE FUNCIONAL FUTURA NO IMPLEMENTADA

Scope: tenant

tenant_id: alpuntodeventa

Owner: Gabi / Carlos Canu

Fuente de verdad: docs/tenants/alpuntodeventa/business-observer/sources/SOURCE-002D-STOCK-CURRENT-10MIN.md

1. Proposito

Esta fuente futura existe para documentar la necesidad funcional de mantener una sincronizacion frecuente y liviana del stock actual de articulos activos.

Su objetivo es que el observer pueda saber:

  • si un SKU tiene stock ahora
  • si un SKU volvio a tener stock durante el dia
  • si conviene avisar a vendedores o direccion comercial

La intencion es sostener operacion viva y deteccion temprana de ingresos sin convertir esta capa en una sync pesada.

No se implementa nada en este documento.

No se define SQL.

No se definen scripts.

No se define API.

Solo se documenta una necesidad funcional futura.

2. Diferencia con snapshot diario

La diferencia funcional debe quedar explicita:

  • SOURCE-002C guarda historia diaria de cierre
  • SOURCE-002D mantiene estado vivo liviano
  • ambas son complementarias

Lectura obligatoria:

  • SOURCE-002C sirve para historia y analisis de quiebres
  • SOURCE-002D sirve para operacion actual y seguimiento intradiario

Por eso SOURCE-002D no debe confundirse con historico diario.

Regla canonica obligatoria:

  • cada lectura intradiaria debe anclarse en tenant_id + SKU
  • el SKU sigue siendo la identidad canonica del producto tambien en esta capa liviana
  • stock, stock en bultos y cualquier contexto opcional de marca o descripcion deben interpretarse como atributos observados del SKU
  • politica comercial, promociones, estrategia comercial, actividad comercial y volumetria / logistica siguen colgando de tenant_id + SKU, pero no deben viajar en esta capa intradiaria salvo contexto minimo excepcional

3. Regla transversal: historicos por valor de decision

Regla documental oficial:

  • SOURCE-002D es una capa vigente e intradiaria, pero debe pensarse desde el diseno para no bloquear historicos utiles por valor de decision
  • si la observacion intradiaria permite medir evolucion, detectar patrones, explicar tendencias, generar alertas, mejorar decisiones comerciales o alimentar aprendizaje futuro, debe contemplarse una salida historica liviana en una capa separada
  • no se trata de guardar cada lectura para siempre sin criterio
  • se trata de preservar senales utiles como quiebres, recuperaciones o ingresos cuando negocio realmente los necesita

Aplicacion principal desde SOURCE-002D hacia historicos o eventos futuros:

  • quiebres de stock detectados intradiariamente
  • recuperaciones de stock detectadas intradiariamente
  • ingresos de mercaderia detectados por cambio de disponibilidad
  • alertas operativas de reposicion cuando el patron observado lo justifique

4. Frecuencia sugerida

Frecuencia funcional propuesta:

  • cada 10 minutos

Aclaraciones obligatorias:

  • es una frecuencia funcional inicial
  • debe validarse con Gabi
  • debe evaluarse para no sobrecargar SGC
  • debe evaluarse para no sobrecargar VPS

La frecuencia final podria cambiar si negocio y capacidad operativa asi lo requieren.

5. Alcance funcional liviano

Esta capa futura deberia enfocarse solo en articulos con estado Activo.

Campos minimos futuros:

  • tenant / contexto
  • fecha y hora de sincronizacion
  • SKU
  • stock unidades
  • stock en bultos si sale barato calcularlo
  • estado activo o senal equivalente de vigencia si ya viene en la misma lectura
  • origen de datos
  • fecha y hora fuente si existe

Campos opcionales:

  • deposito
  • marca
  • descripcion corta solo si ya viene sin costo operativo relevante

Si aparece marca en esta capa:

  • debe leerse solo como atributo comercial de apoyo del SKU
  • no convierte a SOURCE-002D en una capa de analitica por marca separada del producto

Regla funcional clave:

  • no incluir campos pesados si no son necesarios
  • no consultar costos, precios, IVA, margenes, descuentos, proveedor, palletizado ni fechas operativas en esta capa
  • no consultar politica comercial, promociones, estrategia comercial, actividad comercial ni volumetria / logistica detallada en esta capa
  • no usar esta capa para transportar todo el maestro de productos

Referencia relacionada:

  • SOURCE-002-FUTURE-LAYER-MAPPING.md: cierra documentalmente que SOURCE-002D debe quedarse como stock actual liviano y no como una copia frecuente del maestro completo

Esta fuente debe ser liviana porque su valor esta en la frecuencia y no en transportar toda la riqueza del maestro de productos.

6. Criterio minimo recomendado para la consulta

Documentalmente, la consulta futura de SOURCE-002D deberia aspirar al minimo util posible:

  • SKU
  • stock unidades
  • stock bultos solo si ya cae naturalmente del mismo origen
  • marca o descripcion corta solo si ayudan a lectura operativa sin volver pesada la consulta
  • timestamp de observacion o de extraccion

No deberia cargar en la misma lectura:

  • listas de precios L1..L9
  • costo
  • IVA
  • margenes
  • descuentos
  • proveedor
  • palletizado
  • fechas de ultima compra, venta o cambio de costo

Si de estas lecturas nacen eventos historicos utiles, deben materializarse en una capa de eventos o historial separado y no dentro de la sync liviana.

7. Que permite detectar

Con esta fuente futura, APV podria detectar:

  • ingreso de stock antes de las 17:00
  • salida de quiebre durante el dia
  • stock actual para recomendaciones
  • aviso de reposicion a vendedores
  • recuperacion de oportunidades de venta
  • bloqueo de recomendaciones de productos sin stock

Tambien puede alimentar, en una capa separada, historicos utiles sobre:

  • duracion aproximada de quiebres
  • velocidad de recuperacion
  • frecuencia de ingresos de mercaderia
  • patrones intradiarios de reposicion

La utilidad principal es reducir ceguera intradiaria.

8. Caso de uso APV

Ejemplo:

Lunes 17:00:

  • Baldo 500 gr
  • stock 0

Martes:

  • 09:00: stock 0
  • 10:10: stock 0
  • 10:20: stock 120

Lectura funcional del observer:

  • el producto volvio a estar disponible aproximadamente a las 10:20
  • esa recuperacion puede quedar historizada como evento util si negocio quiere medir patrones o alertas de reposicion

Si un vendedor reporto demanda no atendida a las 09:30, esa senal podria servir para recontactar al cliente una vez recuperado el stock.

9. Relacion con UC007

UC007 puede usar esta fuente para:

  • no recomendar productos sin stock
  • priorizar avisos de reposicion

Lectura funcional:

esta capa ayuda a que la recomendacion no llegue tarde ni empuje articulos que en ese momento no pueden sostenerse.

10. Relacion con UC004

UC004 puede usar esta fuente para cerrar oportunidades pendientes cuando vuelve el stock.

No reemplaza la captura de demanda no atendida.

La complementa al mostrar cuando reaparece disponibilidad.

11. Relacion con UC009

UC009 puede usar esta fuente para medir la duracion aproximada del quiebre con mas precision que una foto diaria.

Eso mejora la lectura de:

  • recurrencia
  • severidad
  • velocidad de reposicion
  • dano aproximado por proveedor o SKU

12. Riesgos y limites

  • frecuencia demasiado alta puede sobrecargar origen
  • stock actual puede cambiar rapidamente
  • no reemplaza auditoria de inventario
  • puede haber diferencias por deposito
  • se necesita tolerancia ante fallas temporales
  • si se le agregan demasiados campos, deja de cumplir su objetivo liviano
  • si se intenta usar esta capa como historico bruto completo, pierde foco y eficiencia

Tambien debe asumirse que:

  • la hora observada seria aproximada, no necesariamente exacta al minuto del movimiento real
  • el stock podria ser teorico y no siempre vendible
  • un origen parcial podria no reflejar toda la red logistica

13. Preguntas pendientes para Gabi

  • confirmar si cada 10 minutos es aceptable
  • confirmar si stock de activos alcanza
  • confirmar si se requiere por deposito
  • confirmar fuente exacta del stock
  • confirmar si stock bultos debe ir siempre o solo si el origen lo entrega casi gratis
  • confirmar si se deben disparar avisos futuros

14. Relacion con otras fuentes

Relacion funcional esperada:

  • SOURCE-002: maestro de productos y contexto de SKU
  • SOURCE-002C: historia diaria de cierre
  • SOURCE-002D: estado vivo liviano

Conclusion funcional:

  • SOURCE-002D no duplica SOURCE-002
  • SOURCE-002D no reemplaza SOURCE-002C
  • SOURCE-002D no debe absorber precios, costos ni impuestos intradiarios
  • SOURCE-002-FUTURE-LAYER-MAPPING refuerza que tampoco debe absorber margenes, descuentos, proveedor ni palletizado
  • los historicos utiles de quiebres, recuperaciones o ingresos deben nacer en una capa separada y no engordar SOURCE-002D
  • SOURCE-002C y SOURCE-002D deben mantenerse separadas

15. Confirmaciones de alcance

  • no se implemento codigo
  • no se crearon tablas
  • no se crearon scripts
  • no se toco runtime
  • no se tocaron Docker, VPS, Portainer ni NPM
  • no se ejecutaron conexiones reales
  • no se ejecutaron sincronizaciones
  • no se diseno SQL final
  • no se disenaron APIs
  • no se diseno IA
  • no se mezclo Core con Tenant
  • la fuente queda documentada como futura y no implementada