SOURCE-003 Sales Items DDL Design

Fecha: 2026-06-10

Estado: DISENO DOCUMENTAL / CARGA PILOTO 001 EJECUTADA / PRODUCCION FINAL BLOQUEADA

Scope: tenant

tenant_id: alpuntodeventa

Owner: Gabi / Carlos Canu

Fuente de verdad: docs/tenants/alpuntodeventa/business-observer/design/SOURCE-003-SALES-ITEMS-DDL-DESIGN.md

SQL relacionados:

• docs/tenants/alpuntodeventa/business-observer/design/sql/001_source_003_sales_items_design.sql
• docs/tenants/alpuntodeventa/business-observer/design/sql/002_source_003_sales_items_pilot_migration.sql
• docs/tenants/alpuntodeventa/business-observer/design/sql/002_source_003_sales_items_pilot_rollback.sql

Documentos relacionados:

• docs/governance/standards/DATA-DESIGN-STANDARD.md
• docs/tenants/alpuntodeventa/business-observer/design/POSTGRES-PHYSICAL-ARCHITECTURE.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-PILOT-MIGRATION.md
• docs/tenants/alpuntodeventa/business-observer/design/SOURCE-003-SALES-ITEMS-PILOT-LOAD.md
• docs/tenants/alpuntodeventa/business-observer/design/SOURCE-003-SALES-ITEMS-PILOT-LOAD-001.md
• docs/tenants/alpuntodeventa/business-observer/data-dictionary/SOURCE-003-TABLA2-COLUMN-DICTIONARY.md
• docs/tenants/alpuntodeventa/business-observer/design/SOURCE-003-SALES-ITEMS-COLUMN-MAPPING.md
• docs/tenants/alpuntodeventa/business-observer/SOURCE-003-DRIFT-ANALYSIS-001.md
• docs/tenants/alpuntodeventa/business-observer/sources/SOURCE-003-SGC-VENTAS-COMPROBANTES.md
• docs/tenants/alpuntodeventa/business-observer/source-authority/SOURCE-003-VENTAS-VNEXT-TABLA2-AUTHORITY.sql
• docs/tenants/alpuntodeventa/business-observer/source-authority/SOURCE-003-VENTAS-VNEXT-TABLA2-AUTHORITY-V2.sql
• docs/tenants/alpuntodeventa/business-observer/source-authority/SOURCE-003-QUERY-DELTA-REVIEW.md
• docs/tenants/alpuntodeventa/business-observer/BUSINESS-OBSERVER-DATA-CONTRACT-001.md

1. Proposito

Disenar documentalmente el DDL futuro de la tabla PostgreSQL source_003_sales_items, usando la evidencia validada de SOURCE-003 / Tabla 2 vNext, line_key_v4 y source_row_hash_v1.

Este documento nacio como propuesta revisable para una migracion futura. La implementacion piloto posterior quedo limitada a PostgreSQL local y documentada como excepcion controlada; no habilita produccion final.

Registro V2 2026-06-10:

• SOURCE-003-VENTAS-VNEXT-TABLA2-AUTHORITY-V2.sql queda registrada como candidata actual
• Hora debe permanecer incluida en la query definitiva por aclaracion humana de Gabi
• el delta V1 vs V2 queda clasificado como MEDIO porque V2 conserva Tabla 2, Hora, joins, filtros y calculos, pero cambia flags de salida
• este DDL no queda invalidado textualmente, pero queda pendiente de revalidacion contra Tabla 2 V2 antes de cualquier migracion, snapshot, carga o sync

La identidad line_key_v4 queda aceptada humanamente en estado AMARILLO ACEPTADO para sync inicial analitico. Esa aceptacion permite preparar una migracion piloto/documental ejecutable, pero no habilita produccion final ni auditoria legal perfecta de renglones ERP.

La version revisada del SQL piloto queda preparada documentalmente y no fue ejecutada en esta revision. Vive en design/sql/002_source_003_sales_items_pilot_migration.sql, con rollback piloto historico en design/sql/002_source_003_sales_items_pilot_rollback.sql.

Registro de diccionario completo 2026-06-10:

• el snapshot controlado SOURCE-003-SNAPSHOT-001 confirma 68 columnas reales en Tabla 2 V2
• el DDL piloto anterior contemplaba semanticamente 37 columnas y dejaba 31 columnas faltantes o solo consolidadas
• quedan creados el diccionario completo de columnas y el mapping CSV/PostgreSQL
• la persistencia futura debe preservar las 68 columnas reales de Tabla 2 V2 como columnas estructuradas o mapping directo documentado
• source_row_hash_v1 debe cubrir las 68 columnas reales canonicalizadas antes de cualquier carga
• la carga piloto quedaba bloqueada hasta aprobacion humana del diccionario y mapping; esa aprobacion fue registrada posteriormente y la carga piloto 001 quedo ejecutada desde SOURCE-003-SNAPSHOT-001

2. Limites

Este documento es modo DESIGN. La revalidacion de Hora pertenece al modo INVENTORY y queda documentada en SOURCE-INVENTORY-RESULTS-003.md.

No incluye:

• ejecucion de migraciones
• ejecucion del SQL piloto
• creacion de tablas fisicas
• queries operativas de sync contra SGC
• cambios en PostgreSQL
• cambios en runtime
• cambios en VPS
• cambios en Docker
• definicion final de schema destino
• aprobacion para carga productiva

3. Evidencia validada

La propuesta se apoya en el inventario controlado de SOURCE-003 / Tabla 2 vNext ejecutado para la ventana 2026-06-08.

Resultado: VERDE.

Metricas observadas:

Metrica	Resultado
filas	1269
clientes unicos	125
comprobantes unicos	305
SKU unicos	178
vendedores unicos	23
filas con SKU vacio	0
filas con cliente vacio	0
filas con vendedor vacio	0
filas con documento o comprobante vacio	0
filas con CMVBruto_Item nulo o cero	6

Conciliacion minima contra Tabla 1:

Comparacion	Diferencia
importe Tabla 2 vs Tabla 1	0.28
CMV Tabla 2 vs Tabla 1	0.01

Lectura:

• las diferencias son residuales y compatibles con redondeos
• Tabla 2 vNext queda como candidata canonica para ventas itemizadas
• la validacion todavia cubre una ventana chica y debe ampliarse antes de produccion

Revalidacion mayor 2026-06-10:

Metrica	Resultado
ventana	2026-05-05 a 2026-06-09
fechas con datos	30
filas Tabla 2	48976
claves line_key_v1 distintas	48970
claves line_key_v1 duplicadas	6
filas involucradas en duplicados	12
grupos con salida completa identica	3

Resultado de esa revalidacion: ROJO.

Lectura:

• line_key_v1 no sostiene unicidad para indice unico
• agregar importes, source_row_hash_v1, campos logisticos o todas las columnas expuestas no resuelve todos los duplicados
• las escalas numericas observadas quedan cubiertas por los tipos documentales actuales
• el diseno no debe convertirse en migracion ejecutable hasta definir un line_sequence_v1 estable o un identificador funcional de linea

Investigacion de identidad de linea 2026-06-10:

Metrica	Resultado
ventana	2026-05-05 a 2026-06-09
filas Tabla 2 medidas en la corrida exacta	48973
columnas candidatas de metadata V_VENTAS	5
columnas aptas como line_id_source	0
claves line_key_v2 con line_sequence_v1 distintas	48973
claves line_key_v2 duplicadas	0
grupos absolutamente identicos	3
filas en grupos absolutamente identicos	6

Resultado vigente: AMARILLO ACEPTADO.

Lectura:

• no existe line_id_source apto en la metadata visible de V_VENTAS
• line_sequence_v1 resuelve unicidad agregada, pero tiene riesgo documentado cuando dos ocurrencias son absolutamente identicas
• line_key_v1 queda preservada como historicamente fallida
• line_key_v2 queda preservada como clave con unicidad agregada previa
• la decision humana acepta el riesgo residual para sync inicial analitico
• el diseno sigue sin habilitar produccion final ni auditoria legal perfecta de renglones ERP

Revalidacion de Hora y line_key_v3 2026-06-10:

Metrica	Resultado
ventana	2026-05-05 a 2026-06-09
v.Hora en V_VENTAS	char(6) NOT NULL
filas Tabla 2 medidas	48973
columnas Tabla 2 con Hora	68
posicion Hora en salida	2
filas con Hora formato HHMMSS	48973
claves line_key_v3 distintas	48967
claves line_key_v3 duplicadas	6
filas involucradas en duplicados line_key_v3	12
duplicados line_key_v3 con misma Hora	6 grupos / 12 filas

Lectura:

• Hora debe preservarse como hora_origen_sgc
• es valor raw de SGC, con formato observado esperado HHMMSS
• ejemplo documental de formato: 085923
• no debe usarse como timestamp unico sin validacion
• line_key_v3 falla porque los duplicados restantes comparten la misma Hora
• la clave documental aceptada pasa a ser line_key_v4, combinando hora_origen_sgc con line_sequence_v1

Deriva operativa confirmada 2026-06-10:

Metrica	Historico	Observado posterior	Delta
filas Tabla 2 para 2026-06-08	1269	1262	-7
suma Importe_Total_Todos_los_Items	24852533.32	24866892.52	14359.20
suma CMVBruto_Item	19122718.36	19078909.1264	-43809.2336

Lectura de diseno:

• SOURCE-003 / SGC Ventas es una fuente viva, no un historico congelado por fecha de comprobante
• el SGC puede modificar, anular, refacturar o ajustar comprobantes aproximadamente hasta 7 dias hacia atras por entregas, rechazos, cobros, descuentos, notas de credito, cuenta corriente y cambios operativos de entrega o cobranza
• no debe usarse incremental simple basado solo en ultima fecha cargada
• la tabla futura debe tolerar que una linea aparezca, cambie valores, desaparezca de una extraccion activa, quede anulada o reciba una nota de credito/ajuste posterior
• el freeze date de pilotos y conciliaciones debe salir de snapshot, no de una relectura posterior de SGC vivo

4. Tabla propuesta

Nombre futuro:

text source_003_sales_items

Capa conceptual:

text raw/core

Grano:

text una linea calculada de Tabla 2 por tenant, documento, cliente, SKU, vendedor transaccional, hora_origen_sgc, line_sequence_v1 y line_key_v4

Clave logica documental propuesta:

text unique (tenant_id, line_key)

Estado vigente de esa clave:

text line_key debe representar line_key_v4; version revisada de migracion piloto documental preparada y no ejecutada en esta revision; produccion final pendiente

Regla central:

• id es identidad tecnica interna
• line_sequence_v1 es una columna tecnica generada por pipeline, no dato fuente
• tenant_id + line_key representa la identidad logica solo si line_key contiene line_key_v4
• line_key_v1 no alcanza como identidad logica unica con la evidencia vigente
• line_key_v3 tampoco alcanza porque Hora no distingue las colisiones observadas
• source_row_hash detecta cambios de valores de la linea
• no se usa IdFila de la autoridad SQL como clave persistida porque es tecnico de sesion
• la clave final suma hora_origen_sgc y line_sequence_v1, con riesgo residual aceptado para filas absolutamente identicas

5. Columnas principales

Identidad interna

Columna	Tipo propuesto	Nulabilidad	Uso
id	uuid	not null	identidad tecnica interna
tenant_id	text	not null	aislamiento tenant
line_key	text	not null	line_key_v4 versionada de linea
line_sequence_v1	integer	not null	secuencia tecnica generada por pipeline
source_row_hash	text	not null	preserva source_row_hash_v1 para deteccion de cambios de valores

Trazabilidad

Columna	Tipo propuesto	Nulabilidad	Uso
source_system	text	not null	alias origen, por ejemplo mssql:mssql-sgc-ecommerce
source_object	text	not null	objeto/logica origen, por ejemplo SOURCE-003 Tabla 2 vNext
source_query_version	text	not null	version de autoridad de extraccion
sync_batch_id	uuid	not null	lote de sync futuro
extracted_at	timestamptz	not null	momento de lectura desde origen
last_seen_at	timestamptz	not null	ultima observacion valida
created_at	timestamptz	not null default now()	alta tecnica interna
updated_at	timestamptz	not null default now()	actualizacion tecnica interna
record_status	text	not null	estado tecnico/funcional

Identidad documental

Columna	Tipo propuesto	Nulabilidad
fecha	date	not null
hora_origen_sgc	text	not null
tipo_comp	text	not null
nro_comp	text	not null
tipo_doc_int	text	not null
nro_int_doc	text	not null
documento	text	not null
condicion_fiscal_raw	text	null

Cliente

Columna	Tipo propuesto	Nulabilidad
codigo_cliente	text	not null
cliente_nombre_raw	text	null
direccion_de_pedidos_raw	text	null

Vendedor transaccional

Columna	Tipo propuesto	Nulabilidad
vendedor_codigo	text	not null
vendedor_nombre_raw	text	null

Producto/item

Columna	Tipo propuesto	Nulabilidad
sku	text	not null
articulo_raw	text	null
marca_raw	text	null
proveedor_codigo_raw	text	null
proveedor_nombre_raw	text	null

Canal/contexto

Columna	Tipo propuesto	Nulabilidad
estado_comprobante_raw	text	null
canal_raw	text	null
ramo_raw	text	null
grupo_raw	text	null
rubro_raw	text	null
motivo_devolucion_raw	text	null

Logistica

Columna	Tipo propuesto	Nulabilidad
hoja_ruta_raw	text	null
direccion_entrega_raw	text	null
localidad_entrega_raw	text	null
provincia_entrega_raw	text	null
cod_repartidor_raw	text	null
repartidor_raw	text	null
zona_raw	text	null

Metricas

Columna	Tipo propuesto	Nulabilidad	Criterio
unidades	numeric(19,4)	not null	cantidad de la linea
precio_unitario	numeric(19,6)	null	precio unitario con mayor escala
porc_desc_linea	numeric(9,4)	null	porcentaje de descuento de linea
desc_neto_unitario_linea	numeric(19,6)	null	descuento neto unitario de linea
iva_alicuota_pct	numeric(9,4)	null	alicuota IVA
precio_neto_unitario_cdesc_linea	numeric(19,6)	null	precio neto unitario con descuento de linea
subtotal_neto_item_cdesc_linea	numeric(19,4)	null	subtotal neto con descuento de linea
desc_al_pie_pct	numeric(9,4)	null	porcentaje de descuento al pie
desc_pie_unitario_neto	numeric(19,6)	null	descuento al pie unitario neto
precio_neto_unitario_cdesc_pie	numeric(19,6)	null	precio neto unitario con descuentos de linea y pie
imponible_neto_item	numeric(19,4)	null	imponible neto por item
perc_iibb_raw	numeric(19,4)	null	percepcion IIBB raw firmada
alicuota_perc_iibb_calculada_pct	numeric(9,4)	null	alicuota IIBB usada en calculo
perc_iibb_item_unidad	numeric(19,6)	null	IIBB unitario
iva_item	numeric(19,4)	null	componente IVA
iva_item_unidad	numeric(19,6)	null	IVA unitario
iibb_item	numeric(19,4)	null	componente IIBB
importe_total_unitario	numeric(19,4)	null	total unitario con impuestos
importe_total_item	numeric(19,4)	not null	total calculado de la linea
total_desc_neto_linea	numeric(19,4)	null	descuento neto total de linea
total_desc_neto_al_pie	numeric(19,4)	null	descuento neto total al pie
total_desc_np	numeric(19,4)	null	creditos NP por SKU especial
total_ajustes_saldos_ctacte	numeric(19,4)	null	ajustes de saldos de cuenta corriente
perc_iva	numeric(19,4)	null	percepcion IVA raw
costo_lista	numeric(19,4)	null	costo lista desde PRODUCTS
desc_compra1	numeric(9,4)	null	descuento compra 1
desc_compra2	numeric(9,4)	null	descuento compra 2
desc_compra3	numeric(9,4)	null	descuento compra 3
cmv_bruto_unidad	numeric(19,4)	null	CMV bruto unitario
cmv_bruto_item	numeric(19,4)	null	puede ser cero por evidencia real
descuento_item	numeric(19,4)	null	descuentos de linea/pie consolidados
markup	numeric(9,4)	null	markup vigente del producto
max_dcto_articulo	numeric(9,4)	null	descuento maximo permitido
contribucion_item	numeric(19,4)	null	contribucion calculada de la linea
indicador_tipo_registro	smallint	null	signo funcional por tipo de comprobante
lista_de_precio_raw	text	null	lista de precio aplicada
peso_total	numeric(19,6)	null	metrica fisica
volumen_total	numeric(19,6)	null	metrica fisica
cant_bultos_vendidos	numeric(19,6)	null	metrica fisica

6. Mapeo inicial desde Tabla 2

El mapping completo CSV/PostgreSQL vive en:

docs/tenants/alpuntodeventa/business-observer/design/SOURCE-003-SALES-ITEMS-COLUMN-MAPPING.md

Ese documento es la autoridad de mapeo campo a campo para las 68 columnas reales de Tabla 2 V2.

Resumen de decisiones:

Decision	Resultado
columnas reales detectadas	68
columnas reales a persistir	68
columnas que participan en line_key_v4	Fecha, Hora, TipoComp, NroComp, TipoDocInt, NroIntDoc, Documento, CodigoCliente, SKU, Vendedor y line_sequence_v1
columnas reales que participan en source_row_hash_v1	68/68
direccion de pedidos	direccion_de_pedidos_raw
direccion/localidad/provincia de entrega	direccion_entrega_raw, localidad_entrega_raw, provincia_entrega_raw
repartidor	cod_repartidor_raw, repartidor_raw
descuentos separados	porc_desc_linea, desc_neto_unitario_linea, desc_al_pie_pct, desc_pie_unitario_neto, total_desc_neto_linea, total_desc_neto_al_pie, total_desc_np
costos separados	costo_lista, desc_compra1, desc_compra2, desc_compra3, cmv_bruto_unidad, cmv_bruto_item

Regla:

• no aprobar carga piloto si el pipeline no produce todas las columnas persistibles del mapping
• no aprobar carga piloto si source_row_hash_v1 no canonicaliza las 68 columnas reales de Tabla 2 V2

7. Constraints y checks documentales

Constraints sugeridas para el DDL futuro:

text primary key (id) unique documental: tenant_id + line_key line_sequence_v1 >= 1 hora_origen_sgc formato HHMMSS observado record_status in ('active','inactive','corrected','missing_from_source') fecha <= current_date + interval '1 day' unidades is not null importe_total_item is not null

La restriccion unique (tenant_id, line_key) solo es valida si line_key representa line_key_v4. Queda descartada para line_key_v1 y line_key_v3.

Regla sobre hora_origen_sgc:

• corresponde a Hora raw de SGC
• formato observado esperado: HHMMSS, ejemplo 085923
• no debe interpretarse como timestamp unico sin validacion adicional
• participa en line_key_v4 como parte candidata de identidad, no como identificador suficiente por si sola

Regla sobre CMV:

• cmv_bruto_item no debe tener check > 0
• el inventario inicial observo 6 casos con CMVBruto_Item nulo o cero
• la revalidacion mayor observo 381 casos con CMVBruto_Item = 0 y 0 nulos
• la nulabilidad final de cmv_bruto_item debe confirmarse antes de migrar
• cero no implica error automatico para esta fuente

Nota de revision humana:

• el check dependiente de current_date es documental y debe revisarse antes de convertirlo en migracion; si se prefiere evitar una regla temporal dentro de CHECK, puede moverse a validacion de carga

8. Indices sugeridos

Indices documentales para la tabla futura:

Indice	Columnas	Uso
source_003_sales_items_tenant_fecha_idx	tenant_id, fecha	lecturas por ventana
source_003_sales_items_tenant_cliente_idx	tenant_id, codigo_cliente	ventas por cliente
source_003_sales_items_tenant_vendedor_fecha_idx	tenant_id, vendedor_codigo, fecha	atribucion transaccional
source_003_sales_items_tenant_sku_fecha_idx	tenant_id, sku, fecha	ventas por producto
source_003_sales_items_tenant_documento_idx	tenant_id, tipo_comp, nro_comp	busqueda documental
source_003_sales_items_tenant_batch_idx	tenant_id, sync_batch_id	auditoria por batch
source_003_sales_items_tenant_status_idx	tenant_id, record_status	conciliacion de estado
source_003_sales_items_tenant_hash_idx	tenant_id, source_row_hash	deteccion e inspeccion de cambios con source_row_hash_v1

9. line_key_v1 historica fallida

Formula conceptual:

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

Campos incluidos:

• fecha
• tipo_comp
• nro_comp
• tipo_doc_int
• nro_int_doc
• documento
• codigo_cliente
• sku
• vendedor_codigo

Por que no usa importes:

• los importes, impuestos, descuentos y costos son valores de la linea
• si cambian, debe cambiar source_row_hash, no la identidad de la linea
• incluir importes en la clave convertiria una correccion en una fila nueva

Por que no usa nombre de cliente:

• el nombre puede cambiar por normalizacion, correccion administrativa o diferencia textual
• no es una identidad funcional fuerte
• puede contener texto personal/comercial que no debe participar en la clave
• la identidad de cliente debe apoyarse en codigo_cliente

Limitacion:

• line_key_v1 paso en la ventana chica 2026-06-08
• line_key_v1 fallo unicidad en la ventana mayor 2026-05-05 a 2026-06-09
• se observaron 6 claves duplicadas y 12 filas involucradas
• 3 grupos duplicados son identicos incluso considerando toda la salida de Tabla 2
• debe usarse line_key_v4 con hora_origen_sgc + line_sequence_v1 o un futuro line_id_source real antes de crear el indice unico

10. line_sequence_v1, Hora y line_key_v4

No se encontro line_id_source apto en ecommerce.dbo.V_VENTAS.

Columnas candidatas revisadas:

Columna	Conclusion
ImpIntLinea	no apta; un unico valor observado en la salida evaluada
Localidad	no apta; cabecera/logistica
PorcDescLinea	no apta; metrica mutable de descuento
Repartidor	no apta; cabecera/logistica
Unidades	no apta; metrica mutable, solo reduce parcialmente duplicados

line_sequence_v1 debe generarse en el pipeline con ROW_NUMBER():

text ROW_NUMBER() OVER ( PARTITION BY fecha, tipo_comp, nro_comp, tipo_doc_int, nro_int_doc, documento, codigo_cliente, sku, vendedor_codigo ORDER BY articulo_raw, marca_raw, proveedor_codigo_raw, unidades, precio_unitario, porc_desc_linea, desc_neto_unitario_linea, precio_neto_unitario_cdesc_linea, desc_al_pie_pct, desc_pie_unitario_neto, precio_neto_unitario_cdesc_pie, imponible_neto_item, iva_item, iva_item_unidad, iibb_item, perc_iibb_item_unidad, importe_total_item, importe_total_unitario, cmv_bruto_unidad, cmv_bruto_item, total_desc_neto_linea, total_desc_neto_al_pie, total_desc_np, total_ajustes_saldos_ctacte, contribucion_item, motivo_devolucion_raw, canal_raw, ramo_raw, hoja_ruta_raw, peso_total, volumen_total, cant_bultos_vendidos )

Reglas:

• line_sequence_v1 no viene del origen; es tecnica de pipeline
• no usar IdFila de la autoridad SQL
• no usar nombre de cliente ni direccion como criterio de orden
• versionar la regla como line_sequence_v1
• si una ocurrencia cambia en un grupo absolutamente identico, la asociacion historica queda en riesgo porque no existe id fisico de linea

Hora fue agregada a la salida Tabla 2 como hora_origen_sgc. line_key_v3, que suma Hora a la clave natural sin line_sequence_v1, fue revalidada y fallo con 6 claves duplicadas y 12 filas involucradas. Los duplicados restantes tienen la misma Hora, por lo que el campo ayuda a trazabilidad pero no alcanza solo para unicidad.

Formula conceptual previa preservada:

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

Validacion agregada de line_key_v2:

Metrica	Resultado
filas evaluadas	48973
claves line_key_v2 distintas	48973
claves line_key_v2 duplicadas	0
grupos absolutamente identicos	3
filas en grupos absolutamente identicos	6

Formula conceptual vigente:

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_codigo, line_sequence_v1 ))

Conclusion: AMARILLO ACEPTADO.

line_key_v4 conserva la unicidad agregada de line_key_v2, suma la hora raw del origen y mantiene el mismo riesgo residual: filas completamente identicas son diferenciadas por line_sequence_v1, no por identidad fisica ERP. Ese riesgo queda aceptado para sync inicial analitico, no para auditoria legal perfecta.

11. source_row_hash_v1

Formula conceptual:

text source_row_hash_v1 = sha256(canonical( 68 columnas reales de Tabla 2 V2, en el orden y con las transformaciones documentadas en SOURCE-003-SALES-ITEMS-COLUMN-MAPPING.md ))

Campos incluidos:

• identidad documental y hora raw de origen SGC
• cliente, direccion de pedidos, vendedor, producto y proveedor
• canal/contexto, grupo, rubro, ramo, zona y motivo de devolucion
• logistica, entrega y reparto
• unidades, precios, descuentos de linea, descuentos al pie y creditos NP
• imponibles, IVA, IIBB, percepciones, importes totales y signo
• costos, descuentos de compra, CMV, markup, descuento maximo y contribucion
• peso, volumen y bultos

Objetivo:

• detectar cambios reales de valores de la linea
• evitar comparar campo por campo en cada sync
• auditar recalculos de ventanas moviles
• distinguir una linea sin cambios de una linea corregida

Diferencia entre line_key y source_row_hash:

Campo	Rol
line_key	componente de identidad; debe generarse como line_key_v4
source_row_hash	detecta si cambiaron los valores de esa linea

Lectura operativa:

• si cambia source_row_hash, la fila sigue siendo la misma linea pero con valores actualizados
• si cambia line_key, el proceso futuro debe tratarlo como identidad nueva o revisar una posible colision/definicion incompleta

Canonicalizacion minima:

• fechas en ISO YYYY-MM-DD
• textos con trim
• nulos con sentinel estable
• decimales con escala definida antes de serializar
• serializacion estructurada o separador escapado para evitar colisiones
• version explicita v1

12. Estrategia de carga futura

La carga futura debe ser por batch, trazable por fila y compatible con una fuente viva. No debe depender solo de ultima fecha cargada, porque una fecha ya cargada puede cambiar al volver a leer SGC.

Reglas:

• ejecutar una carga historica inicial controlada antes de la sync diaria
• tomar snapshot diario de la salida Tabla 2 para congelar evidencia de conciliacion
• reprocesar una ventana movil inicial sugerida de 10 dias para cubrir una semana operativa aproximada mas margen
• cada carga pertenece a un sync_batch_id
• hacer upsert por tenant_id + line_key, siempre que line_key sea line_key_v4
• si no existe la clave, insertar la fila con record_status = active
• si existe y source_row_hash cambio, actualizar valores, source_row_hash, sync_batch_id, extracted_at, last_seen_at y updated_at
• si existe y source_row_hash no cambio, actualizar last_seen_at, sync_batch_id y extracted_at
• si una extraccion full valida o una extraccion de ventana controlada no vuelve a observar una linea que deberia estar dentro de la ventana, marcar record_status = missing_from_source
• no hacer hard delete
• el freeze date de una fecha piloto debe salir del snapshot tomado, no de SGC vivo
• preservar estado_comprobante_raw si la salida o una extension futura de autoridad lo expone
• preservar cambios relevantes en auditoria futura si se implementa source_003_sales_item_audit

Lectura para ventanas moviles:

• recalcular la ventana definida desde la autoridad Tabla 2
• comparar contra source_003_sales_items
• una linea puede aparecer, cambiar valores, desaparecer, quedar anulada o recibir nota de credito/ajuste posterior dentro de la ventana
• no reemplazar calculos por campos crudos del ERP
• no depender de Tabla 1/3/4/5/6 como fuente primaria

13. Checks pre-migracion

Antes de convertir este diseno en migracion ejecutable, se debe confirmar:

• revalidar Tabla 2 V2 contra la nueva autoridad candidata preservada
• riesgo AMARILLO ACEPTADO de line_sequence_v1 preservado y mitigado
• si negocio/ERP puede exponer un identificador fisico de detalle
• revalidar line_key_v4 en backfill o ventana mayor adicional
• confirmar tipos reales y escalas numericas contra salida Tabla 2
• confirmar nombres exactos de columnas de Tabla 2
• aprobar humanamente el diccionario completo de 68 columnas de Tabla 2 V2
• aprobar humanamente el mapping CSV/PostgreSQL de 68 columnas reales
• confirmar que source_row_hash_v1 canonicaliza las 68 columnas reales
• confirmar si hace falta source_003_sales_documents
• confirmar permisos y schema destino
• confirmar estrategia de particionado por fecha
• confirmar si el check de fecha futura vive como CHECK o como validacion de carga
• confirmar generacion de uuid y extension disponible en PostgreSQL destino
• confirmar auditoria futura para cambios de source_row_hash
• confirmar politica final para estado_comprobante_raw si la autoridad de extraccion lo expone

14. Pendientes

Pendientes antes de produccion:

• revision humana del documento, del SQL documental y del SQL piloto
• revision humana del diccionario y mapping antes de cualquier carga piloto
• ejecucion piloto aprobada con backup y validacion post
• ambiente destino PostgreSQL
• schema destino
• migracion productiva final
• carga inicial
• validacion de backfill
• performance real
• permisos de consumo
• estrategia final de particionado

15. Confirmaciones de alcance

• modo DESIGN aplicado
• sin runtime
• con revalidacion de inventario de solo lectura documentada
• sin queries operativas de sync
• sin tablas fisicas
• sin migraciones ejecutadas en esta revision
• sin VPS
• sin Docker
• DDL documental creado
• version revisada de migracion piloto/documental preparada y no ejecutada
• rollback piloto preparado
• line_key_v1 preservada como fallida historicamente
• line_key_v2 preservada como evidencia previa con unicidad agregada
• line_key_v3 preservada como fallida al sumar Hora sin secuencia
• line_key_v4 aceptada como clave documental para sync inicial analitico
• hora_origen_sgc incluida como valor raw de SGC
• line_sequence_v1 incluida como columna tecnica generada por pipeline
• source_row_hash_v1 incluida
• source_row_hash_v1 ampliada documentalmente a las 68 columnas reales de Tabla 2 V2
• columnas de entrega/repartidor y descuentos separados incluidas
• carga piloto 001 ejecutada desde SOURCE-003-SNAPSHOT-001 despues de aprobar diccionario y mapping
• fuente viva, ventana movil inicial de 10 dias y no hard delete documentados
• checks e indices sugeridos documentados
• produccion final bloqueada hasta validacion adicional y aprobacion explicita

16. Proximo paso recomendado

Revisar humanamente la evidencia de la carga piloto 001 y decidir si se habilita un siguiente piloto de ventana movil/backfill antes de cualquier sync diaria, carga masiva o produccion final.