Saltar a contenido

SOURCE-002 Economic Layer

Fecha: 2026-06-07

Estado: DISENO DOCUMENTAL FUTURO / NO IMPLEMENTADO

Scope: tenant

tenant_id: alpuntodeventa

Owner: Gabi / Carlos Canu

Fuente de verdad: docs/tenants/alpuntodeventa/business-observer/SOURCE-002-ECONOMIC-LAYER.md

Relacion directa:

  • SOURCE-002-FUTURE-LAYER-MAPPING.md
  • sources/SOURCE-002-SGC-PRODUCTOS.md
  • source-authority/SOURCE-002-PRODUCTOS-PRODUCTS-AUTHORITY.sql

Frontera documental obligatoria:

  • este documento cubre economia, listas, impuestos, margenes y descuentos de compra
  • no absorbe politica comercial, promociones, estrategia comercial, actividad comercial ni volumetria / logistica como dominios primarios
  • esos dominios tambien cuelgan de tenant_id + SKU, pero se documentan como capas funcionales diferenciadas en SOURCE-002-FUTURE-LAYER-MAPPING.md

1. Proposito

Este documento existe para cerrar formalmente el diseno conceptual futuro de la capa economica derivada de SOURCE-002.

No implementa tablas.

No define SQL.

No define scripts.

No define APIs.

No define servicios.

No abre runtime.

Solo documenta como deberia separarse la persistencia futura de precios, costos, impuestos, margenes y descuentos observados desde el maestro de productos del SGC.

2. Decision documental principal

Decision oficial:

  • tenant_id + SKU es la clave canonica del dominio producto para toda la capa economica derivada de SOURCE-002
  • todo dato economico de SOURCE-002 debe interpretarse como atributo, medicion, relacion vigente o relacion historica del SKU
  • aplicar la regla historicos por valor de decision
  • no usar columnas fijas PrecioL1..PrecioL9 como diseno destino principal
  • no usar columnas fijas MargenL1..MargenL9, IVAPrecioL1..IVAPrecioL9 ni PrecioNetoL1..PrecioNetoL9 como forma estructural principal
  • modelar cada lista de precio como entidad repetible por producto
  • tratar L1..L9 como filas hijas normalizadas por SKU + lista_codigo
  • permitir que L10, L11 o futuras listas aparezcan sin cambio de estructura en la tabla destino principal

Esto implica documentalmente:

  • costos, descuentos de compra, precios, listas, IVA, margenes, descuento permitido y precio oferta no son dominios sueltos: son lecturas asociadas al SKU
  • proveedor y marca siguen siendo relaciones del SKU aunque parte de su analisis ocurra en capas maestras o dimensionales

Ejemplo funcional de una fila de lista:

  • lista_codigo: L7
  • margen: 0.000
  • precio_final: 2020.900
  • iva_precio: 350.735
  • precio_neto: 1670.165

3. Regla transversal: historicos por valor de decision

Regla documental oficial:

  • todo dato que sirva para indicadores, toma de decisiones, patrones, tendencias, alertas o aprendizaje futuro debe contemplar historico desde el diseno
  • el historico debe contemplarse cuando el dato permita medir evolucion, detectar patrones, explicar tendencias, generar alertas, mejorar decisiones comerciales o alimentar aprendizaje futuro
  • esto no implica guardar todo sin criterio ni sin limite
  • el objetivo es disenar historicos livianos, trazables y utiles

Aplicacion obligatoria dentro de la capa economica:

  • cambios de costo
  • cambios de precio y listas
  • cambios de IVA
  • cambios de margen y descuento
  • snapshots diarios utiles como contexto economico de cierre cuando negocio lo necesite

Criterio de diseno:

  • si un valor solo sirve para lectura operativa actual, puede vivir como vigente
  • si un valor ayuda a explicar comportamiento en el tiempo, debe contemplar una forma de historizacion por cambio, vigencia o snapshot resumido
  • la forma de historizacion futura debe elegirse por utilidad de negocio y no por reflejo tecnico

4. Motivo de la decision

La query autoridad de SOURCE-002 hoy expone listas L1..L9 como columnas porque esa es la forma practica de leer el ERP / SGC.

Eso no significa que esa misma forma sea correcta como estructura principal de persistencia futura.

La decision de normalizar nace de estas razones:

  • las listas son una coleccion repetible por SKU
  • el numero de listas puede crecer en el ERP
  • una tabla ancha fija obliga a cambios estructurales cuando aparezca una nueva lista
  • la trazabilidad por cambio se vuelve mas simple si cada lista vive como fila
  • el analisis por lista, por vigencia y por delta de valores queda mas limpio
  • el modelo se vuelve mas estable frente a cambios del origen

Regla adicional de integridad conceptual:

  • la normalizacion por SKU + lista_codigo no reemplaza la identidad canonica del producto
  • la ancla primaria sigue siendo tenant_id + SKU

5. Ejemplo real de listas normalizadas

El ejemplo real aportado por Gabi confirma que el ERP / SGC publica L1..L9 como una estructura horizontal repetible por SKU.

Para cada lista aparecen siempre los mismos cuatro campos:

  • MargenLn
  • PrecioLn
  • IVAPrecioLn
  • PrecioNetoLn

Eso confirma que L1..L9 no son nueve atributos conceptualmente distintos.

Son nueve repeticiones del mismo bloque economico para una lista de precio.

Ejemplo real L7

Tabla destino conceptual normalizada:

SKU lista_codigo margen precio_final iva_precio precio_neto
0135 L7 0.000 1825.840 316.881 1508.959
0128 L7 0.000 2098.550 364.211 1734.339

Contexto de lectura real:

  • SKU 0135 Mani Pelado Kra x110gr
  • SKU 0128 Papas Fritas Kra C.A x 105 grs

Interpretacion documental:

  • el ERP / SGC resuelve las listas como columnas por conveniencia de salida
  • la capa destino no debe copiar esa forma horizontal como estructura principal
  • la forma correcta en destino es una fila por tenant_id + sku + lista_codigo
  • si el ERP agrega L10, entra como nueva fila y no exige cambiar estructura

6. Semantica de costo de compra

Esta seccion documenta semantica de negocio.

No implementa calculo en runtime.

No crea tablas.

No define SQL.

No crea servicios ni APIs.

Campos involucrados en el costo de compra observado en SOURCE-002:

  • CostoListaProveedor
  • Dcto Compra 1
  • Dcto Compra 2
  • Dcto Compra 3
  • Costo

Definicion documental oficial:

  • CostoListaProveedor es el precio de lista cotizado por el proveedor antes de descuentos especiales
  • Dcto Compra 1, Dcto Compra 2 y Dcto Compra 3 son descuentos de compra encadenados
  • cada descuento se aplica sobre el resultado del descuento anterior y no todos sobre el precio original
  • el resultado final de la cadena de descuentos es Costo
  • Costo representa el costo unitario neto final que se le pagara al proveedor por una unidad del articulo
  • Cod Proveedor debe conservarse como identificador de negocio del proveedor asociado a ese SKU
  • Proveedor debe conservarse como nombre o razon social legible asociado a ese SKU
  • no debe usarse solo el texto de Proveedor como clave analitica

Formula conceptual:

Costo = CostoListaProveedor

* (1 - DctoCompra1)

* (1 - DctoCompra2)

* (1 - DctoCompra3)

Lectura correcta:

  • la formula expresa una semantica conceptual de negocio
  • los descuentos deben interpretarse como porcentajes encadenados
  • el valor documentado en Costo ya representa el neto final observado
  • esta seccion no redefine la autoridad SQL; solo fija como debe leerse su semantica economica

Ejemplo real aportado por Gabi

  • CostoListaProveedor = 1774.230
  • Dcto Compra 1 = 35.00%
  • Dcto Compra 2 = 5.50%
  • Dcto Compra 3 = 8.68%
  • Costo = 995.224

Interpretacion documental del ejemplo:

  • el primer descuento reduce el precio de lista proveedor
  • el segundo descuento se aplica sobre el resultado ya descontado
  • el tercer descuento vuelve a aplicarse sobre el neto anterior
  • el valor final documentado en Costo coincide con el costo unitario neto a pagar al proveedor

7. Modelo principal recomendado para listas

La capa economica futura debe tratar las listas de precio como bloque normalizado.

Grano conceptual recomendado:

  • una fila por tenant_id
  • una fila por sku
  • una fila por lista_codigo
  • una fila por rango de vigencia observado

Campos conceptuales minimos recomendados:

  • tenant_id
  • sku
  • lista_codigo
  • margen
  • precio_final
  • iva_precio
  • precio_neto
  • fecha_vigencia_desde
  • fecha_vigencia_hasta opcional
  • hash_valor o equivalente para deteccion futura de cambios
  • source_extracted_at

Campos conceptuales opcionales si luego negocio los necesita:

  • source_name
  • source_version
  • is_oferta
  • moneda
  • observaciones_de_captura

Regla estructural:

  • la clave funcional no debe depender de que existan exactamente 9 listas
  • la clave canonica del dominio producto sigue siendo tenant_id + sku
  • lista_codigo debe aceptar L1, L2, L3 y futuras variantes sin tocar estructura
  • los cambios de listas y precios deben contemplar historia por vigencia o por cambio cuando aporten valor de decision

8. JSON o vector como capa secundaria

JSON, vector o payload agregado pueden usarse en el futuro solo como:

  • cache de lectura
  • vista materializada
  • payload de auditoria

No deben usarse como fuente principal de verdad para analisis si contienen la estructura economica primaria.

La fuente principal de verdad analitica debe seguir siendo una capa normalizada y trazable.

Motivos:

  • mejor filtro por SKU, lista y vigencia
  • mejor comparabilidad temporal
  • mejor trazabilidad por cambio
  • menor dependencia de parseo para consultas analiticas
  • menor ambiguedad cuando aparezcan listas nuevas

9. Diseno conceptual de tablas futuras

Los nombres siguientes son conceptuales y no equivalen a tablas reales ya creadas.

producto_maestro_vigente

Proposito:

  • identidad estable del SKU
  • descripcion, marca, categoria, proveedor, estado y atributos relativamente lentos
  • preservacion de Marca como atributo comercial del SKU
  • preservacion de Cod Proveedor y Proveedor como relacion de negocio del SKU

No deberia cargar toda la historia economica fina.

producto_stock_actual

Proposito:

  • ultima observacion liviana de stock por SKU
  • lectura intradiaria frecuente

No deberia absorber precios, costos ni margenes.

producto_stock_snapshot_diario

Proposito:

  • fotografia diaria de cierre por SKU
  • historia comparativa de disponibilidad

Puede incluir contexto economico resumido de cierre solo como apoyo.

producto_precio_lista_vigente

Proposito:

  • ultima vigencia observada por SKU + lista_codigo
  • lectura rapida de precios de lista normalizados

Grano esperado:

  • una fila por SKU y lista_codigo

producto_precio_lista_historial

Proposito:

  • conservar cambios de lista por SKU + lista_codigo
  • habilitar comparacion temporal y auditoria de variaciones
  • sostener indicadores, patrones, tendencias, alertas y decisiones comerciales sobre evolucion de precios

Grano esperado:

  • una fila por cambio detectado o vigencia observada

producto_costo_vigente

Proposito:

  • costo vigente visible para operacion y analisis actual

producto_costo_historial

Proposito:

  • trazabilidad de cambios de costo con vigencia temporal
  • soporte para aprendizaje futuro sobre variaciones de compra, impacto y reaccion comercial

producto_impuesto_vigente

Proposito:

  • alicuota y componentes fiscales vigentes del producto

Puede convivir cerca de precios, pero conceptualmente no debe desaparecer mezclado solo dentro del precio final.

producto_margen_descuento_vigente

Proposito:

  • Markup
  • margenes por lista
  • descuentos de compra
  • descuento permitido

Puede quedar en una sola capa vigente mientras no se necesite historia fina separada.

Si esos cambios pasan a ser utiles para indicadores, patrones, alertas o decisiones, debera contemplarse tambien un historial liviano por cambio.

producto_extraccion_auditoria

Proposito:

  • trazar fecha de extraccion
  • fuente
  • version de autoridad
  • volumen
  • evidencia de corrida

10. Normalizacion de datos del ERP/SGC

La query nueva de SOURCE-002 normaliza, castea, calcula y ordena datos porque el ERP / SGC expone varios campos en formatos no ideales para analisis.

Esta normalizacion no es un lujo tecnico.

Es una capa de higiene necesaria para volver la lectura util de negocio.

Lectura documental de SOURCE-002:

  • convierte formatos poco utiles del ERP / SGC en valores analiticos
  • no solo replica campos crudos del origen

Transformaciones documentadas en la autoridad actual:

  • RTRIM
  • CAST
  • ROUND
  • calculos de IVA
  • calculos de precio neto y precio final
  • calculo de stock en bultos
  • calculo de palletizado
  • conversion de fechas
  • exclusion configurable de SKU

Lectura correcta:

  • el origen no siempre entrega tipos o formatos listos para analitica
  • algunos textos requieren trimming
  • varios numericos requieren casteo y redondeo controlado
  • IVA, netos y finales se reconstruyen con formulas derivadas
  • el stock en bultos no viene necesariamente como campo limpio
  • palletizado surge de combinaciones de base, altura, bulto, peso y volumen
  • las fechas requieren conversion a formatos legibles y comparables
  • la exclusion de ciertos SKU responde a una regla operativa conocida y no a una excepcion accidental

Regla documental:

  • la futura capa economica debe asumir que SOURCE-002 ya es una autoridad normalizada de lectura
  • eso no habilita a perder trazabilidad de las transformaciones
  • cualquier implementacion futura debera preservar evidencia de que esta capa existe porque el ERP / SGC no expone todo en forma analiticamente prolija

11. Relacion con SOURCE-002-FUTURE-LAYER-MAPPING

El mapeo futuro general define la separacion amplia entre producto, stock, historia diaria y dominios economicos.

Este documento baja una decision mas especifica:

  • la capa economica principal no debe nacer como bloque ancho con columnas fijas L1..L9
  • las listas de precios deben nacer como filas normalizadas por SKU y lista_codigo
  • la semantica de costo de compra debe leer CostoListaProveedor como precio de lista proveedor, Dcto Compra 1..3 como descuentos encadenados y Costo como costo unitario neto final
  • el ejemplo real de L7 para SKU 0135 y SKU 0128 confirma que el patron MargenLn + PrecioLn + IVAPrecioLn + PrecioNetoLn es repetible y no debe copiarse como estructura principal de destino
  • la historia de precios debe vivir por cambio o por vigencia, no solo en el maestro
  • la historia de costo, IVA, margen y descuento debe contemplarse cuando aporte valor de decision y no solo lectura vigente

12. Alcance y limites

Este documento deja explicitamente fuera de alcance:

  • creacion real de tablas
  • DDL
  • vistas reales
  • jobs
  • cron
  • scripts de sincronizacion
  • conexiones a bases reales
  • decisiones de indices
  • decisiones finales de particion

Estado correcto:

  • diseno documental y conceptual solamente

13. Cobertura economica verificada del SELECT

La verificacion documental de SOURCE-002 confirma que el SELECT autoridad devuelve 81 campos y que todo el bloque economico queda clasificado sin huecos documentales ni campos sueltos fuera de tenant_id + SKU.

Cobertura economica explicitamente cerrada:

  • costos: CostoListaProveedor, Costo, UltCambioCosto, DiasSinActCosto
  • descuentos de compra: Dcto Compra 1, Dcto Compra 2, Dcto Compra 3
  • impuestos: AlicuotaIVA, IVAPListaFinal, IVAPrecioL1..IVAPrecioL9
  • precios base: PrecioListaNeto, PrecioListaFinal
  • margenes: Markup, MargenL1..MargenL9
  • listas normalizables: PrecioL1..PrecioL9, PrecioNetoL1..PrecioNetoL9, IVAPrecioL1..IVAPrecioL9, MargenL1..MargenL9

Dominios relacionados pero deliberadamente separados de la capa economica principal:

  • politica comercial: Descuento Permitido, PrecioCDescPermitidoFinal, Acepta Devolucion, CantVtaMin, CantVentaAgrupada
  • promociones: PrecioOfertaFinal
  • estrategia comercial: Estrategico
  • actividad comercial: Fecha de Ultima Compra, UltVenta, DiasSinComprar, DiasSinVender, DiasSinActCosto
  • volumetria / logistica: Unidades_x_Bulto, Stock en Bultos, UnidadMedida, PesoxUnidad, VolumenxUnidad, BasePallet, AlturaPallet, CantBultosxPallet, CantUnidxPallet, PesoxPalletkg, VolumenxPalletm3

Regla documental ya cerrada:

  • no queda ningun campo economico del SELECT sin capa futura asignada
  • no queda ningun campo economico del SELECT sin relacion clara con tenant_id + SKU
  • la matriz integral campo por campo vive en SOURCE-002-FUTURE-LAYER-MAPPING.md

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