SOURCE-003 Sales Items Pilot Load 001¶

Fecha: 2026-06-10

Estado: CARGA PILOTO EJECUTADA / DATASET PILOTO CARGADO / ETAPA LOCAL CERRADA / 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-PILOT-LOAD-001.md

Documento padre: docs/tenants/alpuntodeventa/business-observer/design/SOURCE-003-SALES-ITEMS-PILOT-LOAD.md

1. Objetivo¶

Ejecutar una carga piloto controlada desde el snapshot congelado SOURCE-003-SNAPSHOT-001 hacia business_observer.source_003_sales_items en PostgreSQL local.

La carga uso exclusivamente el CSV congelado. No consulto SGC vivo, no ejecuto sync diaria, no automatizo procesos, no toco VPS, no toco Docker, no toco OpenClaw, no toco NPM y no habilito produccion final.

2. Safe point¶

Safe point previo:

git status -sb: ## main...origin/main
git rev-parse HEAD: 54fda17b27eb365ec2eb99a0291e4e8e690c0e20

3. Ambiente¶

Campo	Valor
motor	`PostgreSQL 15.15` local
host/puerto	`localhost:5432`
base	`gestion_de_negocios_core`
schema	`business_observer`
tabla	`business_observer.source_003_sales_items`
usuario	`postgres`
alias permitido	`postgres:postgres-alpuntodeventa-dev-env`
modo	`BUILD + VALIDATE`
rol del entorno	local piloto
aislamiento aplicado	schema `business_observer`

Conexion PostgreSQL:

Control	Resultado
`SELECT 1`	`PASS`, resultado `1`
tabla destino existe	`PASS`
filas antes de cargar	`0`
columnas fisicas antes de cargar	`52`

4. Fuente congelada¶

Campo	Valor
snapshot	`SOURCE-003-SNAPSHOT-001`
CSV	`C:\APV\openclawai\snapshots\source-003\SOURCE-003-TABLA2-V2-2026-06-09_20260610-210406-0300.csv`
sha256 esperado	`07092c284b5b636b8a31cd616ef5b4fa5d0ce499b81c767437842b1f7edfcbc3`
sha256 observado	`07092c284b5b636b8a31cd616ef5b4fa5d0ce499b81c767437842b1f7edfcbc3`
hash verificado	`PASS`
fecha del snapshot	`2026-06-09`
extraccion congelada	`2026-06-10T21:04:06-03:00`

El hash coincidio antes de transformar o cargar. Si el hash hubiera fallado, la carga se habria detenido.

5. Backup previo¶

Backup logico generado antes de modificar estructura o datos:

Campo	Valor
archivo dump	`C:\APV\backups_postgres\openclawai\source_003_sales_items_pilot_load_001\20260610-230617-gestion_de_negocios_core-pre-source-003-sales-items-pilot-load-001.dump`
archivo hash	`C:\APV\backups_postgres\openclawai\source_003_sales_items_pilot_load_001\20260610-230617-gestion_de_negocios_core-pre-source-003-sales-items-pilot-load-001.dump.sha256`
archivo TOC	`C:\APV\backups_postgres\openclawai\source_003_sales_items_pilot_load_001\20260610-230617-gestion_de_negocios_core-pre-source-003-sales-items-pilot-load-001.dump.toc.txt`
bytes	`12872973`
sha256 dump	`8bc5f6429f2efaa0d67c53e9aac2a146b42b2320792559d9b32cd684a9d738e0`
verificacion	`pg_restore --list PASS`
TOC entries	`870`

El backup no se versiona en Git.

6. Validacion pre-carga del CSV¶

Control	Resultado
filas	`1886`
headers	`68`
columnas del mapping presentes	`68/68`
orden de headers contra mapping	`MATCH`
fecha unica	`2026-06-09`
importe total	`48087486.83`
`CMV` total	`37881269.3025`
clientes unicos	`173`
vendedores unicos	`25`
`SKU` unicos	`180`
comprobantes unicos	`428`
`Hora` vacia	`0`
`Hora` formato `HHMMSS`	`1886`
errores de parseo numerico	`0`

Identidad y hashes pre-carga:

Control	Resultado
particiones `line_sequence_v1`	`1886`
`line_sequence_v1` maximo	`1`
empates en `ORDER BY` tecnico	`0` grupos / `0` filas
`line_key_v4` distintos	`1886`
duplicados `line_key_v4` calculados	`0` grupos / `0` filas
`source_row_hash_v1` nulos	`0`
`source_row_hash_v1` distintos	`1886`

7. Transformacion aplicada¶

Metadata generada:

Campo	Valor
`tenant_id`	`alpuntodeventa`
`source_system`	`snapshot:SOURCE-003-SNAPSHOT-001`
`source_object`	`SOURCE-003 / Tabla 2 V2`
`source_query_version`	`SOURCE-003-VENTAS-VNEXT-TABLA2-AUTHORITY-V2`
`sync_batch_id`	`2d2f3c4d-72b9-45e5-b113-608166daeeda`
`extracted_at`	`2026-06-10T21:04:06-03:00`
`last_seen_at`	`2026-06-10T21:04:06-03:00`
`record_status`	`active`

Reglas:

hora_origen_sgc se cargo desde Hora.
line_sequence_v1 se calculo como ROW_NUMBER() deterministico por la particion aprobada y el orden tecnico documentado.
line_key contiene line_key_v4.
line_key_v4 uso Fecha, Hora, TipoComp, NroComp, TipoDocInt, NroIntDoc, Documento, CodigoCliente, SKU, Vendedor y line_sequence_v1.
source_row_hash_v1 canonicalizo las 68 columnas reales aprobadas del CSV, sin columnas tecnicas de pipeline.
No se documentaron valores personales, logisticos o fiscales de filas.

8. Ajuste fisico previo dentro de la transaccion¶

La tabla fisica existia vacia con 52 columnas, correspondiente a la version piloto anterior. Para poder persistir las 68 columnas reales aprobadas, la misma transaccion de carga ajusto la estructura local piloto hasta 83 columnas fisicas.

Cambios de estructura ejecutados dentro de la transaccion:

Tipo	Cantidad
columnas renombradas	`3`
columnas agregadas	`31`
columnas fisicas finales	`83`
columnas de negocio mapeadas presentes	`68/68`

Renombres:

direccion_raw -> direccion_entrega_raw
localidad_raw -> localidad_entrega_raw
provincia_raw -> provincia_entrega_raw

Columnas agregadas:

condicion_fiscal_raw
direccion_de_pedidos_raw
cod_repartidor_raw
repartidor_raw
porc_desc_linea
desc_neto_unitario_linea
iva_alicuota_pct
precio_neto_unitario_cdesc_linea
subtotal_neto_item_cdesc_linea
desc_al_pie_pct
desc_pie_unitario_neto
precio_neto_unitario_cdesc_pie
perc_iibb_raw
alicuota_perc_iibb_calculada_pct
perc_iibb_item_unidad
iva_item_unidad
importe_total_unitario
total_desc_neto_linea
total_desc_neto_al_pie
total_desc_np
total_ajustes_saldos_ctacte
perc_iva
costo_lista
desc_compra1
desc_compra2
desc_compra3
cmv_bruto_unidad
markup
max_dcto_articulo
indicador_tipo_registro
lista_de_precio_raw

9. Carga¶

La carga se ejecuto en una unica transaccion:

lock local de business_observer.source_003_sales_items
verificacion de tabla vacia
ajuste fisico local piloto de columnas faltantes
INSERT ... ON CONFLICT (tenant_id, line_key) DO UPDATE
validacion post-carga dentro de la misma transaccion
COMMIT solo despues de validar

Resultado:

Control	Resultado
transaccion unica	`SI`
upsert por `(tenant_id, line_key)`	`SI`
errores unique/check/type	`NO`
rollback ejecutado	`NO`
motivo de no rollback	validaciones en verde y commit exitoso
datos quedaron cargados	`SI`

10. Validacion post-carga¶

Validacion post-commit sobre tenant_id = alpuntodeventa:

Control	Resultado
filas cargadas	`1886`
fecha minima	`2026-06-09`
fecha maxima	`2026-06-09`
distinct `line_key`	`1886`
duplicados `line_key`	`0`
importe total	`48087486.8300`
`CMV` total	`37881269.3025`
clientes unicos	`173`
vendedores unicos	`25`
`SKU` unicos	`180`
comprobantes unicos	`428`
`Hora` vacia	`0`
`record_status = active`	`1886`
`sync_batch_id` distintos	`1`
timestamps no nulos	`1886`
`source_row_hash` no nulo	`1886`
`line_sequence_v1` no nulo	`1886`
columnas fisicas finales	`83`
columnas de negocio persistidas o mapeadas	`68/68`

Conciliacion contra snapshot:

Metrica	Snapshot	PostgreSQL	Estado
filas	`1886`	`1886`	`PASS`
fecha unica	`2026-06-09`	`2026-06-09`	`PASS`
importe total	`48087486.83`	`48087486.8300`	`PASS`
`CMV` total	`37881269.3025`	`37881269.3025`	`PASS`
clientes unicos	`173`	`173`	`PASS`
vendedores unicos	`25`	`25`	`PASS`
`SKU` unicos	`180`	`180`	`PASS`
comprobantes unicos	`428`	`428`	`PASS`
`Hora` vacia	`0`	`0`	`PASS`
duplicados `line_key`	`0`	`0`	`PASS`

11. Estado final¶

Decision: CARGA PILOTO EXITOSA.

Estado final:

business_observer.source_003_sales_items queda cargada con el dataset piloto de 1886 filas de SOURCE-003-SNAPSHOT-001.
La fuente de carga fue exclusivamente el CSV congelado.
No se ejecuto rollback.
No se ejecuto sync diaria.
No se consulto SGC vivo.
No se cargo otro rango.
No se habilito produccion final.

12. Cierre de etapa local PostgreSQL¶

Decision documentada al 2026-06-11: la base gestion_de_negocios_core fue usada como entorno local piloto para Business Observer APV y queda cerrada como etapa valida de piloto acotado.

Estado final del piloto local:

El aislamiento fue por schema business_observer, no por base fisica separada.
business_observer.source_003_sales_items conserva 1886 filas reales del snapshot cerrado 2026-06-09.
Las filas provienen de SOURCE-003-SNAPSHOT-001; no se cargo otro rango.
La evidencia posterior de backup acotado a business_observer quedo VERDE con pg_restore --list PASS.
No se borraron datos.
No se movieron datos.
No se ejecuto sync.
No se crearon bases nuevas.

Recomendacion futura:

No escalar pilotos largos dentro de gestion_de_negocios_core.
Para el siguiente piloto, preparar una base local separada openclaw_business_observer_dev cuando haya aprobacion para crear bases, o evaluar formalmente un sandbox VPS.
Mantener bloqueadas sync diaria, carga masiva, produccion final y runtime hasta aprobacion explicita.

13. Confirmaciones de alcance¶

fuente = snapshot CSV: SI
sin SGC vivo para carga: SI
PostgreSQL local piloto tocado conscientemente: SI
base local usada como piloto: gestion_de_negocios_core
aislamiento por schema business_observer: SI
etapa local piloto cerrada documentalmente: SI
sin VPS: SI
sin Docker: SI
sin OpenClaw: SI
sin NPM: SI
sin sync diaria: SI
sin carga masiva: SI
sin automatizacion: SI
line_key_v4 validada: SI
source_row_hash_v1 calculado: SI
68 columnas aprobadas contempladas: SI
repo limpio antes de operar: SI

14. Proximo paso recomendado¶

Definir el entorno del siguiente piloto antes de cualquier nueva carga: preferentemente DB local separada openclaw_business_observer_dev, o sandbox VPS evaluado formalmente. No continuar pilotos largos dentro de gestion_de_negocios_core sin una decision explicita de gobierno.