Saltar a contenido

SOURCE-003 - SGC Ventas / Comprobantes calculados

Fecha: 2026-06-10

Estado: CANDIDATA VNEXT V2 / SNAPSHOT CARGADO EN PILOTO LOCAL / LINE_KEY_V4 AMARILLO ACEPTADO

Scope: tenant

tenant_id: alpuntodeventa

Owner: Gabi / Carlos Canu

Fuente de verdad: docs/tenants/alpuntodeventa/business-observer/sources/SOURCE-003-SGC-VENTAS-COMPROBANTES.md

Autoridad SQL preservada anterior: docs/tenants/alpuntodeventa/business-observer/source-authority/SOURCE-003-VENTAS-TABLA2-AUTHORITY.sql

Autoridad SQL vNext candidate preservada: docs/tenants/alpuntodeventa/business-observer/source-authority/SOURCE-003-VENTAS-VNEXT-TABLA2-AUTHORITY.sql

Autoridad SQL vNext candidate V2 preservada: docs/tenants/alpuntodeventa/business-observer/source-authority/SOURCE-003-VENTAS-VNEXT-TABLA2-AUTHORITY-V2.sql

Documentos relacionados:

  • docs/tenants/alpuntodeventa/business-observer/sources/SOURCE-003-CHANNEL-TAXONOMY.md
  • docs/tenants/alpuntodeventa/business-observer/SOURCE-INVENTORY-RESULTS-003.md
  • docs/tenants/alpuntodeventa/business-observer/design/SOURCE-003-LINE-IDENTITY-DECISION.md
  • docs/tenants/alpuntodeventa/business-observer/design/SOURCE-003-SALES-ITEMS-DDL-DESIGN.md
  • docs/tenants/alpuntodeventa/business-observer/source-authority/SOURCE-003-QUERY-DELTA-REVIEW.md
  • docs/tenants/alpuntodeventa/business-observer/SOURCE-003-SNAPSHOT-001.md

1. Proposito

Documentar la fuente funcional de ventas y comprobantes calculados que el Business Observer de APV debera usar en el futuro para leer ventas historicas, detalle por item y comportamiento documental sin implementar nada, sin crear tablas, sin crear scripts, sin tocar runtime y sin disenar SQL productivo.

Regla critica:

  • la query compartida por Gabi debe tratarse como autoridad funcional estricta
  • la logica de calculo observada en esa query es sagrada
  • no debe reemplazarse por campos crudos del ERP
  • no debe simplificarse IVA, IIBB, descuentos, CMV, notas de credito, guias, motivos ni BalanceCtaCteFinal

2. Fuente base

La evidencia funcional compartida por Gabi indica que esta fuente nace de una query calculada sobre estas bases operativas:

  • ecommerce.dbo.V_VENTAS
  • ecommerce.dbo.VCLIENTES
  • ecommerce.dbo.PRODUCTS
  • ecommerce.dbo.VPROVEEDORES

Lectura prudente:

  • SOURCE-003 no debe leerse como una tabla cruda aislada
  • SOURCE-003 debe leerse como una salida calculada y compuesta
  • la autoridad no es una tabla individual sino la logica completa de la query

Credencial de origen ya identificada:

  • alias canonico: mssql:mssql-sgc-ecommerce

3. Evidencia funcional disponible

La evidencia funcional de esta fuente incluye estas autoridades preservadas:

  • autoridad anterior: docs/tenants/alpuntodeventa/business-observer/source-authority/SOURCE-003-VENTAS-TABLA2-AUTHORITY.sql
  • autoridad vNext candidate: docs/tenants/alpuntodeventa/business-observer/source-authority/SOURCE-003-VENTAS-VNEXT-TABLA2-AUTHORITY.sql
  • autoridad vNext candidate V2: docs/tenants/alpuntodeventa/business-observer/source-authority/SOURCE-003-VENTAS-VNEXT-TABLA2-AUTHORITY-V2.sql
  • delta review V1 vs V2: docs/tenants/alpuntodeventa/business-observer/source-authority/SOURCE-003-QUERY-DELTA-REVIEW.md

Regla de preservacion:

  • la autoridad anterior no se reemplaza ni se borra
  • la query vNext previa queda preservada como V1
  • la query actual completa pegada por Gabi queda versionada aparte como V2 candidata
  • Gabi aclaro que Hora fue omitida por olvido en el pegado y que debe quedar incluida en la query definitiva

Dentro de la autoridad V2 candidata existen varios selectores de salida:

  • DECLARE @ShowTabla1 BIT = 1
  • DECLARE @ShowTabla2 BIT = 1
  • DECLARE @ShowTabla3 BIT = 0
  • DECLARE @ShowTabla4 BIT = 0
  • DECLARE @ShowTabla5 BIT = 1
  • DECLARE @ShowTabla6 BIT = 1

Confirmacion cerrada por Gabi:

  • Tabla 2 es la unica salida que interesa para sincronizacion
  • Tabla 1, Tabla 3, Tabla 4, Tabla 5 y Tabla 6 no deben sincronizarse como fuentes separadas
  • esas tablas deben tratarse como reportes derivados reconstruibles desde Tabla 2
  • la autoridad real no es V_VENTAS sola, sino la logica completa compuesta por V_VENTAS, VCLIENTES, PRODUCTS, VPROVEEDORES y calculos
  • la query completa debe quedar documentada paso a paso para futura replicacion en Python / Postgres si alguna vez hace falta

Lectura vNext obligatoria:

  • la query preservada en SOURCE-003-VENTAS-VNEXT-TABLA2-AUTHORITY.sql pasa a tratarse como
  • candidata vNext V1 para la futura sync de ventas itemizadas
  • la query preservada en SOURCE-003-VENTAS-VNEXT-TABLA2-AUTHORITY-V2.sql pasa a tratarse como candidata vNext V2 revalidada para snapshot controlado de ventas itemizadas
  • no corresponde marcarla todavia como autoridad final de runtime o de sync productiva porque falta diseno fisico ejecutable, DDL y validacion de backfill antes de operar
  • la autoridad anterior sigue preservada como referencia historica de esta evolucion documental
  • el ejemplo preservado hoy usa @FechaDesde = '2026-06-08' y @FechaHasta = '2026-06-08'
  • esa fecha es solo un ejemplo de corrida y la query queda documentada como parametrizable por @FechaDesde / @FechaHasta

Cambio funcional visible en la candidata vNext:

  • incorpora tratamiento explicito del codigo 4010 para ajustes de saldos de cuenta corriente
  • documenta CMVBruto como lectura economica principal observada en esta nueva version
  • mantiene a Tabla 2 como salida canonica candidata y a Tabla 1/3/4/5/6 como referencias ERP

Version documental recomendada para esta query:

  • SOURCE-003 vNext candidate V2 / Tabla 2 canonical sync output / 2026-06-10

Regla de no reemplazo silencioso:

  • esta iteracion no declara a SOURCE-003 vNext V2 como autoridad final cerrada
  • esta iteracion si deja asentado que la nueva query completa es la candidata actual para esa autoridad futura
  • la validacion real de inventario controlado de V1 queda documentada en SOURCE-INVENTORY-RESULTS-003.md
  • V2 fue revalidada contra SGC con Tabla 2 seleccionada explicitamente; queda habilitada solo para preparar snapshot controlado, no para carga o sync

Aclaracion obligatoria:

  • este repositorio versiona la query completa autoridad como SQL preservado
  • este documento no redefine la query
  • este documento solo deja asentado que la logica observada en esa query es la referencia funcional que debera respetarse en cualquier sync futuro

Estado de preservacion actual:

  • existe evidencia funcional fuerte
  • existe en este repo la query completa autoridad preservada como SQL
  • existe validacion real de Tabla 2 vNext V1 en ventana controlada
  • existe V2 candidata preservada y revalidada en Tabla 2 con flags explicitos
  • la referencia oficial de preservacion queda en: source-authority/SOURCE-AUTHORITY-REGISTRY.md

4. Decision documental vNext de sincronizacion

Decision documental vigente de SOURCE-003 vNext:

  • sincronizar solo Tabla 2
  • no sincronizar Tabla 1, Tabla 3, Tabla 4, Tabla 5 ni Tabla 6 como fuentes independientes
  • reconstruir Tabla 1, Tabla 3, Tabla 4, Tabla 5 y Tabla 6 como reportes derivados desde Tabla 2 cuando negocio los necesite
  • aceptar line_key_v4 en estado AMARILLO ACEPTADO para sync inicial analitico de Tabla 2, con hora_origen_sgc + line_sequence_v1
  • preservar Hora en V2 como campo obligatorio de la query definitiva, por aclaracion humana de Gabi
  • usar V2 para snapshot controlado solo si la extraccion fuerza explicitamente Tabla 2
  • la carga piloto 001 ya fue habilitada por gate posterior contra SOURCE-003-SNAPSHOT-001 y quedo ejecutada en PostgreSQL local
  • mantener bloqueadas sync diaria, carga masiva y produccion final hasta aprobacion explicita posterior

Flags obligatorios para cualquier extractor futuro de Tabla 2:

Flag Valor obligatorio
@ShowTabla1 0
@ShowTabla2 1
@ShowTabla3 0
@ShowTabla4 0
@ShowTabla5 0
@ShowTabla6 0

Regla:

  • no depender de los defaults de V2
  • no seleccionar resultsets por posicion implicita si la query se ejecuta con otros flags activos
  • para sync, Tabla 2 debe ser la unica salida emitida o la unica salida explicitamente seleccionada por el extractor

Resultado agregado de revalidacion Tabla 2 V2 explicita:

Metrica Resultado
fecha controlada 2026-06-08
resultsets con filas 1
filas Tabla 2 1262
columnas Tabla 2 68
importe total 24866892.52
CMV total 19078909.1264
clientes unicos 124
vendedores unicos 23
SKU unicos 178
Hora vacia o nula 0
formato Hora observado HHMMSS
duplicados line_key_v4 + line_sequence_v1 0

La fecha 2026-06-08 sigue sin ser snapshot estable; solo se uso para comparar contra la deriva ya documentada.

Snapshot controlado posterior:

Metrica Resultado
documento SOURCE-003-SNAPSHOT-001.md
fecha controlada 2026-06-09
archivo local snapshots/source-003/SOURCE-003-TABLA2-V2-2026-06-09_20260610-210406-0300.csv
filas Tabla 2 1886
columnas Tabla 2 68
importe total 48087486.83
CMV total 37881269.3025
clientes unicos 173
vendedores unicos 25
SKU unicos 180
comprobantes unicos 428
Hora vacia o nula 0
duplicados line_key_v4 + line_sequence_v1 0
sha256 snapshot 07092c284b5b636b8a31cd616ef5b4fa5d0ce499b81c767437842b1f7edfcbc3

Lectura:

  • 2026-06-09 queda como baseline congelada valida para un futuro piloto
  • cualquier carga posterior debe usar el snapshot como expectativa de gate, no una relectura viva no congelada de SGC
  • no se ejecuto carga, sync, migracion ni escritura en destino

Implicancia de gobierno:

  • SOURCE-003 no equivale a V_VENTAS sola
  • SOURCE-003 equivale a la logica completa preservada en la query autoridad
  • cualquier implementacion futura debe respetar joins, reglas de signo, calculos, saneos y redondeos observados en esa query

Destino conceptual futuro:

  • la base sincronizada recomendada para PostgreSQL / OpenClaw pasa a ser source_003_sales_items
  • el DDL documental futuro de esa tabla queda en design/SOURCE-003-SALES-ITEMS-DDL-DESIGN.md y su SQL documental asociado queda en design/sql/001_source_003_sales_items_design.sql
  • esa base debe nacer desde Tabla 2
  • Tabla 1, Tabla 3, Tabla 4, Tabla 5 y Tabla 6 quedan como referencias ERP y controles de conciliacion, no como fuente primaria de sync
  • la migracion piloto/documental puede prepararse con line_key_v4, pero no debe presentarse como auditoria legal perfecta de renglones ERP
  • despues de revalidar V2, la carga piloto 001 se ejecuto solo desde SOURCE-003-SNAPSHOT-001; cualquier sync diaria, carga masiva, backfill o produccion final sigue bloqueado hasta aprobar el siguiente gate

5. Por que Tabla 2 es la salida principal

Tabla 2 debe tratarse como salida principal porque, segun la evidencia compartida, es la capa donde queda expresada la composicion final por item de BalanceCtaCteFinal.

Eso la vuelve la salida correcta para el observer por estas razones:

  • expone granularidad por item, no solo resumen de cabecera
  • conserva el contexto documental necesario para distinguir facturas, notas de credito, guias y otros motivos
  • mantiene la logica calculada que negocio ya considera valida
  • evita reconstruir a posteriori calculos sensibles desde campos crudos del ERP
  • permite que UC001 a UC009 consuman una misma lectura transaccional gobernada

Adicionalmente, Tabla 2 es la unica salida prudente para sync porque:

  • preserva el mayor nivel de detalle util
  • permite reconstruir reportes agregados sin perder contexto historico
  • evita sincronizar multiples tablas ya resumidas que podrian divergir entre si
  • concentra la logica documental de facturas, guias, notas de credito y motivos de devolucion en una sola lectura gobernada

Regla madre:

si existe diferencia entre un campo crudo del ERP y el resultado de Tabla 2, la autoridad funcional para SOURCE-003 debe ser Tabla 2.

6. Grano funcional de Tabla 2

La confirmacion funcional vigente es:

  • Tabla 2 representa el registro itemizado de cada comprobante, cliente, venta y SKU

Lectura prudente del grano:

  • una fila representa una linea comercial calculada dentro de un comprobante
  • el mismo comprobante puede tener multiples SKU
  • el mismo comprobante podria repetir un mismo SKU mas de una vez
  • por eso no alcanza con asumir unicidad por tipo comprobante + numero + SKU

Recomendacion documental obligatoria para implementacion futura:

  • definir una line_key robusta
  • esa line_key debe distinguir lineas repetidas del mismo SKU dentro del mismo comprobante
  • si el origen no expone un identificador de linea visible, la replicacion futura debera documentar una clave funcional compuesta mas estable y una estrategia explicita para colisiones

Grano canonico recomendado para la futura base sincronizada:

  • fecha
  • cliente
  • comprobante
  • documento
  • SKU
  • seller_transactional
  • linea_tecnica

Traduccion operativa recomendada de ese grano:

  • tenant_id
  • fecha
  • codigo_cliente
  • tipo_comp
  • nro_comp
  • tipo_doc_int
  • nro_int_doc
  • documento
  • sku
  • seller_transactional
  • line_key o line_id tecnico si el origen lo expone o si luego debe derivarse con criterio documentado

7. Campos principales de Tabla 2

Sin fijar alias definitivos ni disenar SQL final, la salida principal debe conservar como minimo estos bloques funcionales observados:

Bloque funcional Lectura esperada
fecha de venta / fecha documental fecha base del hecho comercial
tipo y numero de comprobante identidad documental de la operacion
estado documental lectura para distinguir documentos validos, anulados u otras variantes segun la query
cliente referencia comercial del cliente vinculada a VCLIENTES
vendedor ownership comercial de la venta
canal / ramo contexto comercial transaccional observado en V_VENTAS
SKU / articulo item vendido vinculado a PRODUCTS
descripcion / marca / proveedor contexto comercial del item para cruce con producto y proveedor
cantidad / unidades volumen transaccional del item
precio e importes base valor de la linea segun la logica calculada
descuentos componente de descuento calculado por la query
IVA componente impositivo calculado por la query
IIBB componente impositivo calculado por la query
CMV componente de costo / margen segun la logica observada
notas de credito tratamiento documental y de signo segun la query
guias y motivos contexto documental que no debe perderse
BalanceCtaCteFinal salida calculada final que da sentido a Tabla 2

Regla de documentacion:

  • los nombres exactos de columnas deben seguir la query compartida por Gabi
  • este documento solo fija los bloques funcionales que no pueden perderse

Campos reales principales observados en la salida Tabla 2 preservada:

  • identidad documental: Fecha, Hora, TipoComp, NroComp, TipoDocInt, NroIntDoc, Documento
  • cliente: CodigoCliente, Nombre, Direccion_de_pedidos, Condicion_Fiscal
  • vendedor transaccional: Vendedor, NomVendedor
  • item: SKU, Articulo, Marcas
  • pricing e importes por item: Precio_Neto_Unitario, Precio_Neto_Unitario_CDescLinea, Precio_Neto_Unitario_CDescPie, SubtotalNetoItem_cDescLinea, ImponibleNetoItem, Importe_Total_Item, Importe_Total_Todos_los_Items
  • descuentos: PorcDescLinea, DescNetoUnitarioXLinea, DescAlPie, Desc_Pie_Unitario_Neto, Total_Desc_Neto_Linea, Total_Desc_Neto_Al_Pie, Total_Desc_NP
  • impuestos: IVA, PercIIBB, AlicuotaPercIIBBCalculada, PercIIBBItemUnidad, PercIIBBItemImporte, IVAItemUnidad, IVATotalItems
  • costos y margen: CostoLista, descCompra1, descCompra2, CMV_Neto_Unitario, CMV_Neto_Total_Item, Factor_de_Correccion_Compra_Articulo, Markup, MaxDctoArticulo, Contribucion_BalanceCtaCteFinal
  • clasificacion documental: Indicador_TipoRegistro, MotivoDevolucion
  • logistica y canal: Lista_De_Precio, Proveedor, RazonSocial_Proveedor, HojaDeRuta, DireccionEntrega, LocalidadEntrega, ProvinciaEntrega, CodRepartidor, Repartidor, Zona, Ramo, Canal, Grupo, Rubro
  • metricas fisicas: Unidades, Peso_Total, Volumen_Total, Cant_Bultos_Vendidos

8. Campos indispensables a preservar

Para no depender del maestro actual si cambia despues de la transaccion, la salida sincronizable de Tabla 2 debe preservar como minimo:

  • identidad documental: fecha, tipo de comprobante, numero de comprobante, documento interno, documento visible y cualquier otro identificador expuesto por la query
  • contexto comercial de la transaccion: cliente, vendedor, canal, ramo, condicion fiscal, motivos documentales y reglas de signo
  • identidad de item: SKU, descripcion y cualquier identificador de linea que exista o pueda derivarse de forma robusta
  • contexto historico del producto al momento de la venta: marca, proveedor, razon social del proveedor, costo, precio, descuentos, impuestos, peso, volumen y bultos
  • valores economicos calculados: Total_NetoSD, Venta_Total, Total_IIBB, Total_IVA, DescAlPie_Importe_Item, descuentos permitidos, CMV y BalanceCtaCteFinal
  • metricas fisicas: unidades, peso total, volumen total y cantidad de bultos vendidos

Confirmacion semantica cerrada:

  • Proveedor = codigo proveedor
  • RazonSocial_Proveedor = nombre / razon social del proveedor

Confirmacion semantica adicional al 2026-06-09:

  • SOURCE-003 expone un campo real de canal: LTRIM(RTRIM(v.Canal)) AS Canal
  • SOURCE-003 expone tambien LTRIM(RTRIM(v.Ramo)) AS Ramo
  • la taxonomia funcional parcial observada para esos campos queda documentada en: sources/SOURCE-003-CHANNEL-TAXONOMY.md

Confirmacion semantica adicional al 2026-06-10:

  • SOURCE-003 expone LTRIM(RTRIM(v.Hora)) AS Hora
  • Hora existe en ecommerce.dbo.V_VENTAS como char(6) NOT NULL
  • Hora debe documentarse en destino como hora_origen_sgc
  • es valor raw de SGC
  • formato observado esperado: HHMMSS, ejemplo 085923
  • no debe usarse como timestamp unico sin validacion
  • debe tratarse como parte candidata de identidad de linea
  • en V2, Hora queda preservada por aclaracion humana posterior al pegado de la query actual; no debe removerse de la salida definitiva de Tabla 2

9. Logica funcional observada paso a paso

La query autoridad debe poder replicarse en el futuro con una lectura mas clara si hiciera falta. A nivel documental, la secuencia observada es esta:

  1. toma una ventana por fecha y filtros opcionales
  2. arma una base cruda desde V_VENTAS
  3. enriquece esa base con cliente desde VCLIENTES
  4. enriquece el item con producto y atributos fisicos/comerciales desde PRODUCTS
  5. enriquece proveedor desde VPROVEEDORES
  6. sanea textos, numeros y formatos antes de calcular
  7. clasifica tipos de comprobante, notas de credito, guias y motivos
  8. aplica reglas de signo y tratamiento economico segun tipo de comprobante y condicion fiscal
  9. calcula importes netos, brutos, impuestos, descuentos, creditos y CMV con precision interna mayor a la salida final
  10. compone Tabla 2 a nivel itemizado
  11. deriva desde esa base los reportes agregados de Tabla 1, Tabla 3, Tabla 4, Tabla 5 y Tabla 6

Lectura operativa obligatoria:

  • la futura replicacion no debe empezar desde una tabla ya resumida
  • debe reproducir la secuencia funcional completa
  • la paridad debe medirse contra Tabla 2, no contra reportes agregados

10. Tabla 2 como salida canonica de sync

Lectura conceptual obligatoria:

  • Tabla 2 es la salida canonica futura para sincronizar ventas itemizadas hacia PostgreSQL / OpenClaw
  • la query completa sigue siendo el motor de calculo ERP
  • la sync no debe intentar usar Tabla 1/3/4/5/6 como base primaria
  • PostgreSQL debe guardar el itemizado y luego producir sus propios agregados, snapshots o materializaciones derivadas

Tabla base sugerida para esa sync futura:

  • source_003_sales_items

Campos tecnicos minimos recomendados para esa tabla futura:

  • tenant_id
  • source_system
  • source_object
  • source_query_version
  • source_row_hash
  • sync_batch_id
  • extracted_at
  • last_seen_at
  • created_at
  • updated_at

Capas de dato recomendadas dentro de esa tabla futura:

  • datos raw relevantes preservados desde Tabla 2
  • datos normalizados para consumo
  • metricas calculadas por item
  • trazabilidad completa de sync

11. Tablas auxiliares como referencia ERP

Las demas salidas de la query deben conservarse documentadas, pero con este rol:

  • Tabla 1: totales por cliente + fecha; base agregada inmediata del calculo ERP
  • Tabla 3: totales consolidados por fecha
  • Tabla 4: totales por fecha y vendedor
  • Tabla 5: totales por vendedor en el rango
  • Tabla 6: consolidado unico del rango

Reglas de uso:

  • no se sincronizan como fuente primaria
  • sirven como modelo de calculo del ERP
  • sirven como control de conciliacion contra ERP
  • sirven para validar futuros agregados que PostgreSQL derive desde source_003_sales_items
  • sirven como referencia de calculo para: totales por cliente + fecha, totales por fecha, totales por fecha y vendedor, totales por vendedor en rango y consolidado general

12. Calculos relevantes observados

Calculos economicos y fisicos que la documentacion vNext debe preservar como obligatorios:

  • neto: Total_NetoSD, Precio_Neto_Unitario, ImponibleNetoItem
  • bruto: Venta_Total, Importe_Total_Todos_los_Items, BalanceCtaCteFinal / Contribucion_BalanceCtaCteFinal
  • IVA: Total_IVA, IVAItemUnidad, IVATotalItems
  • IIBB: Total_IIBB, PercIIBBItemUnidad, PercIIBBItemImporte
  • descuentos: DescAlPie_Importe_Item, PorcDescLinea, Total_Desc_Neto_Linea, Total_Desc_Neto_Al_Pie
  • CMV: CMVNeta_Item, CMVTotal_Item, CMV_Neto_Unitario, CMV_Neto_Total_Item
  • contribucion: Contribucion_BalanceCtaCteFinal
  • creditos NP: Total_Credito_NP_3793, Total_Credito_NP_3998, Credito_NP_3793_Neto, Credito_NP_3998_Neto
  • ajustes de cuenta corriente: BalanceCtaCteFinal, BalanceCtaCteNeto, Dinero_Disponible_Segun_Balance
  • mermas: Total_Credito_MERMAS, Credito_MERMAS_Neto, Total_Credito_Mermas_Roturas_Vencidos
  • peso: Peso_Total_Item / Peso_Total
  • volumen: Volumen_Total_Item / Volumen_Total
  • bultos: Cant_Bultos_Vendidos_Item / Cant_Bultos_Vendidos

13. Tipos de comprobante, anulaciones y reglas de signo

La confirmacion funcional vigente es:

  • dentro de la query ya se contemplan tipos de comprobantes que anulan o corrigen

Por lo tanto:

  • la lectura futura no debe asumir que todo comprobante suma en positivo
  • facturas, notas de credito, guias y variantes documentales deben respetar la logica de signo observada en la query
  • la forma correcta de interpretar anulaciones, correcciones o compensaciones es la logica documental ya preservada, no una heuristica externa simplificada
  • si la implementacion futura traduce esto a Python / Postgres, debera dejar una tabla de reglas o un bloque de paridad explicito por tipo de comprobante

14. Parametros configurables futuros

Si en una sincronizacion futura hiciera falta parametrizar la lectura, los parametros documentados y permitidos deberian ser:

  • FechaDesde
  • FechaHasta
  • FiltroMarca
  • FiltroProveedor
  • FiltroVendedor
  • FiltroCliente

Lectura de gobierno:

  • estos parametros se documentan como capacidad futura
  • no autorizan a cambiar la logica sagrada de calculo
  • deben usarse como recorte de lectura o debug, no como reemplazo de reglas de negocio

Aclaracion de parametrizacion:

  • la query preservada usa una fecha de ejemplo puntual
  • esa fecha no debe leerse como restriccion estructural
  • la frontera temporal oficial de esta documentacion queda expresada por @FechaDesde / @FechaHasta

15. Estrategia futura de sincronizacion

Sin implementar nada, la estrategia futura recomendada para esta fuente es:

  1. hacer una carga historica inicial controlada
  2. tomar snapshot diario de Tabla 2 para congelar evidencia
  3. sincronizar una ventana movil inicial sugerida de 10 dias para cubrir una semana operativa aproximada mas margen
  4. recalcular siempre esa ventana usando la query compartida por Gabi con seleccion explicita de Tabla 2
  5. hacer upsert por tenant_id + line_key
  6. comparar source_row_hash para detectar cambios de valores
  7. refrescar last_seen_at cuando la linea reaparece sin cambios
  8. actualizar valores cuando cambia source_row_hash
  9. marcar missing_from_source si una linea deja de aparecer en una extraccion full o ventana controlada
  10. no hacer hard delete
  11. congelar fechas piloto desde snapshot, no desde SGC vivo
  12. conservar trazabilidad completa de la corrida

Justificacion funcional:

  • ventas y comprobantes pueden modificarse despues del primer alta
  • liquidacion de entregas, rechazos de clientes, anulaciones, refacturacion, descuentos posteriores, notas de credito, ajustes de cuenta corriente y cambios operativos de cobro/entrega pueden impactar dias recientes
  • una fecha ya cargada puede cambiar si se reextrae desde SGC vivo
  • una linea puede aparecer, cambiar valores, desaparecer de la extraccion activa, quedar anulada o recibir nota de credito o ajuste posterior
  • recalcular por ventana protege la logica sagrada sin depender de supuestos parciales

16. Estrategia futura de actualizacion y trazabilidad

Sin disenar tablas finales, esta fuente debera prever como minimo:

  • line_key_v4
  • source_row_hash_v1
  • sync_batch_id
  • extracted_at
  • last_seen_at
  • origen
  • ventana sincronizada
  • estado raw del comprobante si la salida o una extension futura de autoridad lo expone

Clave funcional vigente para sync inicial

La identidad futura aceptada para sync inicial analitico es line_key_v4 en estado AMARILLO ACEPTADO, documentada en design/SOURCE-003-LINE-IDENTITY-DECISION.md.

La clave sale de la propia granularidad de Tabla 2, combinando:

  • fecha documental
  • hora de origen SGC
  • tipo de comprobante
  • numero de comprobante
  • cliente
  • SKU
  • vendedor transaccional
  • line_sequence_v1

Regla de cuidado:

  • line_key_v4 no es identidad fisica legal perfecta del ERP
  • no debe inventarse una clave que colapse lineas distintas o mezcle notas de credito con ventas normales
  • debe contemplar explicitamente el caso de un mismo comprobante con el mismo SKU repetido mas de una vez
  • si el ERP expone en el futuro un id fisico de detalle, la identidad debera evolucionar de forma versionada

Resultado de inventario controlado inicial 2026-06-10:

  • Tabla 2 vNext ejecuto en solo lectura para la ventana 2026-06-08 a 2026-06-08
  • la candidata E fecha + tipo_comp + nro_comp + documento + sku + vendedor no duplico en 1269 filas medidas
  • no se observo un line_id estable expuesto por ecommerce.dbo.V_VENTAS
  • el IdFila observado en la autoridad es tecnico de sesion y no debe usarse como clave persistida
  • propuesta inicial previa a la revalidacion mayor:

text line_key_v1 = sha256(canonical( fecha, tipo_comp, nro_comp, tipo_doc_int, nro_int_doc, documento, codigo_cliente, sku, vendedor ))

Revalidacion mayor e investigacion de identidad de linea 2026-06-10:

  • line_key_v1 fallo unicidad en la ventana 2026-05-05 a 2026-06-09
  • no se encontro line_id_source apto en la metadata visible de ecommerce.dbo.V_VENTAS
  • las columnas candidatas ImpIntLinea, Localidad, PorcDescLinea, Repartidor y Unidades no son identificadores reales de linea
  • line_sequence_v1 queda recomendado como columna tecnica generada por pipeline, no como dato fuente
  • line_key_v2 queda preservada como evidencia previa con unicidad agregada:

text line_key_v2 = sha256(canonical( fecha, tipo_comp, nro_comp, tipo_doc_int, nro_int_doc, documento, codigo_cliente, sku, vendedor, line_sequence_v1 ))

  • line_key_v2 con line_sequence_v1 no duplico en la corrida exacta de 48973 filas
  • Hora fue confirmada como char(6) NOT NULL en V_VENTAS y agregada a Tabla 2 inmediatamente a la derecha de Fecha
  • line_key_v3 suma Hora a la clave natural sin line_sequence_v1:

text line_key_v3 = sha256(canonical( fecha, hora, tipo_comp, nro_comp, tipo_doc_int, nro_int_doc, documento, codigo_cliente, sku, vendedor ))

  • line_key_v3 fallo con 6 claves duplicadas y 12 filas involucradas
  • todos los duplicados restantes de line_key_v3 comparten la misma Hora
  • Hora ayuda a trazabilidad y debe conservarse como parte candidata de identidad, pero no alcanza sola
  • line_key_v4 queda aceptada como:

text line_key_v4 = sha256(canonical( fecha, hora_origen_sgc, tipo_comp, nro_comp, tipo_doc_int, nro_int_doc, documento, codigo_cliente, sku, vendedor, line_sequence_v1 ))

  • la conclusion es AMARILLO ACEPTADO, no VERDE, porque existen 3 grupos y 6 filas absolutamente identicas en la salida Tabla 2
  • no existe line_id_source fisico en la vista SGC disponible
  • el DDL documental debe incluir hora_origen_sgc, line_sequence_v1 y line_key_v4
  • la migracion piloto/documental puede avanzar para analitica, BI, IA y ML, pero no como auditoria legal perfecta de renglones ERP

Trazabilidad minima futura

  • source_row_hash_v1: para detectar cambios reales en lineas ya sincronizadas
  • sync_batch_id: para identificar la corrida que observo o actualizo la fila
  • extracted_at: para saber cuando se leyo la fila desde SGC
  • last_seen_at: para saber cuando una linea fue vista por ultima vez sin hard delete
  • origen: debe registrar mssql:mssql-sgc-ecommerce
  • ventana sincronizada: para dejar evidencia del rango recalculado en cada corrida
  • missing_from_source: para marcar desapariciones dentro de extracciones full o ventanas controladas

source_row_hash recomendado por inventario 2026-06-10:

  • version: source_row_hash_v1
  • campos base: fecha, hora_origen_sgc, tipo_comp, nro_comp, tipo_doc_int, nro_int_doc, documento, codigo_cliente, vendedor, sku, unidades, precio_neto_unitario, imponible_neto_item, iva, iibb, importe_total_todos_los_items, cmv_bruto_item, descuentos, canal, ramo, motivo_devolucion
  • canonicalizar textos, fechas y decimales antes de calcular el hash
  • no usar nombre de cliente, importes como identidad ni campos no deterministas de sesion como clave

17. Precision y redondeo

Decision documental obligatoria:

  • la salida sincronizada de Tabla 2 debe preservar suficiente precision para evitar diferencias futuras por redondeo

Lectura tecnica prudente:

  • la query autoridad calcula varios valores internos con mas precision y recien despues expone salidas redondeadas
  • una futura replicacion en Python / Postgres no deberia recalcular desde valores ya redondeados si eso cambia resultados
  • si hubiera que persistir una capa sincronizada, conviene preservar valores con precision suficiente para reproducir agregados sin drift acumulado

18. Tablas derivadas futuras en PostgreSQL

Tablas o lecturas derivadas conceptuales futuras recomendadas desde source_003_sales_items:

  • analytics_sales_daily
  • analytics_sales_by_seller_daily
  • analytics_sales_by_customer_daily
  • analytics_sales_by_product_daily
  • analytics_sales_by_brand_daily
  • analytics_sales_by_supplier_daily
  • analytics_sales_rejections_daily
  • analytics_cmv_margin_daily
  • analytics_sales_logistics_daily

Ejemplos conceptuales de agregacion futura desde source_003_sales_items:

  • ventas netas por dia
  • ventas brutas por dia
  • CMV por dia
  • margen o contribucion por dia
  • ventas por vendedor
  • ventas por cliente
  • ventas por SKU
  • ventas por marca y proveedor
  • bultos, peso y volumen por fecha o ruta
  • rechazos, notas de credito y mermas

19. Casos de uso consumidores

Esta fuente calculada tiene relacion directa con todos los casos de uso del observer:

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

Lectura resumida:

  • UC001 necesita ultima compra, frecuencia y comportamiento documental
  • UC002 necesita ventas por cliente, vendedor, marca y SKU
  • UC003 necesita medir antes y despues de acciones
  • UC004 necesita entender que se vendio, que se devolvio y donde hubo impacto economico
  • UC005 necesita una base temporal confiable de comprobantes
  • UC006 necesita importes calculados, descuentos, impuestos y CMV
  • UC007 necesita senales comerciales confiables y trazables
  • UC008 necesita detalle por item para leer surtido y mix
  • UC009 necesita impacto por proveedor, marca y SKU

20. Riesgos

Riesgos principales de esta fuente:

  • tocar calculos sagrados
  • elegir la tabla equivocada y no la salida calculada correcta
  • usar campos crudos en lugar de la logica de la query
  • no detectar modificaciones dentro de la ventana movil inicial de 10 dias o definir una ventana demasiado corta para la operacion real
  • duplicar lineas por una clave funcional incompleta
  • no identificar correctamente notas de credito
  • perder precision y generar diferencias futuras por redondeo
  • asumir unicidad por comprobante + SKU cuando el mismo SKU puede repetirse
  • no contar con un line_id_source fisico visible en el origen
  • depender de line_sequence_v1 cuando existen ocurrencias absolutamente identicas
  • asumir que Hora es un timestamp unico de linea; la revalidacion mostro que los duplicados restantes comparten la misma Hora
  • depender del maestro actual de PRODUCTS para reconstruir despues costo, proveedor, marca o atributos que deberian quedar congelados en la venta

Riesgo rector:

convertir SOURCE-003 en una lectura simplificada del ERP en vez de respetar la composicion calculada de Tabla 2.

21. Pendientes abiertos

Pendientes que siguen abiertos:

  • ampliar validacion de Tabla 2 V2 a una ventana movil o backfill antes de ejecutar cualquier DDL
  • usar el snapshot controlado de Tabla 2 V2 para 2026-06-09 como baseline congelada antes de cualquier nuevo intento de carga piloto
  • comparar totales de Tabla 2 contra Tabla 3, Tabla 4, Tabla 5 y Tabla 6
  • confirmar con evidencia si la ventana movil inicial de 10 dias es suficiente o debe ampliarse
  • revisar humanamente el DDL documental de source_003_sales_items
  • revisar nuevamente la migracion piloto/documental de source_003_sales_items con line_key_v4 solo despues de revalidar V2, sin produccion final
  • convertir el piloto en migracion productiva solo cuando exista ambiente destino aprobado, validacion adicional y aprobacion final
  • confirmar schema, permisos y estrategia de particionado
  • definir materialized views
  • definir performance real
  • definir permisos de consumo
  • confirmar si los filtros futuros quedan solo para debug o tambien para sync

Pendientes ya cerrados en esta iteracion:

  • Tabla 2 es la unica salida a sincronizar
  • Tabla 1, Tabla 3, Tabla 4, Tabla 5 y Tabla 6 son reportes derivados
  • la logica documental ya contempla comprobantes que corrigen o anulan segun tipo y signo
  • Tabla 2 vNext fue validada en solo lectura con datos reales para la ventana 2026-06-08
  • line_key_v1 queda preservada como clave historica fallida en ventana mayor
  • no se encontro line_id_source apto en metadata visible de V_VENTAS
  • Hora queda agregada a Tabla 2 como valor raw de SGC
  • line_key_v2 queda preservada como evidencia previa con unicidad agregada
  • line_key_v3 queda preservada como fallida porque los duplicados comparten la misma Hora
  • line_key_v4 queda aceptada con hora_origen_sgc + line_sequence_v1 y conclusion AMARILLO ACEPTADO
  • source_row_hash_v1 queda preservado con campos canonicos recomendados
  • Tabla 2 V2 queda revalidada con Hora incluida y seleccion explicita de resultset para la fecha minima controlada 2026-06-08
  • V2 queda habilitada para preparar snapshot controlado, no para carga ni sync
  • SOURCE-003-SNAPSHOT-001 queda capturado para 2026-06-09 con 1886 filas, hash global y agregados documentados
  • line_key_v4, hora_origen_sgc, line_sequence_v1, source_row_hash_v1, checks e indices quedan llevados a diseno DDL documental revisable para source_003_sales_items
  • la conciliacion minima Tabla 2 vs Tabla 1 fue ejecutada con diferencias residuales por redondeo

Documento futuro recomendado, sin implementar todavia:

  • docs/tenants/alpuntodeventa/business-observer/SOURCE-003-PYTHON-POSTGRES-REPLICATION-DESIGN.md

Objetivo esperado de ese documento futuro:

  • describir la logica original paso a paso
  • proponer una logica equivalente mas clara para Python / Postgres
  • dejar checklist de paridad contra Tabla 2

18. Relacion con otras fuentes

Relacion funcional esperada:

  • SOURCE-001 aporta maestro de clientes y ownership comercial base
  • SOURCE-002 aporta maestro de productos por SKU
  • SOURCE-003 aporta el hecho transaccional calculado de ventas y comprobantes
  • SOURCE-002C y SOURCE-002D no reemplazan esta fuente porque resuelven stock, no ventas calculadas

Regla de separacion:

  • SOURCE-003 no debe mezclarse con SOURCE-002
  • SOURCE-003 no debe reinterpretarse como una fuente de stock
  • SOURCE-003 gobierna ventas calculadas y comportamiento documental

Regla documental adicional para territorio comercial:

  • SOURCE-003 es la fuente transaccional que permite medir el territorio comercial real del vendedor
  • la pregunta por territorio del vendedor no debe responderse con Zona aislada de SOURCE-001
  • la lectura correcta debe cruzar clientes asignados y geografia desde SOURCE-001 con ventas reales desde SOURCE-003 y atributos de producto desde SOURCE-002

19. Confirmaciones de alcance

  • no se implemento codigo
  • no se crearon tablas
  • no se crearon scripts
  • no se toco runtime
  • no se toco VPS
  • se ejecuto conexion real de solo lectura contra SGC para inventario
  • no se diseno SQL productivo
  • no se modifico la query compartida por Gabi
  • la logica de la query queda documentada como autoridad funcional estricta