Saltar a contenido

SOURCE-003 Core DDL Candidate

Fecha local: 2026-06-15

Estado: DDL CORE 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-CORE-DDL-CANDIDATE.md

1. Objetivo

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

Tabla candidata:

text business_observer.core_source_003_sales_items

Origen futuro:

text business_observer.raw_source_003_sales_items

Batch piloto de referencia:

text 1827f887-9499-4579-b4f3-234d54f41f7f

Este paquete es documental y revisable. No se ejecuto SQL, no se uso psql, no se toco PostgreSQL, no se creo tabla real, no se modifico Python, no se cargo data, no se genero CSV, no se ejecuto runner y no se toco RAW/CORE/MART real.

2. Documentos base

  • SOURCE-003-CORE-LAYER-CONTRACT.md
  • SOURCE-003-IMPORTER-PROMOTE-CORE-PLAN.md
  • SOURCE-003-LOAD-RAW-LOCAL-DEV-POST-EXECUTION-REVIEW.md
  • SOURCE-003-RAW-DDL-LOCAL-DEV-FORWARD-001.md

Lectura vigente:

  • RAW local-dev existe como business_observer.raw_source_003_sales_items;
  • el batch 1827f887-9499-4579-b4f3-234d54f41f7f tiene 1886 filas validadas en RAW;
  • line_key, source_row_hash y loaded_at estan completos en el batch;
  • 0 duplicados por tenant_id + line_key dentro del batch;
  • promote-core sigue como comando futuro bloqueado;
  • no existe todavia tabla CORE real aprobada.

3. Archivos SQL candidatos

Todos los SQL viven en:

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

Paquete candidato:

  • 005_source_003_core_ddl_candidate_preflight.sql
  • 005_source_003_core_ddl_candidate_forward.sql
  • 005_source_003_core_ddl_candidate_rollback.sql
  • 005_source_003_core_ddl_candidate_post_checks.sql

Regla: son SQL candidatos revisables. No fueron ejecutados.

4. Modelo fisico candidato

La tabla CORE candidata normaliza la evidencia RAW hacia nombres canonicos de negocio y conserva trazabilidad completa hacia RAW.

Conteo fisico candidato:

Grupo Cantidad Nota
Columnas tecnicas, batch y auditoria 17 Incluye id, tenant_id, sync_batch_id, hashes, timestamps y auditoria.
Documento comercial 9 Fecha, hora, tipo, numero, estado y documento interno.
Cliente 4 Codigo canonico, nombre y campos raw pendientes.
Producto 5 SKU canonico, nombre, marca y proveedor.
Vendedor y canal 4 Vendedor transaccional y canal raw/normalizado.
Cantidades 3 Decimales, sin float.
Importes 11 Decimales exactos para netos, impuestos, costos y contribucion.
Logistica 7 Campos raw preservados hasta normalizacion territorial aprobada.
Estado core y calidad 6 Estado, vigencia, missing flag y calidad.
Total fisico candidato 66 Tabla CORE candidata vacia.

5. Normalizacion RAW -> CORE

Mapping conceptual principal:

RAW CORE
fecha business_date
hora_origen_sgc document_time_raw, document_time si convierte sin ambiguedad
tipo_comp, nro_comp document_type, document_number
tipo_doc_int, nro_int_doc, documento document_internal_type, document_internal_number, document_label
codigo_cliente, cliente_nombre_raw customer_code, customer_name
sku, articulo_raw, marca_raw sku, product_name, brand
proveedor_codigo_raw, proveedor_nombre_raw supplier_code, supplier_name
vendedor_codigo, vendedor_nombre_raw seller_code, seller_name
canal_raw channel_raw, channel_normalized cuando exista catalogo aprobado
unidades, cant_bultos_vendidos quantity, package_quantity
importes y descuentos RAW unit_price, gross_amount, net_amount, discount_amount, tax_amount, cost_amount, contribution_amount
campos logisticos RAW delivery_*_raw, route_sheet_raw, logistic_zone_raw
record_status document_status, core_record_status
loaded_at raw_loaded_at

Reglas:

  • textos con trim lateral antes de promover;
  • vacios sin valor semantico a NULL;
  • codigos de cliente, producto, vendedor, proveedor y repartidor como text;
  • importes y cantidades como numeric, nunca float;
  • source_row_hash, sync_batch_id, line_key y raw_loaded_at preservados;
  • sin enriquecimiento desde SOURCE-001 o SOURCE-002;
  • sin KPI de MART dentro de CORE;
  • sin hard delete.

6. Claves candidatas

Clave tecnica:

text id

Clave logica CORE:

text tenant_id + line_key

Clave de promocion por batch:

text tenant_id + sync_batch_id + line_key

Clave de auditoria minima:

text tenant_id + sync_batch_id + source_row_hash

El id tecnico no reemplaza la identidad funcional.

7. Constraints candidatas

El forward candidato define:

  • PRIMARY KEY (id);
  • UNIQUE (tenant_id, line_key);
  • UNIQUE (tenant_id, sync_batch_id, line_key);
  • check estricto tenant_id = 'alpuntodeventa';
  • checks de no vacio para line_key, source_row_hash, metadata de origen, documento, cliente, sku y vendedor;
  • check SHA256 para source_row_hash;
  • check line_sequence >= 1;
  • catalogos cerrados para document_status, core_record_status y quality_status;
  • check de ventana temporal valid_to IS NULL OR valid_to >= valid_from.

No se exige signo positivo en cantidades o importes porque existen notas de credito, ajustes, anulaciones y valores validamente negativos o cero.

8. Indices candidatos

Indices propuestos:

  • tenant_id, sync_batch_id
  • tenant_id, source_row_hash
  • tenant_id, business_date
  • tenant_id, customer_code, business_date
  • tenant_id, seller_code, business_date
  • tenant_id, sku, business_date
  • tenant_id, document_type, document_number
  • tenant_id, channel_normalized, business_date
  • tenant_id, core_record_status
  • tenant_id, quality_status

9. 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 reversa futura debe usar rollback logico o rebuild por batch con gate separado.

10. Preflight candidato

El preflight candidato valida:

  • database esperada openclaw_business_observer_dev;
  • schema business_observer existente y con owner openclaw_bo_admin;
  • roles requeridos existentes y sin login;
  • RAW source table existente;
  • CORE candidate table ausente antes del forward;
  • batch autorizado con 1886 filas;
  • line_key, source_row_hash y loaded_at completos en RAW;
  • 0 duplicados por tenant_id + line_key dentro del batch;
  • PUBLIC sin privilegios sobre schema;
  • preflight sin DDL/DML y sin modificacion de RAW.

11. Forward candidato

El forward candidato:

  • crea o valida schema business_observer con owner openclaw_bo_admin;
  • crea business_observer.core_source_003_sales_items;
  • define 66 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;
  • no lee ni modifica RAW.

12. Rollback candidato

El rollback candidato elimina solo objetos de:

text business_observer.core_source_003_sales_items

Reglas:

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

13. Post-checks candidatos

Los post-checks deben exigir:

  • tabla creada;
  • owner openclaw_bo_admin;
  • 66 columnas;
  • 22 constraints esperadas;
  • 10 indices esperados;
  • row count exacto 0;
  • PUBLIC sin privilegios;
  • writer con SELECT, INSERT, UPDATE y sin DELETE;
  • reader con SELECT y sin escritura;
  • RAW source table todavia existente.

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

text row_count = 0

14. Riesgos y bloqueos

Riesgos:

  • channel_normalized requiere catalogo aprobado para no inventar semantica;
  • contribution_amount preserva el valor candidato, pero su lectura de margen sigue pendiente de cierre funcional;
  • la politica futura de update vs invalidacion por tenant_id + line_key requiere gate de promote-core;
  • la tabla CORE candidata no tiene RLS ni particionado productivo.

Bloqueos 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;
  • RAW/CORE/MART real no tocado;
  • rollback real no ejecutado;
  • VPS, Docker, OpenClaw, NPM y Portainer no tocados;
  • push y deploy no realizados;
  • sync diaria, carga masiva, produccion final y OpenClaw executor bloqueados.

15. Decision

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

El paquete candidato deja disenada la futura tabla CORE de SOURCE-003 como modelo normalizado de negocio trazable hacia RAW. La implementacion real sigue bloqueada hasta revision tecnica, gate de ejecucion local-dev, aprobacion humana, fingerprint DB y post-checks con row_count = 0.