SOURCE-003 Mart DDL Candidate¶

Fecha local: 2026-06-16

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

1. Objetivo¶

Disenar el paquete DDL MART candidato para SOURCE-003 / SGC Ventas / Tabla 2 V2, sin ejecutarlo.

El paquete propone tablas agregadas de consumo analitico gobernado desde:

text business_observer.core_source_003_sales_items

Batch piloto de referencia:

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

CORE debe conservar:

text 1886 filas

Este documento y sus SQL candidatos no ejecutan SQL, no tocan PostgreSQL, no crean tablas reales, no modifican Python, no cargan datos, no generan CSV, no ejecutan runner y no tocan RAW/CORE/MART real.

2. Documentos base leidos¶

SOURCE-003-MART-LAYER-CONTRACT.md
SOURCE-003-IMPORTER-BUILD-MART-PLAN.md
SOURCE-003-PROMOTE-CORE-LOCAL-DEV-POST-EXECUTION-REVIEW.md
SOURCE-003-CORE-DDL-LOCAL-DEV-FORWARD-001.md

3. SQL candidatos¶

Archivo	Proposito
`design/sql/006_source_003_mart_ddl_candidate_preflight.sql`	Validar DB, schema, roles, CORE, batch piloto, ausencia de MART candidatas y permisos `PUBLIC`.
`design/sql/006_source_003_mart_ddl_candidate_forward.sql`	Crear tablas MART candidatas vacias, constraints, indices, owner, comments y grants.
`design/sql/006_source_003_mart_ddl_candidate_rollback.sql`	Dropear solo las tablas MART candidatas, abortando si cualquiera tiene filas.
`design/sql/006_source_003_mart_ddl_candidate_post_checks.sql`	Verificar existencia, owner, grants, constraints, indices y `row_count = 0` en todas las MART candidatas.

4. Tablas MART V1 candidatas¶

Tabla candidata	Grano	Uso
`business_observer.mart_source_003_sales_daily`	`tenant_id + sync_batch_id + source_query_version + business_date`	Lectura diaria de ventas, unidades, comprobantes, clientes y SKUs.
`business_observer.mart_source_003_sales_by_seller`	`tenant_id + sync_batch_id + source_query_version + period_key + seller_code`	Performance transaccional por vendedor.
`business_observer.mart_source_003_sales_by_customer`	`tenant_id + sync_batch_id + source_query_version + period_key + customer_code`	Compra, recurrencia, abandono y recuperacion por cliente.
`business_observer.mart_source_003_sales_by_sku`	`tenant_id + sync_batch_id + source_query_version + period_key + sku`	Mix, unidades, importes y participacion por producto/SKU.

No se incluye tabla fisica por territorio en V1 porque territory_key todavia no tiene semantica aprobada para inferir vendedor responsable ni territorio comercial.

5. Trazabilidad minima¶

Todas las tablas candidatas incluyen:

tenant_id
sync_batch_id
source_query_version
mart_built_at
row_count_source
mart_build_id
mart_name
source_id
source_table
source_core_row_hash_set_hash
created_at
updated_at

Regla: row_count_source representa cantidad de filas CORE usadas para el grupo agregado, no cantidad de filas MART.

6. Metricas candidatas¶

Metricas base:

total_items
total_units
total_net_amount
total_gross_amount
document_count
customer_count
sku_count

Metricas condicionadas:

total_cmv
contribution_amount

Advertencia semantica:

total_cmv y contribution_amount quedan persistibles solo como columnas candidatas. Su lectura economica requiere revision semantica y conciliacion formal antes de habilitar dashboards, reportes productivos o consultas LLM operativas.

7. Ownership, permisos y seguridad¶

Owner esperado:

text openclaw_bo_admin

Permisos candidatos:

Rol	Permisos
`openclaw_bo_writer`	`SELECT`, `INSERT`, `UPDATE`; sin `DELETE`
`openclaw_bo_reader`	`SELECT`
`PUBLIC`	sin privilegios sobre schema ni tablas

El paquete no propone DELETE, TRUNCATE, REFERENCES ni TRIGGER para roles de consumo/escritura.

8. Rollback candidato¶

El rollback candidato:

valida current_database() = openclaw_business_observer_dev;
revisa las cuatro tablas MART candidatas;
aborta si cualquiera existe y tiene filas;
no usa TRUNCATE;
no borra datos;
no toca RAW;
no toca CORE;
no toca tablas MART reales ajenas al paquete.

9. Post-checks candidatos¶

Los post-checks exigen:

DB correcta;
schema business_observer existente;
owner de schema openclaw_bo_admin;
cuatro tablas MART candidatas existentes;
owner de cada tabla openclaw_bo_admin;
row_count = 0 en todas las MART candidatas;
constraints requeridas presentes;
indices requeridos presentes;
writer con SELECT/INSERT/UPDATE y sin DELETE;
reader con SELECT y sin INSERT/UPDATE/DELETE;
PUBLIC sin privilegios sobre schema ni tablas;
CORE existe y conserva 1886 filas para el batch piloto.

10. Riesgos y decisiones pendientes¶

territory_key no debe inferir vendedor responsable. La lectura de territorio comercial requiere cruce gobernado con clientes asignados, geografia, ventas y productos.
CMV, costos y contribucion requieren revision semantica antes de consumo ejecutivo o automatizado.
contribution_amount queda con advertencia semantica hasta reconciliacion formal.
Las reglas de signo para notas de credito, anulaciones y comprobantes correctivos deben preservarse desde CORE y revisarse antes de cualquier KPI productivo.
No se habilitan dashboards, reportes productivos ni consultas LLM operativas.
No se habilita build-mart, sync diaria, carga masiva ni produccion final.

11. Prohibiciones preservadas¶

Queda prohibido en esta tarea:

ejecutar SQL;
usar psql;
tocar PostgreSQL;
crear tablas reales;
modificar Python;
cargar datos;
tocar RAW/CORE/MART real;
generar CSV;
ejecutar runner;
usar VPS, Docker, OpenClaw, NPM o Portainer;
push o deploy.

12. Decision¶

text DDL MART CANDIDATO / NO EJECUTADO / NO IMPLEMENTADO EN DB APTO PARA REVISION TECNICA NO APTO PARA PRODUCCION NO APTO PARA SYNC DIARIA NO APTO PARA DASHBOARDS/LLM PRODUCTIVOS

El paquete queda listo para revision tecnica documental. Cualquier preflight, forward local-dev, implementacion Python build-mart o carga MART requiere tarea separada, SAFE POINT nuevo y autorizacion explicita.