SOURCE-003 Sales Items Column Mapping

Fecha: 2026-06-10

Estado: APPROVED_FOR_CONTROLLED_PILOT / MAPPING CSV POSTGRES / PRODUCCION FINAL BLOQUEADA

portal_visible = yes

Scope: tenant

tenant_id: alpuntodeventa

Owner: Gabi / Carlos Canu

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

1. Alcance

Mapping documental entre el CSV real de SOURCE-003 / Tabla 2 V2 y la propuesta revisada de columnas PostgreSQL para source_003_sales_items.

Este documento no autoriza carga, sync, migracion ni escritura en PostgreSQL.

2. Reglas de mapping

• line_key_v4 usa solo identidad documental, Hora, CodigoCliente, SKU, Vendedor y line_sequence_v1 generado por pipeline.
• source_row_hash_v1 debe cubrir las 68 columnas reales de Tabla 2 V2.
• Los codigos numericos de negocio se guardan como text cuando funcionan como identificadores.
• Los valores calculados monetarios usan numeric para evitar perdida de precision.
• Las columnas personales/contacto/logisticas se persisten por trazabilidad, pero no deben exponerse sin control en vistas de consumo.

3. Mapping CSV -> PostgreSQL

#	Columna CSV Tabla 2	Columna PostgreSQL	Transformacion	Tipo	Nullable	Persistir	Entra en line_key	Entra en source_row_hash	Observaciones
1	Fecha	fecha	CONVERT(date, v.Fecha)	date	NO	SI	SI	SI	fecha documental de la venta
2	Hora	hora_origen_sgc	LTRIM/RTRIM(v.Hora)	text	NO	SI	SI	SI	formato observado HHMMSS
3	Vendedor	vendedor_codigo	trim de v.Vendedor	text	NO	SI	SI	SI	vendedor transaccional
4	NomVendedor	vendedor_nombre_raw	trim de v.NomVendedor	text	SI	SI	NO	SI	lectura humana
5	CodigoCliente	codigo_cliente	trim de v.CodigoCliente	text	NO	SI	SI	SI	clave comercial del cliente
6	Nombre	cliente_nombre_raw	trim de v.Nombre	text	SI	SI	NO	SI	no usar como identidad
7	Direccion_de_pedidos	direccion_de_pedidos_raw	trim de c.Direccion_de_pedidos	text	SI	SI	NO	SI	faltaba en DDL piloto actual
8	Condicion_Fiscal	condicion_fiscal_raw	trim de v.CondFiscal	text	SI	SI	NO	SI	faltaba en DDL piloto actual
9	TipoComp	tipo_comp	trim de v.TipoComp	text	NO	SI	SI	SI	tipo de comprobante
10	NroComp	nro_comp	trim de v.NroComp	text	NO	SI	SI	SI	numero de comprobante
11	TipoDocInt	tipo_doc_int	trim de v.TipoDocInt	text	NO	SI	SI	SI	tipo documento interno
12	NroIntDoc	nro_int_doc	trim de v.NroIntDoc	text	NO	SI	SI	SI	numero interno
13	Documento	documento	trim de v.Documento	text	NO	SI	SI	SI	documento comercial
14	SKU	sku	trim de v.Codigo via ap.SKU	text	NO	SI	SI	SI	producto vendido
15	Articulo	articulo_raw	trim de v.Descripcion	text	SI	SI	NO	SI	descripcion raw
16	Marcas	marca_raw	trim de v.Marcas	text	SI	SI	NO	SI	marca raw
17	Precio_Neto_Unitario	precio_unitario	calc1.PrecioUnit_Neto	numeric(19,6)	SI	SI	NO	SI	calculado por regla fiscal
18	PorcDescLinea	porc_desc_linea	cast numerico de v.PorcDescLinea	numeric(9,4)	SI	SI	NO	SI	faltaba en DDL piloto actual
19	DescNetoUnitarioXLinea	desc_neto_unitario_linea	b.Precio * PorcDescLinea/100	numeric(19,6)	SI	SI	NO	SI	faltaba en DDL piloto actual
20	IVA	iva_alicuota_pct	cast numerico de v.TaxIva	numeric(9,4)	SI	SI	NO	SI	alicuota, no importe
21	Precio_Neto_Unitario_CDescLinea	precio_neto_unitario_cdesc_linea	CASE de Tabla 2 para precio con descuento de linea	numeric(19,6)	SI	SI	NO	SI	faltaba en DDL piloto actual
22	Unidades	unidades	cast numerico de v.Unidades	numeric(19,4)	NO	SI	NO	SI	cantidad de la linea
23	SubtotalNetoItem_cDescLinea	subtotal_neto_item_cdesc_linea	SignoDoc * ABS(SubtotalNetoItem_cDescLinea_Raw)	numeric(19,4)	SI	SI	NO	SI	faltaba en DDL piloto actual
24	DescAlPie	desc_al_pie_pct	cast numerico de v.DescAlPie	numeric(9,4)	SI	SI	NO	SI	faltaba en DDL piloto actual
25	Desc_Pie_Unitario_Neto	desc_pie_unitario_neto	PrecioUnit_CDescLinea * DescAlPie/100	numeric(19,6)	SI	SI	NO	SI	faltaba en DDL piloto actual
26	Precio_Neto_Unitario_CDescPie	precio_neto_unitario_cdesc_pie	SignoDoc * ABS(PrecioUnit_CDescPie)	numeric(19,6)	SI	SI	NO	SI	base de impuestos
27	ImponibleNetoItem	imponible_neto_item	SignoDoc * ABS(PrecioUnit_CDescPie * Unidades)	numeric(19,4)	SI	SI	NO	SI	base imponible
28	PercIIBB	perc_iibb_raw	SignoDoc * ABS(b.PercIIBB)	numeric(19,4)	SI	SI	NO	SI	percepcion origen
29	AlicuotaPercIIBBCalculada	alicuota_perc_iibb_calculada_pct	cast numerico de v.AlicIIBB	numeric(9,4)	SI	SI	NO	SI	alicuota IIBB
30	PercIIBBItemUnidad	perc_iibb_item_unidad	regla IIBB unitaria de Tabla 2	numeric(19,6)	SI	SI	NO	SI	faltaba en DDL piloto actual
31	PercIIBBItemImporte	iibb_item	PercIIBBItemUnidad * Unidades, firmado	numeric(19,4)	SI	SI	NO	SI	importe IIBB item
32	IVAItemUnidad	iva_item_unidad	PrecioUnit_CDescPie * TaxIva cuando aplica	numeric(19,6)	SI	SI	NO	SI	faltaba en DDL piloto actual
33	IVATotalItems	iva_item	IVAItemUnidad * Unidades, firmado	numeric(19,4)	SI	SI	NO	SI	importe IVA item
34	Importe_Total_Item	importe_total_unitario	neto unitario con descuentos + IIBB unidad + IVA unidad	numeric(19,4)	SI	SI	NO	SI	faltaba en DDL piloto actual
35	Importe_Total_Todos_los_Items	importe_total_item	ImponibleNetoItem + IVATotalItems + PercIIBBItemImporte	numeric(19,4)	NO	SI	NO	SI	total de linea
36	Total_Desc_Neto_Linea	total_desc_neto_linea	Precio * PorcDescLinea/100 * Unidades	numeric(19,4)	SI	SI	NO	SI	antes solo consolidada en descuento_item
37	Total_Desc_Neto_Al_Pie	total_desc_neto_al_pie	Desc_Pie_Unitario_Neto * Unidades	numeric(19,4)	SI	SI	NO	SI	antes solo consolidada en descuento_item
38	Total_Desc_NP	total_desc_np	total firmado si SKU es 3793 o 3998, si no 0	numeric(19,4)	SI	SI	NO	SI	antes solo consolidada en descuento_item
39	Total_Ajustes_Saldos_CtaCte	total_ajustes_saldos_ctacte	total firmado si SKU es 4010, si no 0	numeric(19,4)	SI	SI	NO	SI	faltaba en DDL piloto actual
40	PercIva	perc_iva	cast numerico de v.PercIva	numeric(19,4)	SI	SI	NO	SI	percepcion IVA origen
41	CostoLista	costo_lista	cast numerico de p.CostoLista	numeric(19,4)	SI	SI	NO	SI	costo desde PRODUCTS
42	descCompra1	desc_compra1	cast numerico de p.descCompra1	numeric(9,4)	SI	SI	NO	SI	descuento compra
43	descCompra2	desc_compra2	cast numerico de p.descCompra2	numeric(9,4)	SI	SI	NO	SI	descuento compra
44	descCompra3	desc_compra3	cast numerico de p.descCompra3	numeric(9,4)	SI	SI	NO	SI	descuento compra
45	CMVBruto_Unidad	cmv_bruto_unidad	CostoLista * descuentos compra * factor IVA	numeric(19,4)	SI	SI	NO	SI	costo bruto unitario
46	CMVBruto_Item	cmv_bruto_item	CMVBruto_Unidad * UnidadesBrutas	numeric(19,4)	SI	SI	NO	SI	costo bruto de linea
47	Markup	markup	cast numerico de p.Markup	numeric(9,4)	SI	SI	NO	SI	politica comercial
48	MaxDctoArticulo	max_dcto_articulo	cast numerico de p.MaxDctoArticulo	numeric(9,4)	SI	SI	NO	SI	descuento maximo permitido
49	Contribucion_BalanceCtaCteFinal	contribucion_item	misma suma firmada que total de item en V2	numeric(19,4)	SI	SI	NO	SI	revisar significado antes de usar como margen
50	Indicador_TipoRegistro	indicador_tipo_registro	-1 notas de credito, 1 resto	smallint	SI	SI	NO	SI	signo funcional
51	Lista_De_Precio	lista_de_precio_raw	trim de v.Lista	text	SI	SI	NO	SI	faltaba en DDL piloto actual
52	Proveedor	proveedor_codigo_raw	trim de v.Proveedor	text	SI	SI	NO	SI	codigo proveedor
53	HojaDeRuta	hoja_ruta_raw	trim de v.HojaRuta	text	SI	SI	NO	SI	logistica
54	DireccionEntrega	direccion_entrega_raw	trim de v.Direccion	text	SI	SI	NO	SI	direccion de entrega, acceso controlado
55	LocalidadEntrega	localidad_entrega_raw	trim de v.Localidad	text	SI	SI	NO	SI	localidad de entrega
56	ProvinciaEntrega	provincia_entrega_raw	trim de v.Provincia	text	SI	SI	NO	SI	provincia de entrega
57	CodRepartidor	cod_repartidor_raw	trim de v.Repartidor	text	SI	SI	NO	SI	faltaba en DDL piloto actual
58	Repartidor	repartidor_raw	trim de v.RepNombre	text	SI	SI	NO	SI	puede contener contacto; acceso controlado
59	MotivoDevolucion	motivo_devolucion_raw	trim de v.MotivoDevolucion	text	SI	SI	NO	SI	devoluciones, rechazos y mermas
60	Peso_Total	peso_total	Unidades * p.Peso	numeric(19,6)	SI	SI	NO	SI	metrica fisica
61	Volumen_Total	volumen_total	Unidades * p.Volumen	numeric(19,6)	SI	SI	NO	SI	metrica fisica
62	Cant_Bultos_Vendidos	cant_bultos_vendidos	Unidades / NULLIF(p.Unidades_bulto, 0)	numeric(19,6)	SI	SI	NO	SI	metrica fisica
63	Zona	zona_raw	trim de v.Zona	text	SI	SI	NO	SI	zona transaccional/logistica
64	Ramo	ramo_raw	trim de v.Ramo	text	SI	SI	NO	SI	contexto comercial
65	Canal	canal_raw	trim de v.Canal	text	SI	SI	NO	SI	puede venir vacio
66	Grupo	grupo_raw	trim de v.Grupo	text	SI	SI	NO	SI	segmentacion producto
67	Rubro	rubro_raw	trim de v.Rubro	text	SI	SI	NO	SI	segmentacion producto
68	RazonSocial_Proveedor	proveedor_nombre_raw	trim de pr.RazonSocial	text	SI	SI	NO	SI	nombre proveedor

4. Columnas tecnicas generadas por pipeline

Columna PostgreSQL	Origen	Tipo	Nullable	Persistir	Entra en line_key	Entra en source_row_hash	Observaciones
id	generado por pipeline	uuid	NO	SI	NO	NO	identidad tecnica interna
tenant_id	contexto de carga	text	NO	SI	NO	NO	aislamiento tenant
line_key	generado por pipeline como line_key_v4	text	NO	SI	NO	NO	hash de identidad logica; no es valor fuente
line_sequence_v1	generado por pipeline con ROW_NUMBER()	integer	NO	SI	SI	NO	participa en line_key_v4; riesgo AMARILLO ACEPTADO
source_row_hash	generado por pipeline desde 68 columnas CSV	text	NO	SI	NO	NO	detecta cambios de valores de origen
source_system	metadata de carga	text	NO	SI	NO	NO	alias origen
source_object	metadata de carga	text	NO	SI	NO	NO	nombre logico de fuente/salida
source_query_version	metadata de carga	text	NO	SI	NO	NO	version autoridad SQL
sync_batch_id	metadata de carga	uuid	NO	SI	NO	NO	lote de sync/carga
extracted_at	metadata de carga	timestamptz	NO	SI	NO	NO	momento de extraccion
last_seen_at	metadata de reconciliacion	timestamptz	NO	SI	NO	NO	ultima observacion valida
created_at	metadata interna	timestamptz	NO	SI	NO	NO	alta interna
updated_at	metadata interna	timestamptz	NO	SI	NO	NO	actualizacion interna
record_status	metadata funcional	text	NO	SI	NO	NO	active, inactive, corrected o missing_from_source

5. Campos de line_key_v4

Campo fuente	Campo destino
Fecha	fecha
Hora	hora_origen_sgc
TipoComp	tipo_comp
NroComp	nro_comp
TipoDocInt	tipo_doc_int
NroIntDoc	nro_int_doc
Documento	documento
CodigoCliente	codigo_cliente
SKU	sku
Vendedor	vendedor_codigo
generado por pipeline	line_sequence_v1

Formula conceptual:

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 ))

6. Decision de carga

Gabi aprueba explicitamente este mapping para piloto controlado, no para produccion final.

La aprobacion acepta las 68 columnas reales de SOURCE-003 / Tabla 2 V2 para persistencia segun el mapping CSV/PostgreSQL y habilita la preparacion de una carga piloto controlada desde SOURCE-003-SNAPSHOT-001 contra PostgreSQL local.

La aprobacion no habilita sync diaria, carga masiva, produccion final, automatizacion ni exposicion operativa. Cualquier ejecucion posterior debe mantener alcance piloto, trazabilidad de snapshot, validaciones previas y rollback documentado.

7. Aprobacion humana

Estado de aprobacion: APPROVED_FOR_CONTROLLED_PILOT.

Aprobacion humana registrada:

Rol	Estado
owner negocio / datos	Gabi
aprobacion de mapping	APROBADA PARA PILOTO CONTROLADO
columnas reales aceptadas para persistencia	68/68
autorizacion para preparacion de carga piloto	SI, DESDE SOURCE-003-SNAPSHOT-001 CONTRA POSTGRESQL LOCAL
autorizacion para produccion final	NO AUTORIZADA
autorizacion para sync diaria	NO AUTORIZADA
autorizacion para carga masiva	NO AUTORIZADA

Safe points documentales:

Instancia	Control	Resultado
revision previa	git status -sb	## main...origin/main
revision previa	git rev-parse HEAD	3cd0fd6875428dd82663ffa8185fee10ba7357cc
aprobacion humana	git status -sb	## main...origin/main
aprobacion humana	git rev-parse HEAD	501cf4f643f7c1ff84d3a62c63d00a3b73160878

Resultado de validacion previa:

Control	Resultado
header real del snapshot local	68 columnas
filas de mapping CSV/PostgreSQL	68/68
orden del mapping contra snapshot	MATCH
columnas CSV faltantes en mapping	0
columnas PostgreSQL del mapping faltantes en DDL documental SQL	0
columnas reales no persistidas	0
columnas reales en source_row_hash_v1	68/68
columnas CSV en line_key_v4	10/68
columna tecnica en line_key_v4	line_sequence_v1

Columnas especialmente revisadas:

Columna CSV	Columna PostgreSQL	Persistir	source_row_hash_v1	line_key_v4	Estado
DireccionEntrega	direccion_entrega_raw	SI	SI	NO	OK
LocalidadEntrega	localidad_entrega_raw	SI	SI	NO	OK
ProvinciaEntrega	provincia_entrega_raw	SI	SI	NO	OK
CodRepartidor	cod_repartidor_raw	SI	SI	NO	OK
Repartidor	repartidor_raw	SI	SI	NO	OK
DescAlPie	desc_al_pie_pct	SI	SI	NO	OK
PorcDescLinea	porc_desc_linea	SI	SI	NO	OK
DescNetoUnitarioXLinea	desc_neto_unitario_linea	SI	SI	NO	OK
Precio_Neto_Unitario_CDescLinea	precio_neto_unitario_cdesc_linea	SI	SI	NO	OK

Condiciones aceptadas por la aprobacion:

• el diccionario completo queda aprobado para piloto controlado
• este mapping queda aprobado para piloto controlado
• source_row_hash_v1 debe canonicalizar las 68 columnas reales del CSV
• el pipeline piloto debe producir todas las columnas persistibles documentadas
• Contribucion_BalanceCtaCteFinal queda aprobada como persistible, con semantica de negocio pendiente
• Total_Credito_MERMAS queda aprobado con posibilidad futura de columna separada si se confirma necesidad
• PercIIBB queda aprobado, con lectura fina pendiente junto a PercIIBBItemImporte

Restricciones vigentes:

• no produccion final
• no sync diaria
• no carga masiva
• no VPS
• no Docker
• no OpenClaw runtime
• no APIs
• no IA
• no exposicion de datos personales/logisticos sin controles

Proximo paso habilitado:

Preparar la carga piloto controlada desde SOURCE-003-SNAPSHOT-001 contra PostgreSQL local, con validacion previa de transformaciones, conteos, conciliaciones, line_key_v4, line_sequence_v1, source_row_hash_v1 y rollback.