SOURCE-003 Raw DDL Candidate¶

Fecha local: 2026-06-15

Estado: DDL RAW CANDIDATO / NO EJECUTADO / NO IMPLEMENTADO EN DB

portal_visible = yes

Scope: tenant

tenant_id: alpuntodeventa

Owner: Gabi / Carlos Canu

Fuente de verdad: docs/tenants/alpuntodeventa/business-observer/design/SOURCE-003-RAW-DDL-CANDIDATE.md

1. Objetivo¶

Disenar el paquete DDL candidato para la futura tabla RAW de SOURCE-003 / SGC Ventas / Tabla 2 V2.

Tabla candidata:

text business_observer.raw_source_003_sales_items

Este paquete es documental y revisable. No se ejecuto SQL, no se toco PostgreSQL, no se creo tabla real, no se modifico Python, no se ejecuto runner, no se genero CSV, no se cargo data y no se habilita sync diaria.

2. Relacion con la tabla piloto¶

La tabla existente:

text business_observer.source_003_sales_items

queda explicitamente clasificada como PILOTO, no como RAW final.

Lectura obligatoria:

source_003_sales_items es evidencia historica de piloto dedicado;
no reemplaza el contrato RAW;
no debe usarse como tabla RAW final por conveniencia;
no habilita produccion, carga masiva ni sync diaria;
no define por si sola permisos, idempotencia ni rollback de la capa RAW.

La tabla candidata RAW usa otro nombre para evitar mezcla operacional entre piloto y evidencia gobernada futura.

3. Archivos SQL candidatos¶

Todos los SQL viven en:

text docs/tenants/alpuntodeventa/business-observer/design/sql/

Paquete candidato:

004_source_003_raw_ddl_candidate_preflight.sql
004_source_003_raw_ddl_candidate_forward.sql
004_source_003_raw_ddl_candidate_rollback.sql
004_source_003_raw_ddl_candidate_post_checks.sql

Regla: son SQL candidatos revisables. No fueron ejecutados.

4. Columnas candidatas¶

El DDL candidato preserva las columnas del prepared CSV vigente y suma la metadata RAW obligatoria loaded_at.

Lectura de conteo:

Grupo	Cantidad	Nota
Columnas prepared CSV vigentes	`83`	Incluye `68` columnas de negocio y metadata tecnica del pipeline piloto.
Metadata RAW adicional obligatoria	`1`	`loaded_at`, exigida por el contrato RAW.
Total fisico candidato	`84`	Tabla RAW candidata, no tabla piloto.

Columnas tecnicas y metadata RAW:

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

Columnas de negocio preservadas desde Tabla 2 V2 / prepared CSV:

fecha
hora_origen_sgc
tipo_comp
nro_comp
tipo_doc_int
nro_int_doc
documento
condicion_fiscal_raw
codigo_cliente
cliente_nombre_raw
direccion_de_pedidos_raw
vendedor_codigo
vendedor_nombre_raw
sku
articulo_raw
marca_raw
proveedor_codigo_raw
proveedor_nombre_raw
canal_raw
ramo_raw
grupo_raw
rubro_raw
motivo_devolucion_raw
hoja_ruta_raw
direccion_entrega_raw
localidad_entrega_raw
provincia_entrega_raw
cod_repartidor_raw
repartidor_raw
zona_raw
unidades
precio_unitario
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
imponible_neto_item
perc_iibb_raw
alicuota_perc_iibb_calculada_pct
perc_iibb_item_unidad
iibb_item
iva_item_unidad
iva_item
importe_total_unitario
importe_total_item
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
cmv_bruto_item
descuento_item
markup
max_dcto_articulo
contribucion_item
indicador_tipo_registro
lista_de_precio_raw
peso_total
volumen_total
cant_bultos_vendidos

5. Claves candidatas¶

Clave tecnica:

text id

Clave logica por batch:

text tenant_id + sync_batch_id + line_key

La clave logica incluye sync_batch_id porque RAW preserva evidencia por corrida. Un mismo line_key puede reaparecer en batches futuros para permitir comparacion, drift y promocion controlada hacia core.

Clave de auditoria candidata:

text tenant_id + sync_batch_id + source_row_hash

6. Constraints candidatas¶

El forward candidato define:

PRIMARY KEY (id);
UNIQUE (tenant_id, sync_batch_id, line_key);
checks de no vacio para tenant_id, line_key, source_row_hash, source_system, source_object y source_query_version;
check de record_status en active, inactive, corrected, missing_from_source;
check de line_sequence_v1 >= 1;
check de formato observado hora_origen_sgc como HHMMSS;
checks de campos minimos de identidad documental, cliente, vendedor, SKU, unidades e importe total.

No se agrega check positivo para CMV o importes porque existen notas de credito, ajustes, anulaciones y valores validamente negativos o cero.

7. Indices candidatos¶

Indices propuestos:

tenant_id, sync_batch_id
tenant_id, sync_batch_id, line_key
tenant_id, source_row_hash
tenant_id, fecha
tenant_id, codigo_cliente, fecha
tenant_id, vendedor_codigo, fecha
tenant_id, sku, fecha
tenant_id, tipo_comp, nro_comp
tenant_id, record_status

8. Owner y grants¶

Owner candidato:

text openclaw_bo_admin

Roles esperados:

openclaw_bo_admin
openclaw_bo_writer
openclaw_bo_reader

Permisos:

Rol	Permisos tabla	Prohibiciones explicitas
`openclaw_bo_admin`	owner	n/a
`openclaw_bo_writer`	`SELECT`, `INSERT`, `UPDATE`	sin `DELETE`, `TRUNCATE`, `REFERENCES`, `TRIGGER`
`openclaw_bo_reader`	`SELECT`	sin escritura
`PUBLIC`	ninguno	sin privilegios sobre schema ni tabla

writer no recibe DELETE. Cualquier rollback futuro debe pasar por paquete separado, conteo esperado, fingerprint DB, aprobacion humana y bloqueo si hay dependencias core o mart.

9. Preflight candidato¶

El preflight candidato es de catalogo y solo lectura. Debe validar:

database esperada openclaw_business_observer_dev;
schema business_observer existente y con owner openclaw_bo_admin;
roles requeridos existentes;
roles requeridos sin login;
tabla RAW candidata ausente antes del forward;
tabla piloto presente o ausente solo como observacion, sin tratarla como RAW final;
PUBLIC sin privilegios sobre business_observer;
que el preflight no crea objetos ni carga datos.

10. Forward candidato¶

El forward candidato:

crea o valida schema business_observer con owner openclaw_bo_admin;
crea business_observer.raw_source_003_sales_items;
define 84 columnas fisicas;
define constraints, indices, comments, owner y grants;
revoca privilegios de PUBLIC;
otorga a writer solo SELECT, INSERT, UPDATE;
otorga a reader solo SELECT;
no inserta datos.

11. Rollback candidato¶

El rollback candidato elimina solo objetos de:

text business_observer.raw_source_003_sales_items

Reglas:

aborta si la tabla existe y tiene filas;
no usa TRUNCATE;
no borra datos;
no toca business_observer.source_003_sales_items;
no elimina schema ni roles;
solo dropea indices y tabla si la tabla RAW candidata esta vacia.

12. Post-checks candidatos¶

Los post-checks deben exigir:

tabla creada;
owner openclaw_bo_admin;
84 columnas;
constraints esperadas;
indices esperados;
row count exacto 0;
PUBLIC sin privilegios;
writer con SELECT, INSERT, UPDATE y sin DELETE;
reader con SELECT y sin escritura;
tabla piloto diferenciada como piloto, no RAW final.

El resultado correcto despues de un forward aprobado en una tarea futura debe mantener:

text row_count = 0

13. Bloqueos preservados¶

Quedan preservados:

PostgreSQL no tocado;
SQL no ejecutado;
DB no modificada;
tabla real no creada;
Python no modificado;
runner no ejecutado;
CSV no generado;
datos no cargados;
rollback real no ejecutado;
VPS, Docker, OpenClaw y NPM no tocados;
push y deploy no realizados;
sync diaria, carga masiva, produccion final y OpenClaw executor bloqueados.

14. Decision¶

text DDL RAW CANDIDATO / NO EJECUTADO / NO IMPLEMENTADO EN DB

El paquete candidato deja disenada la futura tabla RAW de SOURCE-003 como evidencia gobernada por batch. La implementacion real sigue bloqueada hasta aprobacion humana separada, fingerprint DB, gate de ejecucion, rollback aprobado y validaciones previas.