Saltar a contenido

SOURCE-003 Sales Items Pilot Migration

Fecha: 2026-06-10

Estado: PILOTO HISTORICO EJECUTADO / CARGA PILOTO 001 POSTERIOR CARGADA

Scope: tenant

tenant_id: alpuntodeventa

Owner: Gabi / Carlos Canu

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

SQL piloto: docs/tenants/alpuntodeventa/business-observer/design/sql/002_source_003_sales_items_pilot_migration.sql

Nota 2026-06-10:

  • la ejecucion historica validada corresponde a la version piloto previa del SQL
  • el SQL piloto fue revisado documentalmente para contemplar las 68 columnas reales de Tabla 2 V2
  • esa version revisada no fue ejecutada
  • este documento no autoriza tocar PostgreSQL

Nota posterior:

  • la carga piloto 001 de SOURCE-003-SNAPSHOT-001 ajusto la tabla local vacia dentro de una transaccion de carga, pasando de 52 a 83 columnas fisicas para cubrir 68/68 columnas de negocio aprobadas
  • quedaron 1886 filas cargadas y conciliadas en business_observer.source_003_sales_items
  • evidencia: docs/tenants/alpuntodeventa/business-observer/design/SOURCE-003-SALES-ITEMS-PILOT-LOAD-001.md
  • produccion final sigue bloqueada

Rollback piloto: docs/tenants/alpuntodeventa/business-observer/design/sql/002_source_003_sales_items_pilot_rollback.sql

Documentos relacionados:

  • docs/tenants/alpuntodeventa/business-observer/design/SOURCE-003-SALES-ITEMS-DDL-DESIGN.md
  • docs/tenants/alpuntodeventa/business-observer/design/SOURCE-003-LINE-IDENTITY-DECISION.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/design/POSTGRES-PHYSICAL-ARCHITECTURE.md
  • docs/tenants/alpuntodeventa/business-observer/SOURCE-INVENTORY-RESULTS-003.md
  • docs/tenants/alpuntodeventa/business-observer/BUSINESS-OBSERVER-DATA-CONTRACT-001.md
  • docs/governance/standards/DATA-DESIGN-STANDARD.md

1. Objetivo

Ejecutar y documentar una migracion piloto controlada para source_003_sales_items, basada en el DDL documental vigente y en line_key_v4.

El objetivo fue dar vida al primer componente fisico real del Business Observer sin convertirlo en produccion final, sin carga masiva y sin automatizacion.

2. Alcance piloto

Incluye:

  • schema sugerido business_observer
  • tabla piloto business_observer.source_003_sales_items
  • columnas del DDL documental vigente
  • hora_origen_sgc
  • line_sequence_v1
  • line_key como line_key_v4
  • source_row_hash
  • sync_batch_id
  • extracted_at
  • last_seen_at
  • created_at
  • updated_at
  • record_status
  • constraints minimas
  • indices documentales de lectura y sync
  • rollback piloto separado

No incluye:

  • carga inicial
  • cambios en runtime
  • cambios en VPS
  • cambios en Docker
  • produccion final
  • auditoria legal perfecta de renglones ERP

3. Gate previo aplicado

Gate aplicado el 2026-06-10:

  • aprobacion humana explicita recibida en la sesion Codex
  • ambiente destino: PostgreSQL 15.15 local
  • host/puerto: localhost:5432
  • base destino: gestion_de_negocios_core
  • usuario de ejecucion: postgres
  • alias canonico usado: postgres:postgres-alpuntodeventa-dev-env
  • tenant interno de conexion: 471050d2-62b6-41a0-ae67-83e715d0886c
  • schema destino: business_observer
  • tabla destino: business_observer.source_003_sales_items
  • tabla inexistente antes de ejecutar: SI
  • permiso de creacion en base: SI
  • alcance confirmado: piloto controlado, no produccion final
  • rollback leido y verificado antes del insert piloto: SI

4. Backup requerido

Antes de la ejecucion se genero backup logico verificable del destino.

Backup aplicado:

  • comando: pg_dump --format=custom --verbose --no-owner --no-privileges --file <backup_file> --host localhost --port 5432 --username postgres --dbname gestion_de_negocios_core
  • archivo: C:\APV\backups_postgres\openclawai\source_003_sales_items_pilot\20260610-162554-gestion_de_negocios_core-pre-source-003-sales-items-pilot.dump
  • archivo hash: C:\APV\backups_postgres\openclawai\source_003_sales_items_pilot\20260610-162554-gestion_de_negocios_core-pre-source-003-sales-items-pilot.dump.sha256
  • tamano: 12861057 bytes
  • sha256: 9604ddd95038d6c3695705ccb1e0e97ab580b4482cf6784a2b6d85cbb9448125
  • verificacion: pg_restore --list leyo el dump correctamente
  • TOC Entries: 854
  • dump creado con pg_dump 15.15 desde PostgreSQL 15.15

El backup no se guardo en Git.

5. Ejecucion piloto

Comando ejecutado:

text psql --set ON_ERROR_STOP=1 --single-transaction --host localhost --port 5432 --username postgres --dbname gestion_de_negocios_core --file C:\APV\openclawai\docs\tenants\alpuntodeventa\business-observer\design\sql\002_source_003_sales_items_pilot_migration.sql

Resultado:

  • return code: 0
  • salida: CREATE SCHEMA, CREATE TABLE, 8 x CREATE INDEX, 7 x COMMENT
  • SQL modificado antes de ejecutar: NO
  • transaccion unica: SI
  • rollback ejecutado: NO
  • motivo de no ejecutar rollback: migracion y validaciones en verde

6. Rollback

Rollback preparado:

docs/tenants/alpuntodeventa/business-observer/design/sql/002_source_003_sales_items_pilot_rollback.sql

El rollback:

  • elimina indices si existen
  • elimina la tabla piloto si existe
  • no elimina el schema business_observer
  • no debe usarse contra produccion final
  • requiere aprobacion humana, backup y validacion posterior

Verificacion del archivo:

  • archivo existe: SI
  • elimina los 8 indices piloto si existen: SI
  • elimina business_observer.source_003_sales_items si existe: SI
  • no elimina el schema business_observer: SI

7. Validaciones post-migracion ejecutadas

Validaciones ejecutadas el 2026-06-10:

  • tabla creada
  • constraints creadas
  • indices creados
  • insert de prueba controlado
  • unique tenant_id + line_key funcionando
  • conteo esperado
  • checks de record_status
  • rollback disponible, no ejecutado

Resultado estructural:

Control Resultado
schema business_observer PASS
tabla business_observer.source_003_sales_items PASS
columnas totales 52
columnas principales PASS
PK source_003_sales_items_pk PASS
unique source_003_sales_items_tenant_line_key_uk PASS
indices documentales esperados PASS
checks esperados PASS
comentarios de tabla/columnas PASS
filas iniciales 0

Indices verificados:

  • source_003_sales_items_tenant_fecha_idx
  • source_003_sales_items_tenant_cliente_idx
  • source_003_sales_items_tenant_vendedor_fecha_idx
  • source_003_sales_items_tenant_sku_fecha_idx
  • source_003_sales_items_tenant_documento_idx
  • source_003_sales_items_tenant_batch_idx
  • source_003_sales_items_tenant_status_idx
  • source_003_sales_items_tenant_hash_idx

8. Insert piloto minimo

Insert sintetico controlado ejecutado: SI.

Alcance:

  • filas sinteticas insertadas: 2
  • source_system: synthetic:codex-pilot
  • sync_batch_id: 74ea3e37-bc62-4c15-a543-b8992d7ea9c5
  • datos personales reales: NO
  • filas sinteticas borradas: 2
  • filas finales en tabla: 0

Validaciones del insert:

Control Resultado
record_status = active PASS
created_at / updated_at con default PASS
unique (tenant_id, line_key) PASS, rechazo 23505
check record_status PASS, rechazo 23514
check hora_origen_sgc formato HHMMSS PASS, rechazo 23514
check line_sequence_v1 >= 1 PASS, rechazo 23514

Incidencia no migratoria:

  • el primer script local de insert piloto intento enviar objetos UUID de Python directamente y fallo con can't adapt type 'UUID'
  • la transaccion fue revertida
  • no quedaron filas insertadas por ese intento
  • el insert se reejecuto enviando UUID como texto y quedo validado

9. Riesgos

Riesgos preservados:

  • line_key_v4 no es identidad fisica nativa del ERP
  • no existe line_id_source disponible en la vista SGC accesible
  • line_sequence_v1 diferencia ocurrencias duplicadas, pero no prueba identidad fisica de linea
  • si una ocurrencia absolutamente identica cambia en el futuro, la asociacion historica podria quedar en revision
  • el schema business_observer es sugerido y no decision productiva final
  • no hay performance real medida sobre volumen completo en PostgreSQL
  • no hay estrategia final de particionado por fecha
  • no hay auditoria fisica source_003_sales_item_audit
  • no hay permisos productivos ni RLS definidos para consumo

10. Por que line_key_v4 esta en AMARILLO ACEPTADO

line_key_v4 queda en AMARILLO ACEPTADO porque es la mejor identidad documental disponible para el sync inicial analitico, pero no cierra identidad fisica perfecta del ERP.

Hechos preservados:

  • line_key_v1 fallo unicidad en ventana mayor
  • line_key_v3 tambien fallo porque los duplicados compartian la misma Hora
  • line_key_v2 paso unicidad agregada al incluir line_sequence_v1
  • line_key_v4 suma hora_origen_sgc y conserva line_sequence_v1
  • no existe id fisico de renglon expuesto por V_VENTAS
  • line_sequence_v1 es tecnica de pipeline con ROW_NUMBER()
  • el riesgo residual fue aceptado humanamente para analytics, BI, IA y ML

Por eso la decision habilita preparar piloto, no produccion final ni auditoria legal perfecta.

11. Que falta para produccion final

Falta antes de produccion:

  • schema destino final
  • revalidacion de line_key_v4 en backfill o ventana mayor adicional
  • confirmacion final de tipos y escalas numericas
  • confirmacion de permisos, roles y RLS
  • definicion de particionado o decision explicita de no particionar
  • pipeline de carga con line_sequence_v1, line_key_v4 y source_row_hash_v1
  • estrategia de auditoria de cambios por source_row_hash
  • pruebas de performance con volumen real
  • decision de rollback real en ambiente descartable o ventana aprobada
  • promocion productiva explicitamente aprobada

12. Confirmaciones de alcance

  • modo BUILD + VALIDATE aplicado
  • runtime de aplicacion no tocado
  • sin VPS
  • sin Docker
  • sin OpenClaw
  • sin NPM
  • sin automatizacion
  • sin sync diaria
  • sin carga masiva
  • sin produccion final
  • PostgreSQL piloto tocado conscientemente
  • tabla piloto real creada
  • tabla piloto vacia al cierre
  • migracion piloto ejecutada
  • migracion piloto validada
  • rollback preparado
  • rollback no ejecutado
  • line_key_v4 incluida
  • AMARILLO ACEPTADO preservado
  • produccion final bloqueada hasta aprobacion explicita

13. Intento posterior de carga piloto real

El 2026-06-10 se intento cargar datos reales controlados de SOURCE-003 / Tabla 2 vNext para la fecha piloto 2026-06-08.

El intento quedo documentado en:

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

Resultado:

  • gate previo: PASS
  • backup logico previo: PASS
  • extraccion actual: 1262 filas
  • evidencia esperada: 1269 filas
  • conciliacion de importe total: FAIL
  • conciliacion de CMV: FAIL
  • carga ejecutada: NO
  • filas finales en tabla: 0
  • rollback ejecutado: NO, porque no hubo transaccion de carga

Lectura:

  • la migracion estructural sigue validada
  • la tabla sigue vacia
  • no se debe reintentar la carga hasta aprobar humanamente el diccionario de 68 columnas reales de Tabla 2 V2, el mapping CSV/PostgreSQL y la cobertura completa de source_row_hash_v1