SOURCE-002C - Snapshot diario de stock / producto

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-002C-STOCK-DAILY-SNAPSHOT.md

1. Proposito

Esta fuente futura existe para documentar la necesidad funcional de guardar, todos los dias, una foto completa del inventario de APV cerca del cierre comercial, tomando como referencia inicial las 17:00 de Argentina / Buenos Aires.

La utilidad principal de esta fotografia diaria es construir historia de inventario para:

• analisis historico de disponibilidad
• deteccion de quiebres de stock
• medicion de dias sin disponibilidad
• lectura de productos que cerraron sin stock
• estimacion de oportunidad economica perdida cuando se cruce con ventas, reclamos y demanda no atendida

Esta fuente no implica implementacion tecnica ahora.

No define tablas.

No define scripts.

No define SQL final.

No define APIs.

Solo deja documentada la necesidad funcional para futura implementacion gobernada.

2. Diferencia con stock actual

Este snapshot diario no reemplaza al stock vivo.

Su rol es distinto:

• SOURCE-002C guarda una foto historica de cierre
• SOURCE-002D mantendra en el futuro un estado actual liviano e intradiario

La diferencia es obligatoria porque:

• una foto diaria sirve para historia y comparabilidad
• el stock vivo sirve para operacion inmediata y deteccion temprana de reposicion

Por lo tanto, ambas capas deben convivir sin mezclarse.

Regla canonica obligatoria:

• cada snapshot debe identificarse por tenant_id + SKU + fecha_snapshot
• el SKU sigue siendo la ancla canonica del producto dentro de esta capa
• stock, stock en bultos, estado, marca, proveedor, categoria, precios de cierre opcionales, IVA, costos y demas contexto solo pueden leerse como atributos o relaciones observadas del SKU
• politica comercial, promociones, estrategia comercial, actividad comercial y volumetria / logistica pueden viajar solo como contexto resumido de cierre si negocio lo necesita, pero no son el dominio principal de esta capa

3. Regla transversal: historicos por valor de decision

Regla documental oficial:

• SOURCE-002C existe porque el stock diario de cierre tiene valor de decision
• debe contemplarse historico cuando un dato permita medir evolucion, detectar patrones, explicar tendencias, generar alertas, mejorar decisiones comerciales o alimentar aprendizaje futuro
• no se trata de guardar todo sin limite
• se trata de disenar un historico liviano, trazable y util

Aplicacion minima en esta capa:

• snapshots diarios utiles de stock
• quiebres de stock observados al cierre
• recuperaciones de stock observadas entre cierres
• ingresos de mercaderia inferibles al comparar cierres cuando el dato sirva para abastecimiento o aprendizaje

4. Momento sugerido

Horario funcional propuesto:

• 17:00
• zona horaria: Argentina / Buenos Aires

Aclaracion obligatoria:

• este horario es una propuesta funcional inicial
• debera validarse con Gabi
• podra ajustarse si el cierre comercial real o la operacion de APV recomiendan otro corte

5. Alcance funcional

La necesidad funcional es guardar una foto completa de los SKU relevantes del inventario, incluyendo como minimo:

• tenant / contexto
• fecha del snapshot
• hora del snapshot
• SKU
• descripcion al cierre
• marca al cierre
• categoria al cierre
• proveedor al cierre si existe
• estado del producto al cierre
• stock unidades
• stock bultos si aplica
• unidades por bulto si existe
• indicador de faltante
• origen de datos
• fecha de extraccion

Reglas de cuidado:

• no se esta diseniando una tabla SQL final
• no se esta fijando aun nombres definitivos de columnas
• no se esta definiendo todavia si el origen sera tabla, vista, export o sync
• el listado anterior es funcional y preparatorio
• si se conserva proveedor al cierre, Cod Proveedor debe mantenerse como identificador de negocio del proveedor asociado al SKU
• si se conserva Proveedor, debe leerse como nombre legible asociado al SKU y no como clave analitica autonoma
• si se conserva Marca, debe leerse como atributo comercial del SKU

6. Criterio documental para costo, precio e impuestos

Para esta capa se recomienda una estrategia prudente:

• obligatorio en SOURCE-002C: identidad minima del producto y fotografia de stock
• recomendable si el costo operativo lo permite: conservar tambien costo vigente, precio vigente, IVA vigente, descuento permitido y precio oferta vigentes al momento del cierre
• solo como contexto opcional de cierre: Estrategico, Acepta Devolucion, CantVtaMin, CantVentaAgrupada, UnidadMedida, Unidades_x_Bulto, Stock en Bultos, PesoxUnidad, VolumenxUnidad, CantBultosxPallet, CantUnidxPallet
• no recomendable: intentar guardar en esta misma capa toda la riqueza completa de listas L1..L9, margenes, descuentos de compra y calculos derivados si eso vuelve pesado el snapshot diario

Lectura documental:

• SOURCE-002C debe servir primero para historia de stock
• los valores economicos de cierre son utiles como contexto
• si esos valores economicos de cierre ayudan a explicar tendencias, alertas o decisiones, deben contemplarse como snapshot historico util
• el historico fino de cambios intradiarios de precio o costo necesita una capa separada y no debe forzarse dentro de SOURCE-002C

Historicos economicos que esta capa puede contemplar de forma resumida si aportan valor de decision:

• costo vigente al cierre
• precio o lista vigente al cierre
• IVA vigente al cierre
• margen o descuento relevante al cierre

Referencia relacionada:

• SOURCE-002-FUTURE-LAYER-MAPPING.md: consolida la frontera entre snapshot diario, maestro vigente e historiales economicos por cambio

7. Casos de uso que consume

Esta fuente futura se relaciona directamente con:

• UC004 Demanda no atendida
• UC005 Calendario operativo
• UC007 Recomendaciones priorizadas
• UC009 Proveedores y abastecimiento
• UC002 Crecimiento
• UC008 Surtido y mix

Lectura funcional por UC:

• UC004: ayuda a diferenciar faltante observado de demanda confirmada y a estimar oportunidad perdida con mas evidencia temporal
• UC005: permite leer dias efectivos sin stock y mejorar comparaciones sobre ventanas operativas reales
• UC007: aporta historia de disponibilidad para priorizar mejor recomendaciones y no sobrerreaccionar a un caso aislado
• UC009: permite medir quiebres, recurrencia y dano por proveedor, marca o SKU
• UC002: ayuda a no empujar crecimiento en productos que cierran repetidamente sin disponibilidad
• UC008: ayuda a validar si una oportunidad de surtido puede sostenerse en el tiempo

8. Que permite analizar

Con esta fuente, APV podria analizar por ejemplo:

• que productos cerraron sin stock
• cuantos dias consecutivos estuvieron sin stock
• que productos mostraron recuperaciones de stock entre cierres
• que productos evidenciaron ingresos de mercaderia al comparar snapshots
• que marcas tuvieron mas quiebres
• que proveedores tuvieron mas quiebres
• que productos estrategicos quedaron sin disponibilidad
• oportunidad economica perdida estimada
• impacto por SKU, marca, proveedor, zona o vendedor cuando se cruce con ventas y reclamos

La utilidad no esta en prometer precision exacta.

La utilidad esta en construir historia suficiente para priorizar mejor.

9. Ejemplo APV

Caso simple:

Baldo 500 gr

• lunes 17:00: stock 0
• martes 17:00: stock 90

Lectura funcional:

• el lunes el producto cerro en quiebre
• el martes el producto ya cerro con disponibilidad
• la comparacion entre ambos cierres deja trazada una recuperacion de stock
• al cruzarlo con ventas y reclamos puede analizarse si hubo un quiebre breve, repetido o comercialmente danino

10. Riesgos y limites

Riesgos y limites obligatorios:

• una foto diaria puede ocultar ingresos intermedios
• una foto diaria de costo o precio solo reflejaria el valor de cierre y no todos los cambios intradiarios
• no permite saber la hora exacta de reposicion
• necesita complementarse con stock actual frecuente
• no todo stock cero implica venta perdida real
• no debe confundirse con demanda confirmada

Tambien debe asumirse que:

• el stock observado podria ser teorico y no necesariamente vendible
• podria haber diferencias por deposito si el origen no las separa
• una lectura historica sin cruce con ventas y reclamos puede exagerar o subestimar el dano comercial

11. Reglas de cuidado

• diferenciar siempre snapshot historico de stock vivo
• no usar esta fuente sola para decisiones urgentes
• cruzar siempre con ventas y reclamos cuando se estime oportunidad perdida
• no tratar el snapshot diario como sustituto de historial de cambios intradiarios de costo o precio
• usar esta capa para historico por valor de decision, no como deposito ilimitado de todo cambio posible

Regla madre:

SOURCE-002C debe leerse como historia de cierre y no como confirmacion de demanda real.

12. Preguntas pendientes para Gabi

• confirmar si 17:00 es el horario correcto
• confirmar si deben incluirse todos los SKU o solo los activos
• confirmar si se necesita deposito
• confirmar si stock en unidades alcanza o tambien bultos
• confirmar si costo, precio e IVA de cierre deben guardarse en la foto diaria o en una capa separada de snapshot economico

13. Relacion con otras fuentes

Relacion funcional esperada:

• SOURCE-002: puede aportar base de maestro de productos y contexto de SKU
• SOURCE-002C: agrega historia diaria de disponibilidad al cierre
• SOURCE-002D: agregara estado vivo liviano e intradiario

Conclusion funcional:

• SOURCE-002C no duplica SOURCE-002
• SOURCE-002C tampoco reemplaza SOURCE-002D
• SOURCE-002C no deberia absorber por defecto todo el historico de cambios de precios, costos, impuestos o margenes
• SOURCE-002-FUTURE-LAYER-MAPPING deja documentado que SOURCE-002C puede llevar stock de cierre y, opcionalmente, un resumen economico liviano, pero no la historia fina por cambio
• el valor de SOURCE-002C esta en preservar snapshots diarios utiles para decisiones, tendencias y aprendizaje futuro
• cada una cumple un rol distinto dentro del observer futuro

14. 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