Saltar a contenido

SOURCE-003 Build Mart Write Path Gate 001

Fecha local: 2026-06-18

Estado: GATE WRITE PATH DOCUMENTADO / NO IMPLEMENTADO / NO EJECUTADO

portal_visible = yes

Scope: tenant

tenant_id: alpuntodeventa

Owner: Gabi / Carlos Canu

Fuente de verdad: docs/tenants/alpuntodeventa/business-observer/design/SOURCE-003-BUILD-MART-WRITE-PATH-GATE-001.md

1. Objetivo

Disenar el gate y el flujo transaccional futuro para:

powershell python scripts/source_003_importer.py build-mart --execute

Esta tarea no implementa Python, no ejecuta SQL, no escribe en DB y no habilita build-mart --execute.

2. Safe point documental

Control Resultado
workspace C:\APV\openclawai
rama main
git status -sb inicial ## main...origin/main
git rev-parse HEAD inicial e935dbf96e3440cbe0a31734030a54d1871385d2
ultimo commit inicial docs: preflight source 003 build mart execute
decision SAFE POINT PASS

3. Documentos base leidos

  • scripts/source_003_importer.py
  • docs/tenants/alpuntodeventa/business-observer/design/SOURCE-003-BUILD-MART-EXECUTE-PREFLIGHT-001.md
  • docs/tenants/alpuntodeventa/business-observer/design/SOURCE-003-MART-LAYER-CONTRACT.md
  • docs/tenants/alpuntodeventa/business-observer/design/SOURCE-003-MART-DDL-CANDIDATE.md
  • docs/tenants/alpuntodeventa/business-observer/design/sql/006_source_003_mart_ddl_candidate_forward.sql
  • docs/tenants/alpuntodeventa/business-observer/design/SOURCE-003-PROMOTE-CORE-WRITE-PATH-IMPLEMENTATION-001.md
  • docs/tenants/alpuntodeventa/business-observer/PROJECT-STATE.md
  • docs/tenants/alpuntodeventa/business-observer/ROADMAP.md

4. Alcance obligatorio del gate futuro

Control Valor obligatorio
DB permitida openclaw_business_observer_dev
schema business_observer
source CORE business_observer.core_source_003_sales_items
MART daily business_observer.mart_source_003_sales_daily
MART seller business_observer.mart_source_003_sales_by_seller
MART customer business_observer.mart_source_003_sales_by_customer
MART sku business_observer.mart_source_003_sales_by_sku
batch permitido 1827f887-9499-4579-b4f3-234d54f41f7f
RAW final esperado 1886
CORE batch rows requeridas 1886
MART inicial daily/seller/customer/sku 0/0/0/0
estimates requeridas 1/25/173/180

5. Fingerprint DB obligatorio

text ::1/128:5432|openclaw_business_observer_dev|postgres|PostgreSQL 15.15, compiled by Visual C++ build 1944, 64-bit

Reglas:

  • el comando debe observar el fingerprint antes de cualquier SQL write;
  • debe coincidir exactamente con una lista aprobada;
  • si cambia host, puerto, DB, usuario o version, resultado BLOCKED;
  • el fingerprint observado debe quedar en payload JSON y en la evidencia.

6. postgres-sandbox prohibido

build-mart --execute debe abortar si detecta postgres-sandbox en:

  • PGHOST
  • PGDATABASE
  • APV_LOCAL_POSTGRES_ADMIN_*
  • APV_BO_LOCAL_POSTGRES_*
  • metadata de conexion o ruta inspeccionada por el importer

Resultado requerido: BLOCKED antes de preparar SQL write.

7. Confirmaciones futuras requeridas

powershell --confirm-local-dev --confirm-build-mart-local-dev --confirm-target-database openclaw_business_observer_dev --confirm-core-source business_observer.core_source_003_sales_items --confirm-mart-daily business_observer.mart_source_003_sales_daily --confirm-mart-seller business_observer.mart_source_003_sales_by_seller --confirm-mart-customer business_observer.mart_source_003_sales_by_customer --confirm-mart-sku business_observer.mart_source_003_sales_by_sku --confirm-batch 1827f887-9499-4579-b4f3-234d54f41f7f --confirm-core-batch-rows 1886 --confirm-mart-daily-empty --confirm-mart-seller-empty --confirm-mart-customer-empty --confirm-mart-sku-empty --confirm-mart-daily-initial-row-count 0 --confirm-mart-seller-initial-row-count 0 --confirm-mart-customer-initial-row-count 0 --confirm-mart-sku-initial-row-count 0 --confirm-candidate-daily-rows 1 --confirm-candidate-seller-rows 25 --confirm-candidate-customer-rows 173 --confirm-candidate-sku-rows 180 --confirm-db-fingerprint "<fingerprint aprobado>"

Sin todas las confirmaciones explicitas, el resultado debe ser BLOCKED.

8. Revalidacion intra-transaccion obligatoria

Dentro de la misma transaccion futura debe volver a validarse:

  • current_database() = openclaw_business_observer_dev
  • CORE batch rows = 1886
  • MART initial = 0/0/0/0
  • estimates = 1/25/173/180
  • output duplicates = 0/0/0/0
  • missing keys seller/customer/sku = 0/0/0

Si cualquiera cambia, debe ejecutarse ROLLBACK.

9. Regla de MART vacia por batch y grain

Debe abortar si existe al menos una fila previa para el mismo:

  • tenant_id
  • sync_batch_id
  • source_query_version
  • grain unico de la tabla destino

Grains protegidos:

  • daily: tenant_id + sync_batch_id + source_query_version + business_date
  • seller: tenant_id + sync_batch_id + source_query_version + period_key + seller_code
  • customer: tenant_id + sync_batch_id + source_query_version + period_key + customer_code
  • sku: tenant_id + sync_batch_id + source_query_version + period_key + sku

10. Idempotencia por batch y grain

Reglas:

  • el batch autorizado no debe duplicar filas en ninguna MART;
  • el mismo batch con mismo contenido debe terminar en BLOCKED o unchanged, nunca en duplicado silencioso;
  • si cambia el set fuente para el mismo batch, resultado BLOCKED;
  • la huella minima debe combinar mart_name, sync_batch_id, source_query_version y source_core_row_hash_set_hash.

11. Orden de inserts obligatorio

  1. mart_source_003_sales_daily
  2. mart_source_003_sales_by_seller
  3. mart_source_003_sales_by_customer
  4. mart_source_003_sales_by_sku

12. Flujo transaccional futuro

  1. resolver fingerprint DB y bloqueo postgres-sandbox fuera de SQL;
  2. abrir una unica transaccion con ON_ERROR_STOP;
  3. revalidar DB, CORE, MART vacia y estimates dentro de la transaccion;
  4. construir datasets candidatos read-only desde CORE;
  5. recalcular source_core_row_hash_set_hash por mart;
  6. validar que no existan duplicados de salida por grain;
  7. insertar daily;
  8. insertar seller;
  9. insertar customer;
  10. insertar sku;
  11. ejecutar post-checks cruzados;
  12. COMMIT solo si todo queda PASS;
  13. ROLLBACK ante cualquier FAIL o BLOCKED.

13. Pre-checks obligatorios antes de escribir

Check Esperado
DB observada openclaw_business_observer_dev
fingerprint coincide
postgres-sandbox ausente
CORE source existe
batch autorizado en CORE 1886 filas
MART targets existen
counts iniciales MART 0/0/0/0 para este batch/grain
candidate rows 1/25/173/180
output duplicates 0/0/0/0
missing keys seller/customer/sku 0/0/0

14. Post-checks obligatorios antes de COMMIT

Check Esperado
daily rows insertadas 1
seller rows insertadas 25
customer rows insertadas 173
sku rows insertadas 180
duplicados por grain 0
row_count_source > 0 en todas las filas insertadas
mart_build_id unico del build 1
source_core_row_hash_set_hash no nulo 0 nulos
sumatoria row_count_source por tabla 1886
reconciliacion importes/unidades vs CORE PASS
sync_enabled false

15. Rollback ante error

  • cualquier error o mismatch debe forzar ROLLBACK;
  • el payload debe informar transaction_committed=false y rollback_executed=true;
  • el estado esperado tras rollback es MART = 0/0/0/0 para el batch;
  • no se permite TRUNCATE;
  • no se permite DELETE como recovery normal de este flujo.

16. Evidencia esperada post-write

  • SAFE POINT inicial y final;
  • comando exacto ejecutado sin secretos;
  • fingerprint observado;
  • confirmaciones recibidas;
  • postgres-sandbox no observado;
  • CORE batch rows = 1886;
  • MART final 1/25/173/180;
  • transaction_committed=true;
  • rollback_executed=false;
  • mart_build_id registrado;
  • source_core_row_hash_set_hash por tabla;
  • conciliacion importes/unidades PASS;
  • salida JSON completa del importer.

17. Estrategia para no habilitar produccion ni sync diaria

  • no reutilizar este gate fuera de local-dev;
  • no aceptar otro fingerprint que no sea el aprobado;
  • no permitir batch dinamico;
  • no invocar runner, scheduler ni OpenClaw executor;
  • no habilitar cron, sync diaria ni rebuild automatico;
  • no declarar production_ready.

18. SQL candidato asociado

Las columnas MART estan claras en el DDL vigente, por lo que se deja un SQL candidato no ejecutado:

docs/tenants/alpuntodeventa/business-observer/design/sql/007_source_003_build_mart_write_path_candidate.sql

Estado:

text CANDIDATE / NOT EXECUTED

19. Prohibiciones preservadas

Sigue prohibido:

  • INSERT
  • COPY
  • UPDATE
  • DELETE
  • ejecutar build-mart --execute real
  • modificar RAW, CORE o MART
  • modificar scripts/source_003_importer.py
  • tocar La Directa
  • tocar runtime O4
  • tocar VPS, Docker, NPM o Portainer
  • push o deploy

20. Decision

text SOURCE-003 BUILD-MART WRITE PATH GATE DOCUMENTADO NO IMPLEMENTADO NO EJECUTADO NO APTO PARA PRODUCCION NO APTO PARA SYNC DIARIA

El flujo futuro de build-mart --execute queda diseniado con fingerprint obligatorio, bloqueo postgres-sandbox, revalidacion intra-transaccion, idempotencia por batch/grain, orden fijo de inserts, rollback total y evidencia post-write esperada. La escritura real sigue bloqueada.