Saltar a contenido

SOURCE-003 Load Raw Write Path Implementation 001

Fecha local: 2026-06-15

Estado: RUTA WRITE FUTURA PREPARADA / EJECUCION BLOQUEADA / SIN CARGA

portal_visible = yes

Scope: tenant

tenant_id: alpuntodeventa

Owner: Gabi / Carlos Canu

Fuente de verdad: docs/tenants/alpuntodeventa/business-observer/design/SOURCE-003-LOAD-RAW-WRITE-PATH-IMPLEMENTATION-001.md

1. Objetivo

Preparar en scripts/source_003_importer.py la ruta real futura de escritura para:

powershell python scripts/source_003_importer.py load-raw --execute

Esta tarea no ejecuta carga real, no ejecuta confirmaciones completas, no escribe datos, no invoca runner, no ejecuta rollback, no genera CSV y no toca VPS, Docker, OpenClaw, NPM ni Portainer.

2. Safe point

Control Resultado
workspace C:\APV\openclawai
rama main
HEAD inicial 7accb5957010597d2c828ebb3b5aeb48d64e318b
ultimo commit inicial docs: review source 003 load raw execute gate
decision SAFE POINT PASS

3. Implementacion

load-raw conserva el resultado esperado DRY_RUN.

load-raw --execute conserva el resultado esperado BLOCKED cuando no recibe confirmaciones explicitas. Aunque la ruta futura queda documentada en el payload, esta tarea no habilita INSERT, COPY, UPDATE, DELETE, COMMIT ni rollback real.

Confirmaciones futuras minimas modeladas:

  • --confirm-local-dev;
  • --confirm-write-local-dev;
  • --confirm-batch 1827f887-9499-4579-b4f3-234d54f41f7f;
  • --confirm-raw-empty;
  • --confirm-row-count 1886;
  • --confirm-target-table business_observer.raw_source_003_sales_items.

El gate conserva confirmaciones redundantes adicionales para tenant, source, database, columnas, hashes y fingerprint DB.

4. Ruta futura modelada

Control Valor
DB permitida openclaw_business_observer_dev
tabla destino business_observer.raw_source_003_sales_items
batch 1827f887-9499-4579-b4f3-234d54f41f7f
filas esperadas 1886
columnas destino 84
RAW inicial row_count = 0
post-check esperado 1886 filas del batch
fingerprint obligatorio y aprobado
postgres-sandbox prohibido
duplicate batch BLOCKED antes de escribir
loaded_at resuelto de forma gobernada en DB

Politica loaded_at modelada:

text loaded_at se resuelve dentro de PostgreSQL por default de la columna destino o por statement_timestamp() transaccional; el CSV no es autoridad para loaded_at.

5. Transaccion futura

Plan futuro preparado, no ejecutado:

text BEGIN revalidar fingerprint DB en la misma sesion revalidar current_database() = openclaw_business_observer_dev revalidar target = business_observer.raw_source_003_sales_items revalidar RAW total row_count = 0 bloquear si el batch autorizado ya existe en RAW cargar CSV validado a staging controlado validar staging row_count = 1886 validar batch, line_key, source_row_hash y duplicados resolver loaded_at con politica DB gobernada insertar en RAW solo si todos los checks pasan post-check RAW batch rows = 1886 COMMIT solo si todos los checks pasan ROLLBACK ante cualquier error antes del COMMIT

6. Seguridad

Resultado esperado:

json { "data_written": false, "sync_enabled": false }

Bloqueos preservados:

  • carga real;
  • confirmaciones completas ejecutadas;
  • INSERT, COPY, UPDATE, DELETE, TRUNCATE, COMMIT;
  • runner;
  • rollback real;
  • generacion de CSV;
  • VPS, Docker, OpenClaw, NPM, Portainer;
  • push y deploy.

7. Validaciones requeridas

text python -m py_compile scripts/source_003_importer.py python scripts/source_003_importer.py --help python scripts/source_003_importer.py load-raw python scripts/source_003_importer.py load-raw --execute python scripts/source_003_importer.py dry-run git diff --check .venv-portal\Scripts\mkdocs.exe build --strict

Resultado de validaciones:

Comando Resultado
python -m py_compile scripts/source_003_importer.py PASS
python scripts/source_003_importer.py --help PASS
python scripts/source_003_importer.py load-raw DRY_RUN
python scripts/source_003_importer.py load-raw --execute BLOCKED
python scripts/source_003_importer.py dry-run PASS
git diff --check PASS
.venv-portal\Scripts\mkdocs.exe build --strict PASS

Resultado observado de load-raw:

json { "result": "DRY_RUN", "candidate_rows": 1886, "target_database": "openclaw_business_observer_dev", "target_table": "business_observer.raw_source_003_sales_items", "data_written": false, "sync_enabled": false }

Resultado observado de load-raw --execute sin confirmaciones:

json { "result": "BLOCKED", "data_written": false, "sync_enabled": false, "blocked_actions": ["INSERT", "COPY", "UPDATE", "DELETE", "TRUNCATE", "COMMIT"] }

8. Decision

text SOURCE-003 LOAD-RAW WRITE PATH PREPARADO PARA FUTURA TAREA LOCAL-DEV LOAD-RAW SIGUE DRY_RUN LOAD-RAW --EXECUTE SIN CONFIRMACIONES SIGUE BLOCKED SIN CARGA REAL SIN ESCRITURA DB SIN SYNC