Saltar a contenido

SOURCE-003 Dedicated DB DDL Pilot Gate

Fecha: 2026-06-11

Estado: DISENO DOCUMENTAL / APTO PARA REVISION / NO EJECUTAR

portal_visible = yes

Scope: tenant

tenant_id: alpuntodeventa

Owner: Gabi / Carlos Canu

Fuente de verdad: docs/tenants/alpuntodeventa/business-observer/design/SOURCE-003-DEDICATED-DB-DDL-PILOT-GATE.md

1. Objetivo

Disenar documentalmente el proximo gate DDL piloto para SOURCE-003 en la DB local dedicada openclaw_business_observer_dev, sin ejecutar SQL, sin crear tablas y sin cargar datos.

El gate busca dejar listo un modelo revisable para una futura tabla business_observer.source_003_sales_items dentro de la DB dedicada, separado de la etapa local legacy gestion_de_negocios_core.

Este documento no autoriza:

  • DDL
  • migraciones
  • inserts
  • upserts
  • cargas de SOURCE-003
  • sync diaria
  • carga masiva
  • produccion final
  • cambios en gestion_de_negocios_core
  • cambios en VPS, Docker, OpenClaw o NPM

2. Safe point inicial

Control Resultado
rama main
git status -sb ## main...origin/main
git rev-parse HEAD 797c62477ec4f6ad1db12e01e4c7a5f5922414b0
git ls-remote origin main 797c62477ec4f6ad1db12e01e4c7a5f5922414b0
decision SAFE POINT PASS

3. Lectura documental aplicada

Read-set obligatorio aplicado antes de disenar:

  • docs/governance/PROJECT-CONSTITUTION.md
  • CODEX.md
  • docs/governance/ACTIVE-CONTEXT.md
  • docs/governance/GATE-CODEX-EFFICIENCY.md
  • docs/governance/GOVERNANCE-CONTROL-TOWER.md
  • docs/governance/VALIDATION-STATE.md
  • docs/governance/documentation/DOCUMENT-HIERARCHY.md
  • docs/PROJECT-STATE.md
  • docs/ROADMAP.md
  • docs/governance/operations/CURRENT-BASELINE.md
  • docs/tenants/alpuntodeventa/business-observer/README.md
  • docs/tenants/alpuntodeventa/business-observer/design/POSTGRES-LOCAL-DEV-ENVIRONMENT.md
  • docs/tenants/alpuntodeventa/business-observer/design/SOURCE-003-CREDENTIALS-PREFLIGHT.md
  • documentos vigentes de SOURCE-003, source authority, mapping y diccionarios listados en las secciones siguientes

Clasificacion operativa: DESIGN + VALIDATE.

4. Estado solo lectura de DB dedicada

Verificacion ejecutada solo con consultas de catalogo y sin imprimir secretos, usuarios de conexion, passwords ni connection strings.

Control Resultado
database openclaw_business_observer_dev PASS
schema business_observer PASS
tablas base en business_observer 0
schema dedicado vacio PASS
roles objetivo encontrados 3/3
openclaw_bo_admin NOLOGIN
openclaw_bo_writer NOLOGIN
openclaw_bo_reader NOLOGIN
DDL ejecutado en esta tarea NO
DML ejecutado en esta tarea NO

Lectura:

  • la DB dedicada existe
  • el schema dedicado existe
  • no hay tablas cargadas en business_observer
  • SOURCE-003 no fue cargado en la DB dedicada
  • el entorno esta apto solo para revision documental de DDL

5. Source authority usada

Autoridad de fuente para este gate:

Documento Rol
sources/SOURCE-003-SGC-VENTAS-COMPROBANTES.md fuente funcional y reglas criticas
source-authority/SOURCE-003-VENTAS-TABLA2-AUTHORITY.sql autoridad historica preservada
source-authority/SOURCE-003-VENTAS-VNEXT-TABLA2-AUTHORITY.sql candidata vNext V1 preservada
source-authority/SOURCE-003-VENTAS-VNEXT-TABLA2-AUTHORITY-V2.sql candidata vigente para Tabla 2 V2
source-authority/SOURCE-003-QUERY-DELTA-REVIEW.md delta V1 vs V2 y regla de flags
source-authority/SOURCE-AUTHORITY-REGISTRY.md registro de autoridad de fuentes

Reglas tomadas como autoridad:

  • Tabla 2 es la unica salida candidata para sync itemizada.
  • Tabla 1/3/4/5/6 son referencias de calculo y conciliacion, no tablas fuente a sincronizar.
  • cualquier extraccion futura debe forzar Tabla1=0, Tabla2=1, Tabla3=0, Tabla4=0, Tabla5=0, Tabla6=0.
  • no se deben reemplazar calculos sagrados de la query por campos crudos del ERP.
  • SOURCE-003 es fuente viva y puede cambiar retroactivamente para fechas ya cargadas.

6. Mapping y diccionario usados

Documento Estado usado
data-dictionary/SOURCE-003-TABLA2-COLUMN-DICTIONARY.md APPROVED_FOR_CONTROLLED_PILOT
design/SOURCE-003-SALES-ITEMS-COLUMN-MAPPING.md APPROVED_FOR_CONTROLLED_PILOT
design/SOURCE-003-LINE-IDENTITY-DECISION.md AMARILLO ACEPTADO
design/SOURCE-003-SALES-ITEMS-DDL-DESIGN.md diseno previo de referencia
design/sql/001_source_003_sales_items_design.sql SQL documental de referencia, no ejecutable
SOURCE-003-SNAPSHOT-001.md snapshot controlado de 2026-06-09
SOURCE-003-DRIFT-ANALYSIS-001.md clasificacion de fuente viva
design/SOURCE-003-SALES-ITEMS-PILOT-LOAD-001.md evidencia piloto legacy snapshot
design/SOURCE-003-SALES-ITEMS-WINDOW-PILOT-001.md evidencia piloto legacy ventana movil

Resumen:

  • 68/68 columnas reales de Tabla 2 V2 estan inventariadas.
  • 68/68 columnas reales estan mapeadas a columnas PostgreSQL.
  • source_row_hash_v1 debe canonicalizar las 68 columnas reales.
  • line_key_v4 queda aceptada en estado AMARILLO ACEPTADO.
  • los datos personales, logisticos o fiscales deben persistirse solo con controles de exposicion posteriores.

7. Tablas candidatas

7.1 Tabla candidata para el piloto DDL

Tabla Decision
business_observer.source_003_sales_items CANDIDATA PRINCIPAL / APTO PARA REVISION

Grano:

text una linea calculada de SOURCE-003 / Tabla 2 V2 por tenant, documento, cliente, SKU, vendedor transaccional, hora_origen_sgc, line_sequence_v1 y line_key_v4

Capa conceptual:

text raw/core transaccional itemizado

7.2 Tablas candidatas fuera del piloto DDL

Tabla Decision
business_observer.source_003_sync_batches FUTURA / NO INCLUIR EN ESTE DDL PILOTO
business_observer.source_003_sales_item_audit FUTURA / NO INCLUIR EN ESTE DDL PILOTO
business_observer.source_003_daily_snapshots FUTURA / NO INCLUIR EN ESTE DDL PILOTO
vistas o materialized views analiticas FUTURAS / NO INCLUIR EN ESTE DDL PILOTO

Motivo:

  • el proximo gate debe ser estrecho y reversible
  • la DB dedicada sigue vacia
  • conviene validar primero la tabla base con constraints e indices minimos
  • auditoria historica, batch registry y snapshots requieren diseno propio

8. Columnas candidatas

La tabla candidata debe preservar las 68 columnas reales de Tabla 2 V2 mas columnas tecnicas de trazabilidad.

8.1 Columnas tecnicas

Columna Tipo Nulabilidad Regla
id uuid not null identidad tecnica interna
tenant_id text not null valor esperado alpuntodeventa
line_key text not null contiene line_key_v4
line_sequence_v1 integer not null generado por pipeline, no viene del origen
source_row_hash text not null contiene source_row_hash_v1 sobre 68/68 columnas
source_system text not null origen o snapshot usado
source_object text not null SOURCE-003 / Tabla 2 V2
source_query_version text not null version de autoridad SQL
sync_batch_id uuid not null lote de carga o sync
extracted_at timestamptz not null momento de extraccion
last_seen_at timestamptz not null ultima observacion valida
created_at timestamptz not null alta interna
updated_at timestamptz not null actualizacion interna
record_status text not null active, inactive, corrected, missing_from_source

8.2 Identidad documental, cliente, vendedor y producto

Columna Tipo 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
codigo_cliente text not null
cliente_nombre_raw text null
direccion_de_pedidos_raw text null
vendedor_codigo text not null
vendedor_nombre_raw text null
sku text not null
articulo_raw text null
marca_raw text null
proveedor_codigo_raw text null
proveedor_nombre_raw text null

8.3 Canal, logistica y contexto

Columna Tipo Nulabilidad
canal_raw text null
ramo_raw text null
grupo_raw text null
rubro_raw text null
motivo_devolucion_raw text null
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

8.4 Numericos, precios, impuestos, costos y fisicos

Columna Tipo Nulabilidad
unidades numeric(19,4) not null
precio_unitario numeric(19,6) null
porc_desc_linea numeric(9,4) null
desc_neto_unitario_linea numeric(19,6) null
iva_alicuota_pct numeric(9,4) null
precio_neto_unitario_cdesc_linea numeric(19,6) null
subtotal_neto_item_cdesc_linea numeric(19,4) null
desc_al_pie_pct numeric(9,4) null
desc_pie_unitario_neto numeric(19,6) null
precio_neto_unitario_cdesc_pie numeric(19,6) null
imponible_neto_item numeric(19,4) null
perc_iibb_raw numeric(19,4) null
alicuota_perc_iibb_calculada_pct numeric(9,4) null
perc_iibb_item_unidad numeric(19,6) null
iibb_item numeric(19,4) null
iva_item_unidad numeric(19,6) null
iva_item numeric(19,4) null
importe_total_unitario numeric(19,4) null
importe_total_item numeric(19,4) not null
total_desc_neto_linea numeric(19,4) null
total_desc_neto_al_pie numeric(19,4) null
total_desc_np numeric(19,4) null
total_ajustes_saldos_ctacte numeric(19,4) null
perc_iva numeric(19,4) null
costo_lista numeric(19,4) null
desc_compra1 numeric(9,4) null
desc_compra2 numeric(9,4) null
desc_compra3 numeric(9,4) null
cmv_bruto_unidad numeric(19,4) null
cmv_bruto_item numeric(19,4) null
descuento_item numeric(19,4) null
markup numeric(9,4) null
max_dcto_articulo numeric(9,4) null
contribucion_item numeric(19,4) null
indicador_tipo_registro smallint null
lista_de_precio_raw text null
peso_total numeric(19,6) null
volumen_total numeric(19,6) null
cant_bultos_vendidos numeric(19,6) null

9. Claves candidatas

Clave Estado Decision
primary key (id) candidata usar como identidad tecnica interna
unique (tenant_id, line_key) candidata usar solo si line_key = line_key_v4
line_key_v1 fallida no usar como unique
line_key_v3 fallida no usar como unique
line_key_v4 AMARILLO ACEPTADO apta para piloto analitico, no auditoria legal perfecta

Formula de identidad aceptada:

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

Reglas:

  • no usar IdFila de la query SQL Server
  • no usar importes o descuentos como identidad
  • no usar nombre de cliente ni direccion como identidad
  • versionar cualquier cambio futuro como line_key_v5 o superior
  • si el ERP expone un id fisico de detalle, revisar el modelo

10. Indices minimos

Indices candidatos para el DDL piloto:

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 inspeccion de cambios

No incluir todavia:

  • indices de texto completo
  • indices GIN
  • particionado
  • materialized views
  • indices para dashboards no aprobados

11. Checks y constraints minimos

Constraints candidatos:

Constraint Regla Estado
record_status_ck record_status in ('active','inactive','corrected','missing_from_source') apto para revision
line_sequence_v1_positive_ck line_sequence_v1 >= 1 apto para revision
hora_origen_sgc_format_ck hora_origen_sgc ~ '^[0-9]{6}$' apto para revision
unidades_nn_ck unidades is not null apto para revision
importe_total_item_nn_ck importe_total_item is not null apto para revision
fecha_not_future_ck fecha <= current_date + interval '1 day' revisar si conviene mover a validacion de carga

No agregar:

  • cmv_bruto_item > 0, porque hay evidencia real de CMV cero
  • checks que bloqueen importes negativos, porque notas de credito y devoluciones son esperadas
  • checks que asuman canal no nulo
  • foreign keys a clientes, productos o vendedores en este piloto inicial

12. Campos de trazabilidad

Trazabilidad minima obligatoria:

  • tenant_id
  • source_system
  • source_object
  • source_query_version
  • sync_batch_id
  • extracted_at
  • last_seen_at
  • created_at
  • updated_at
  • record_status
  • source_row_hash
  • line_key
  • line_sequence_v1

Reglas:

  • source_row_hash_v1 debe calcularse desde las 68 columnas reales de Tabla 2 V2, no desde un subconjunto.
  • sync_batch_id identifica la corrida de carga o sync.
  • last_seen_at permite distinguir fila reaparecida sin cambios.
  • record_status = missing_from_source debe usarse para desapariciones controladas, sin hard delete.
  • la version de query debe registrar la autoridad real usada.

13. Criterios de carga piloto futura

Una tarea futura de carga piloto en la DB dedicada deberia cumplir como minimo:

  1. aprobacion humana explicita para ejecutar DDL
  2. rollback o plan de drop documentado antes de tocar la DB
  3. backup o evidencia de estado inicial de la DB dedicada
  4. business_observer vacio o estado esperado confirmado inmediatamente antes de ejecutar
  5. SOURCE-003 extraido solo con Tabla 2 explicita
  6. snapshot local con sha256 antes de transformar
  7. validacion de 68/68 headers contra diccionario y mapping
  8. calculo de line_sequence_v1, line_key_v4 y source_row_hash_v1
  9. validacion de duplicados tenant_id + line_key
  10. validacion de nulos criticos
  11. conciliacion de filas, importe total y CMV
  12. carga en transaccion unica
  13. sin DELETE ni hard delete
  14. post-check de filas, hashes, fechas y agregados
  15. documentacion de evidencia y decision final

No usar gestion_de_negocios_core para este piloto futuro.

14. Validaciones minimas del DDL futuro

Antes de ejecutar cualquier DDL real:

  • confirmar nuevamente safe point Git
  • confirmar nuevamente que la DB dedicada existe
  • confirmar nuevamente que business_observer esta vacio o en estado esperado
  • confirmar owners y grants minimos
  • revisar extension o estrategia para generar uuid
  • decidir si el check temporal de fecha va al DDL o a validacion de carga
  • revisar si source_system debe aceptar snapshot:SOURCE-003-SNAPSHOT-001 y mssql:mssql-sgc-ecommerce como valores distintos
  • validar que el DDL fisico contemple 83 columnas finales esperadas: 68 de negocio mas 15 tecnicas si se mantiene el modelo actual
  • validar git diff --check
  • validar mkdocs build --strict

15. Riesgos

Riesgo Lectura
identidad de linea line_key_v4 es AMARILLO ACEPTADO, no id fisico ERP
fuente viva la misma fecha puede cambiar por anulaciones, rechazos, refacturacion o cambios de maestro
multiples resultsets V2 V2 puede emitir Tabla 1/5/6 si no se fuerzan flags
datos sensibles cliente, direccion, reparto y fiscalidad requieren controles de exposicion
CMV vivo CMV puede cambiar por dependencia de maestro PRODUCTS vivo
checks demasiado duros pueden bloquear notas de credito, importes negativos o CMV cero validos
drift de diccionario cualquier nueva query de Gabi puede cambiar columnas o formulas
produccion prematura el piloto local legacy no habilita produccion final

16. Bloqueos

Bloqueos vigentes:

  • no hay aprobacion para ejecutar DDL
  • no hay aprobacion para crear tablas
  • no hay aprobacion para insertar datos
  • no hay aprobacion para cargar SOURCE-003
  • no hay aprobacion para sync diaria
  • no hay aprobacion para carga masiva
  • no hay aprobacion para produccion final
  • no hay autorizacion para tocar VPS, Docker, OpenClaw o NPM
  • la DB dedicada tiene roles NOLOGIN; cualquier estrategia de usuario operativo requiere decision separada
  • line_key_v4 no cierra auditoria legal perfecta
  • falta una tarea futura separada para convertir este diseno en migracion ejecutable revisada

17. Decision final

Decision del gate DDL documental:

text APTO PARA REVISION

Lectura exacta:

  • apto para revision humana y preparacion de un futuro paquete DDL
  • no apto para ejecucion automatica
  • no apto para migracion productiva
  • no apto para carga piloto en esta tarea
  • no apto para sync diaria, carga masiva ni produccion final

Motivo:

  • la DB dedicada existe y esta vacia
  • el schema dedicado existe
  • los roles minimos existen como NOLOGIN
  • el diccionario y mapping cubren 68/68 columnas
  • existe diseno previo de referencia para columnas, claves, checks e indices
  • la identidad line_key_v4 esta aceptada para piloto analitico con riesgo explicitamente documentado
  • los riesgos y bloqueos quedan declarados antes de ejecutar cualquier SQL

18. Proximo paso recomendado

Abrir una tarea separada para preparar un paquete DDL piloto revisable para openclaw_business_observer_dev, todavia sin carga de datos, con:

  • SQL de migracion separado del documento de diseno
  • rollback documental
  • decision sobre uuid
  • decision sobre check temporal de fecha
  • verificacion de grants/default privileges post-DDL
  • mkdocs build --strict

Solo despues de ese gate, y con aprobacion humana explicita, evaluar una tarea posterior de carga piloto desde snapshot o ventana controlada.