SOURCE-003 Raw DDL Candidate Technical Review

Fecha local: 2026-06-15

Estado: REVISION TECNICA DOCUMENTAL / DDL RAW 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-RAW-DDL-CANDIDATE-TECHNICAL-REVIEW.md

1. Objetivo

Revisar tecnicamente el paquete DDL RAW candidato de SOURCE-003 sin ejecutarlo.

Archivos revisados:

• SOURCE-003-RAW-DDL-CANDIDATE.md
• sql/004_source_003_raw_ddl_candidate_preflight.sql
• sql/004_source_003_raw_ddl_candidate_forward.sql
• sql/004_source_003_raw_ddl_candidate_rollback.sql
• sql/004_source_003_raw_ddl_candidate_post_checks.sql
• SOURCE-003-RAW-LAYER-CONTRACT.md
• SOURCE-003-IMPORTER-LOAD-RAW-PLAN.md
• SOURCE-003-LOAD-RAW-TECHNICAL-REVIEW.md

Esta revision no ejecuto SQL, no uso psql, no toco PostgreSQL, no creo tablas, no modifico Python, no ejecuto runner, no genero CSV, no toco Docker, VPS, OpenClaw, NPM, push ni deploy.

2. Veredicto ejecutivo

text APTO PARA EJECUCION LOCAL-DEV NO APTO PARA PRODUCCION NO APTO PARA IMPLEMENTAR LOAD-RAW TODAVIA

Lectura exacta:

• APTO PARA EJECUCION LOCAL-DEV significa apto solo como DDL candidato para una futura tarea separada, con SAFE POINT nuevo, fingerprint DB, aprobacion humana explicita, ejecucion manual controlada y post-checks.
• NO APTO PARA PRODUCCION porque no existe contrato productivo de entorno, RLS, particion/retencion, observabilidad, backup/restore productivo, dependencias core/mart, operacion ni rollback por batch productivo.
• NO APTO PARA IMPLEMENTAR LOAD-RAW TODAVIA porque faltan precondiciones distintas de cero: el DDL no fue ejecutado ni validado en DB, no existe fingerprint de ejecucion aprobado, no existe staging fisico ni politica final de idempotencia para batch existente/inter-batch.

3. Hallazgos tecnicos

Area	Resultado	Observacion
Tabla RAW candidata	OK	business_observer.raw_source_003_sales_items separa correctamente la futura RAW de la tabla piloto.
Tabla piloto	OK	business_observer.source_003_sales_items queda clasificada como PILOTO, no RAW final.
Metadata RAW obligatoria	OK	Incluye tenant_id, source_system, source_object, source_query_version, source_row_hash, sync_batch_id, extracted_at, loaded_at y record_status.
Columnas prepared CSV	OK CON RIESGO	El forward preserva las 83 columnas del prepared CSV y suma loaded_at, total fisico 84. Riesgo residual: divergencia futura header CSV vs DDL si no se congela manifest antes de carga.
Clave tecnica id	OK	id uuid NOT NULL PRIMARY KEY; no se usa como identidad funcional.
Clave logica	OK	UNIQUE (tenant_id, sync_batch_id, line_key) protege reintentos dentro del mismo batch.
Constraints	OK	Cubre no vacios criticos, estado permitido, secuencia positiva, hora HHMMSS e identidad documental minima.
Indices	OK CON OBSERVACION	Cubren batch, hash, fecha, cliente, vendedor, SKU, documento y estado. El indice tenant_id, sync_batch_id, line_key duplica en parte el indice creado por la constraint unique; no bloquea local-dev.
Ownership/grants	OK	Owner openclaw_bo_admin, writer con SELECT/INSERT/UPDATE, reader con SELECT.
PUBLIC sin privilegios	OK	Forward revoca schema y tabla; preflight/post-checks validan privilegios de schema/tabla.
Writer sin DELETE	OK	DELETE, TRUNCATE, REFERENCES y TRIGGER quedan revocados para writer.
Preflight	OK	Es solo lectura de catalogo, valida database esperada, schema, roles, tabla RAW ausente y PUBLIC sin privilegios sobre schema.
Forward	OK	Crea tabla, constraints, indices, comments, owner y grants; no inserta datos.
Rollback	OK	Aborta si la tabla existe y tiene filas; no usa TRUNCATE, no borra datos y no toca la tabla piloto.
Post-checks	OK	Exigen tabla creada, owner, 84 columnas, constraints, indices, row_count exacto 0, grants y separacion del piloto.

4. Riesgos detectados

Riesgos bloqueantes para produccion:

• postgres-sandbox no puede interpretarse como produccion del Business Observer. La evidencia vigente solo permite leerlo como sandbox.
• No hay contrato productivo de base, host, backup, restore, RLS, observabilidad, retencion, particion ni operacion diaria.
• No hay dependencias core/mart implementadas ni reglas de reversa si la RAW se promociona a capas superiores.

Riesgos no bloqueantes para ejecucion local-dev controlada:

• La paridad CSV vs DDL depende de mantener congelado el header de 83 columnas preparado. La RAW agrega loaded_at, por lo que cualquier futuro COPY debe mapear columnas explicitamente y no asumir SELECT * ni orden fisico completo.
• La diferencia historica 82/83 entre prepared validado y generated queda acotada a id; antes de cargar RAW debe quedar aceptada o revalidada la formula final de id.
• La constraint unique protege tenant_id + sync_batch_id + line_key, pero no impide que el mismo line_key aparezca en batches distintos. Esto es correcto para RAW historizada, pero exige politica de promocion a core.
• tenant_id + sync_batch_id + source_row_hash esta documentada como clave de auditoria candidata, pero no se define como unique. Es aceptable para RAW local-dev, aunque debe decidirse antes de idempotencia productiva.
• El indice explicito tenant_id, sync_batch_id, line_key es redundante con la unique constraint. No bloquea, pero puede revisarse si se busca menor costo fisico.

5. Precondiciones antes de ejecutar local-dev

Antes de cualquier ejecucion futura en openclaw_business_observer_dev:

• SAFE POINT nuevo con rama limpia, HEAD esperado y origin/main alineado.
• Aprobacion humana explicita para ejecutar solo este paquete.
• Fingerprint DB esperado documentado y validado.
• Confirmar que el destino es local-dev o DB dedicada aprobada, nunca postgres-sandbox como produccion.
• Ejecutar primero preflight y exigir PASS antes de forward.
• Ejecutar post-checks despues del forward y exigir row_count = 0.
• Mantener bloqueado load-raw aunque el DDL pase.

6. Conclusion

text APTO PARA EJECUCION LOCAL-DEV NO APTO PARA PRODUCCION NO APTO PARA IMPLEMENTAR LOAD-RAW TODAVIA

El paquete DDL RAW candidato de SOURCE-003 es tecnicamente consistente para una ejecucion local-dev futura y separada. La separacion con la tabla piloto esta bien protegida, la metadata RAW obligatoria esta cubierta, las claves y permisos son razonables, el rollback aborta ante filas y los post-checks conservan row_count = 0.

Produccion y load-raw siguen bloqueados. La proxima tarea, si se aprueba, debe ser una ejecucion local-dev del DDL bajo gate explicito, no una carga de datos ni una implementacion del importer.