SOURCE-002 - SGC Maestro de productos

Fecha: 2026-06-07

Estado: FUENTE REAL DOCUMENTADA CON AUTORIDAD COMPLETA VIGENTE

Scope: tenant

tenant_id: alpuntodeventa

Owner: Gabi / Carlos Canu

Fuente de verdad: docs/tenants/alpuntodeventa/business-observer/sources/SOURCE-002-SGC-PRODUCTOS.md

Autoridad preservada: docs/tenants/alpuntodeventa/business-observer/source-authority/SOURCE-002-PRODUCTOS-PRODUCTS-AUTHORITY.sql

1. Objetivo

Documentar que SOURCE-002 pasa a ser la autoridad vigente y completa para el maestro de productos de APV, preservando textual la query aportada y luego confirmada por Gabi como autoridad vigente, sin tocar runtime, sin conectarse a fuentes reales y sin reinterpretar la logica.

2. Definicion oficial

• source_id: SOURCE-002
• nombre funcional oficial: Maestro de productos
• fuente base documentada: [ecommerce].[dbo].[PRODUCTS]
• tipo de fuente: MSSQL / SGC
• estado: autoridad completa vigente

Regla oficial:

• SOURCE-002 es la fuente unica vigente para producto, marca, estado, stock actual, stock en bultos, proveedor, costos, precios, IVA, margenes, descuentos, logistica de bultos y pallets, y fechas operativas de compra/venta/cambio de costo
• tenant_id + SKU es la clave canonica del dominio producto para todo dato que sale de SOURCE-002
• todo dato de SOURCE-002 debe interpretarse como atributo, medicion, relacion vigente o relacion historica del SKU
• la query preservada en SOURCE-002-PRODUCTOS-PRODUCTS-AUTHORITY.sql queda confirmada por Gabi como autoridad vigente de ahora en adelante

2.1 Regla canonica de relacion por SKU

Confirmacion documental vigente:

• todos los datos publicados por la query de productos se relacionan por medio del SKU
• el dominio producto de SOURCE-002 se identifica por tenant_id + SKU
• articulo, marca, proveedor, stock, stock en bultos, costos, descuentos de compra, precios, listas, IVA, margenes, descuento permitido, precio oferta, categoria, subcategoria, unidad de medida, palletizado, fechas operativas e historicos utiles deben leerse como datos del SKU
• el analisis por proveedor o marca debe derivarse desde los SKU asociados y no desde datos sueltos sin vinculo con producto

Reglas especificas para relaciones comerciales:

• Cod Proveedor debe conservarse como identificador de negocio del proveedor asociado al SKU
• Proveedor debe conservarse como nombre o razon social legible asociado al SKU
• no debe usarse solo el texto de Proveedor como clave analitica
• Marca debe conservarse como atributo comercial asociado al SKU
• si en el futuro aparece un codigo de marca, debera preservarse junto con Marca

3. Autoridad vigente preservada

La autoridad vigente queda preservada textual en:

• source-authority/SOURCE-002-PRODUCTOS-PRODUCTS-AUTHORITY.sql

La query autoridad:

• usa WITH ProductosBase
• lee desde [ecommerce].[dbo].[PRODUCTS]
• filtra Estado = 'ACTIVO'
• mantiene SKU NOT IN ('0124', '3857', '3998', '3793') como primera lista conocida de exclusiones operativas
• esa lista no debe leerse como exclusion rigida sin explicacion de negocio
• la razon de negocio confirmada por Gabi es que algunos articulos del SGC se usan para operaciones internas o no tradicionales de compra/venta, por lo que no deben importarse como productos comerciales normales
• cualquier futuro script de sincronizacion debera tratar esa lista como una regla operativa configurable
• ordena por Marca ASC

No corresponde:

• simplificarla
• reinterpretar calculos
• cambiar aliases
• reemplazarla por una version resumida
• usar SOURCE-002C o SOURCE-002D como fuente base de stock actual

4. Cobertura funcional oficial

Esta autoridad cubre explicitamente:

• producto
• marca
• estado / vigencia
• stock actual
• stock en bultos
• costo lista proveedor
• descuentos de compra
• costo
• markup
• precio lista neto
• IVA
• precio lista final
• descuento permitido
• precio con descuento permitido
• precio oferta
• devolucion
• estrategia / clasificador
• precios y margenes L1..L9
• fechas de ultima compra / venta / cambio de costo
• dias sin comprar / vender / actualizar costo
• venta minima / venta agrupada
• unidad de medida
• peso y volumen
• palletizado
• proveedor
• categoria y subcategoria

Lectura canonica obligatoria:

• cada uno de esos dominios debe quedar vinculado al mismo tenant_id + SKU
• no deben separarse como hechos huerfanos sin referencia de producto

5. Campos observables en la autoridad

Campos principales publicados por la query:

• SKU
• Articulo
• Marca
• Estado
• Stock
• Stock en Bultos
• CostoListaProveedor
• Dcto Compra 1
• Dcto Compra 2
• Dcto Compra 3
• Costo
• Markup
• PrecioListaNeto
• AlicuotaIVA
• IVAPListaFinal
• PrecioListaFinal
• Descuento Permitido
• PrecioCDescPermitidoFinal
• PrecioOfertaFinal
• Acepta Devolucion
• Estrategico
• MargenL1 a MargenL9
• PrecioL1 a PrecioL9
• IVAPrecioL1 a IVAPrecioL9
• PrecioNetoL1 a PrecioNetoL9
• Fecha de Ultima Compra
• UltVenta
• UltCambioCosto
• DiasSinComprar
• DiasSinVender
• DiasSinActCosto
• CantVtaMin
• CantVentaAgrupada
• UnidadMedida
• PesoxUnidad
• VolumenxUnidad
• BasePallet
• AlturaPallet
• PLU Articulo
• [PLU Bulto]
• Unidades_x_Bulto
• CantUnidxPallet
• CantBultosxPallet
• PesoxPalletkg
• VolumenxPalletm3
• Cod Proveedor
• Proveedor
• Category
• SubCategoria

6. Separacion documental recomendada por capas

La query autoridad de SOURCE-002 trae mas informacion de la que conviene consultar con alta frecuencia.

Por eso, a nivel documental, se recomienda separar sus datos en estas capas funcionales futuras:

• identidad de producto: SKU, Articulo, Category, SubCategoria, PLU Articulo, [PLU Bulto]
• marca: Marca
• proveedor: Cod Proveedor, Proveedor
• estado / vigencia / gobernanza del producto: Estado
• politica comercial: Acepta Devolucion, Descuento Permitido, PrecioCDescPermitidoFinal, CantVtaMin, CantVentaAgrupada
• promociones: PrecioOfertaFinal
• estrategia comercial: Estrategico
• actividad comercial: Fecha de Ultima Compra, UltVenta, DiasSinComprar, DiasSinVender, DiasSinActCosto
• stock operativo: Stock, Stock en Bultos, Unidades_x_Bulto
• costos: CostoListaProveedor, Costo, UltCambioCosto
• precios / listas: PrecioListaNeto, PrecioListaFinal, PrecioL1 a PrecioL9, PrecioNetoL1 a PrecioNetoL9
• impuestos: AlicuotaIVA, IVAPListaFinal, IVAPrecioL1 a IVAPrecioL9
• margenes: Markup, MargenL1 a MargenL9
• descuentos de compra: Dcto Compra 1, Dcto Compra 2, Dcto Compra 3
• volumetria / logistica: UnidadMedida, PesoxUnidad, VolumenxUnidad, BasePallet, AlturaPallet, Unidades_x_Bulto, CantUnidxPallet, CantBultosxPallet, PesoxPalletkg, VolumenxPalletm3

Regla documental recomendada:

• SOURCE-002 sigue siendo la autoridad madre
• tenant_id + SKU sigue siendo la clave canonica para unir las capas futuras derivadas desde esta autoridad
• todos los dominios anteriores cuelgan del mismo tenant_id + SKU
• politica comercial, promociones, estrategia comercial, actividad comercial y volumetria / logistica no deben quedar confundidos con costo, precio base o stock
• eso no obliga a consultar toda la query completa en cada ciclo futuro
• la frecuencia futura debe variar segun el dominio del dato

Mapa conceptual relacionado:

• SOURCE-002-FUTURE-LAYER-MAPPING.md: define la separacion futura recomendada entre producto maestro, stock liviano, snapshot diario y capas economicas historizables
• SOURCE-002-ECONOMIC-LAYER.md: cierra la decision documental de modelar listas de precios como filas normalizadas por SKU + lista_codigo, en lugar de columnas fijas L1..L9 como estructura destino principal, deja documentado que CostoListaProveedor es precio de lista proveedor, que Dcto Compra 1..3 son descuentos encadenados y que Costo es el costo unitario neto final a pagar, y ya deja documentado el ejemplo real de L7 compartido por Gabi para SKU 0135 y SKU 0128

6.1 Capa especifica de volumetria / logistica

Todos los campos de volumetria / logistica cuelgan de tenant_id + SKU.

Campos incluidos:

• Unidades_x_Bulto
• Stock en Bultos
• BasePallet
• AlturaPallet
• CantBultosxPallet
• CantUnidxPallet
• PesoxUnidad
• VolumenxUnidad
• PesoxPalletkg
• VolumenxPalletm3
• UnidadMedida
• CantVtaMin
• CantVentaAgrupada

Para que sirve:

• capacidad de deposito y cubicaje
• planificacion de pallets y bultos
• compras con empaque minimo o venta agrupada
• distribucion y carga
• lectura de rentabilidad logistica

Cuando conviene historizar cambios volumetricos:

• cuando cambia UnidadMedida, Unidades_x_Bulto, peso, volumen o palletizado
• cuando cambia una regla que altera capacidad, abastecimiento o distribucion
• cuando negocio necesita explicar un cambio de rentabilidad logistica

6.2 Capa especifica de politica comercial

Todos los campos de politica comercial cuelgan de tenant_id + SKU.

Campos incluidos:

• Descuento Permitido
• PrecioCDescPermitidoFinal
• Acepta Devolucion
• CantVtaMin
• CantVentaAgrupada

Lectura correcta:

• Descuento Permitido no es descuento de compra
• PrecioCDescPermitidoFinal no es precio base ni costo; es un precio comercial calculado a partir de la politica vigente
• Acepta Devolucion expresa una condicion comercial del SKU
• CantVtaMin y CantVentaAgrupada son reglas comerciales del producto, aunque tambien impacten operacion

6.3 Promociones, estrategia y actividad comercial

Todos estos campos cuelgan de tenant_id + SKU y deben leerse como dominios funcionales propios.

• promociones: PrecioOfertaFinal
• estrategia comercial: Estrategico
• actividad comercial / historicos utiles: Fecha de Ultima Compra, UltVenta, DiasSinComprar, DiasSinVender, DiasSinActCosto

Lectura correcta:

• PrecioOfertaFinal pertenece a promociones y no debe mezclarse con PrecioListaFinal
• Estrategico expresa foco comercial y no debe leerse como estado tecnico
• fechas y dias sin movimiento sirven para recencia y actividad comercial, no para reemplazar stock, costo o precio

7. Rutina futura segura y liviana

Sin implementar nada todavia, la rutina documental recomendada es:

• alta frecuencia: consultar solo stock intradiario liviano via SOURCE-002D
• una vez por dia: conservar snapshot diario via SOURCE-002C
• por cambio o en corte de cierre: preservar costos, precios, impuestos, margenes y descuentos en una capa historica separada del maestro

Justificacion:

• stock necesita frecuencia
• identidad y logistica cambian mucho menos
• costos y precios pueden cambiar durante el dia y pierden trazabilidad si se pisan siempre dentro del maestro

8. Relacion con otras fuentes

• SOURCE-002: autoridad base vigente del maestro de productos
• SOURCE-002B: fuente complementaria futura o separada para imagenes por SKU
• SOURCE-002C: capa futura para snapshot historico diario de stock
• SOURCE-002D: capa futura para stock intradiario liviano
• SOURCE-002-FUTURE-LAYER-MAPPING: mapeo conceptual futuro de SOURCE-002 hacia capas separadas de Postgres
• SOURCE-002-ECONOMIC-LAYER: decision especifica para la capa economica futura y para la modelizacion de listas de precios

Reglas de frontera:

• SOURCE-002C no reemplaza SOURCE-002
• SOURCE-002D no reemplaza SOURCE-002
• SOURCE-002C y SOURCE-002D no deben leerse como fuente base de stock actual
• SOURCE-002C y SOURCE-002D quedan reservadas para historia diaria y/o seguimiento intradiario futuro

Regla documental adicional para territorio comercial:

• SOURCE-002 no define por si sola el territorio comercial del vendedor
• SOURCE-002 aporta SKU, marca, proveedor y categoria para cruzar contra la cartera real de clientes del vendedor
• ese cruce debe apoyarse en SOURCE-001 para clientes y ownership comercial, y en SOURCE-003 para ventas reales

9. Utilidad para el Business Observer

SOURCE-002 da base directa para:

• UC002
• UC004
• UC005
• UC006
• UC007
• UC008
• UC009

Porque ya cubre en la misma autoridad:

• identidad de producto por SKU
• marca y estado
• disponibilidad actual y bultos
• proveedor
• costos y descuentos de compra
• markup y precios finales
• margenes y precios L1..L9
• fechas operativas y dias sin movimiento
• logistica de empaque y palletizado

10. Pendientes que siguen abiertos

Queda cerrada la confirmacion humana principal:

• Gabi confirma que esta query es la autoridad vigente de SOURCE-002
• Gabi confirma que SKU NOT IN ('0124', '3857', '3998', '3793') representa la primera lista conocida de exclusiones operativas
• Gabi confirma que esos SKU pueden corresponder a operaciones internas o no tradicionales y no deben tratarse como productos comerciales normales

Siguen pendientes solamente decisiones futuras de implementacion:

• definir como un futuro script de sincronizacion externalizara la lista de exclusiones operativas de forma configurable
• confirmar si SOURCE-002C y SOURCE-002D se activaran mas adelante como snapshots historicos o stock intradiario

No queda pendiente dentro de SOURCE-002:

• proveedor
• costo
• precio propio
• IVA
• palletizado
• fechas de ultima compra / venta / cambio de costo

11. Confirmaciones de alcance

• no se ejecuto sync
• no se ejecuto conexion real
• no se tocaron VPS, Docker ni OpenClaw
• no se creo API
• no se creo servicio
• no se abrio runtime
• no se inventaron columnas
• solo se preservo y documento la autoridad vigente

12. Cobertura integral del SELECT

Verificacion documental cerrada contra la autoridad preservada:

• total de campos devueltos por el SELECT: 81
• campos directos, aliases, calculados y derivados relevados: 81
• campos de listas L1..L9 relevados: 36
• campos logisticos y de palletizado relevados: 12
• campos de fechas operativas e historicos utiles relevados: 6
• campos sin capa futura asignada: 0
• campos fuera de la relacion canonica tenant_id + SKU: 0

La matriz integral campo por campo queda consolidada en:

• docs/tenants/alpuntodeventa/business-observer/SOURCE-002-FUTURE-LAYER-MAPPING.md

Cobertura funcional explicitamente verificada:

• producto, marca, proveedor, categoria y subcategoria
• estado / vigencia
• stock y stock en bultos
• costos, descuentos de compra, listas de precios, IVA, margenes, descuentos comerciales y precio oferta
• inventario, logistica y palletizado
• fechas operativas e historicos utiles
• auditoria de extraccion como capa futura por corrida, aunque no salga como columna del SELECT

Cobertura documental SOURCE-002: 100% de campos del SELECT clasificados.