Saltar a contenido

SOURCE-003 Dedicated DB DDL Pilot Package

Fecha: 2026-06-11

Estado: PAQUETE DDL PILOTO PREPARADO / APTO PARA REVISION / NO EJECUTAR

portal_visible = yes

Scope: tenant

tenant_id: alpuntodeventa

Owner: Gabi / Carlos Canu

Fuente de verdad: docs/tenants/alpuntodeventa/business-observer/design/SOURCE-003-DEDICATED-DB-DDL-PILOT-PACKAGE.md

1. Objetivo

Preparar un paquete DDL piloto revisable para SOURCE-003 / Tabla 2 V2 en la base local dedicada openclaw_business_observer_dev, sin ejecutar SQL, sin crear tablas y sin cargar datos.

El paquete baja a archivos revisables el gate publicado en SOURCE-003-DEDICATED-DB-DDL-PILOT-GATE.md.

2. Alcance

Incluye:

  • DDL forward piloto para business_observer.source_003_sales_items
  • rollback/drop piloto acotado
  • validaciones post-DDL de estructura, owners, grants y ausencia de datos
  • grants explicitos para openclaw_bo_writer y openclaw_bo_reader
  • preservacion de las 68 columnas reales aprobadas por diccionario y mapping
  • campos tecnicos de trazabilidad, line_key_v4, line_sequence_v1 y source_row_hash_v1

No incluye:

  • ejecutar SQL
  • ejecutar DDL
  • crear tablas reales
  • insertar datos
  • cargar SOURCE-003
  • migrar las 9761 filas del piloto legacy
  • tocar gestion_de_negocios_core
  • tocar VPS, Docker, OpenClaw, NPM o sync diaria

3. Safe point inicial

Control Resultado
rama main
git status -sb ## main...origin/main
git rev-parse HEAD 2ddcaf765cbbefe54de91945eea0b9749a682238
git ls-remote origin main 2ddcaf765cbbefe54de91945eea0b9749a682238
decision SAFE POINT PASS

4. Documentos leidos

Read-set obligatorio aplicado:

  • docs/governance/PROJECT-CONSTITUTION.md
  • CODEX.md
  • docs/governance/ACTIVE-CONTEXT.md
  • docs/governance/GATE-CODEX-EFFICIENCY.md
  • docs/governance/GOVERNANCE-CONTROL-TOWER.md
  • docs/governance/VALIDATION-STATE.md
  • docs/governance/documentation/DOCUMENT-HIERARCHY.md
  • docs/PROJECT-STATE.md
  • docs/ROADMAP.md
  • docs/governance/operations/CURRENT-BASELINE.md
  • docs/tenants/alpuntodeventa/business-observer/README.md
  • docs/tenants/alpuntodeventa/business-observer/design/POSTGRES-LOCAL-DEV-ENVIRONMENT.md
  • docs/tenants/alpuntodeventa/business-observer/design/SOURCE-003-CREDENTIALS-PREFLIGHT.md
  • docs/tenants/alpuntodeventa/business-observer/design/SOURCE-003-DEDICATED-DB-DDL-PILOT-GATE.md

Documentos vigentes de SOURCE-003 revisados:

  • sources/SOURCE-003-SGC-VENTAS-COMPROBANTES.md
  • source-authority/SOURCE-AUTHORITY-REGISTRY.md
  • source-authority/SOURCE-003-VENTAS-TABLA2-AUTHORITY.sql
  • source-authority/SOURCE-003-VENTAS-VNEXT-TABLA2-AUTHORITY.sql
  • source-authority/SOURCE-003-VENTAS-VNEXT-TABLA2-AUTHORITY-V2.sql
  • source-authority/SOURCE-003-QUERY-DELTA-REVIEW.md
  • SOURCE-INVENTORY-RESULTS-003.md
  • SOURCE-003-DRIFT-ANALYSIS-001.md
  • SOURCE-003-SNAPSHOT-001.md
  • data-dictionary/SOURCE-003-TABLA2-COLUMN-DICTIONARY.md
  • design/SOURCE-003-SALES-ITEMS-COLUMN-MAPPING.md
  • design/SOURCE-003-LINE-IDENTITY-DECISION.md
  • design/SOURCE-003-SALES-ITEMS-DDL-DESIGN.md
  • design/SOURCE-003-SALES-ITEMS-PILOT-MIGRATION.md
  • design/SOURCE-003-SALES-ITEMS-PILOT-LOAD-001.md
  • design/SOURCE-003-SALES-ITEMS-WINDOW-PILOT-001.md
  • design/sql/001_source_003_sales_items_design.sql
  • design/sql/002_source_003_sales_items_pilot_migration.sql
  • design/sql/002_source_003_sales_items_pilot_rollback.sql

Clasificacion operativa: DESIGN + VALIDATE.

5. Estado DB dedicado

La verificacion directa de DB en vivo no fue reejecutada en esta tarea porque era opcional y no necesaria para preparar el paquete documental.

Se toma como evidencia vigente el gate publicado:

docs/tenants/alpuntodeventa/business-observer/design/POSTGRES-LOCAL-DEV-ENVIRONMENT.md

Estado documentado vigente:

Control Estado vigente
database openclaw_business_observer_dev CREADA / VALIDADA
schema business_observer CREADO / OWNER VALIDADO
roles openclaw_bo_admin, openclaw_bo_writer, openclaw_bo_reader CREADOS / NOLOGIN
grants minimos VALIDADOS
default privileges futuros CONFIGURADOS
tablas en schema dedicado 0
SOURCE-003 cargado en DB dedicada NO
gestion_de_negocios_core modificado por esta tarea NO

6. Archivos del paquete

Archivo Rol Ejecutar ahora
design/sql/003_source_003_dedicated_db_ddl_pilot_preflight.sql preflight solo lectura para gate futuro NO
design/sql/003_source_003_dedicated_db_ddl_pilot_forward.sql DDL forward piloto revisable NO
design/sql/003_source_003_dedicated_db_ddl_pilot_rollback.sql rollback/drop acotado NO
design/sql/003_source_003_dedicated_db_ddl_pilot_post_checks.sql validaciones post-DDL futuras NO

7. Resumen del DDL forward

El DDL forward propone:

  • guard hard de current_database() antes de cualquier DDL
  • asegurar schema business_observer
  • owner esperado openclaw_bo_admin
  • tabla business_observer.source_003_sales_items
  • 83 columnas fisicas esperadas: 68 columnas de negocio aprobadas, columnas tecnicas y descuento_item preservado por compatibilidad del piloto local previo
  • primary key (id)
  • unique (tenant_id, line_key)
  • line_key como line_key_v4
  • line_sequence_v1 como secuencia tecnica de pipeline
  • source_row_hash como source_row_hash_v1 sobre las 68 columnas reales
  • indices minimos por fecha, cliente, vendedor, SKU, documento, batch, estado y hash
  • checks no destructivos de campos criticos, formato HHMMSS y estados permitidos
  • comentarios SQL sobre identidad, sensibilidad y riesgo
  • grants post-DDL: writer = SELECT, INSERT, UPDATE sin DELETE; reader = SELECT sin escritura
  • revocacion explicita de permisos a PUBLIC sobre schema y tabla

No incluye:

  • INSERT
  • UPDATE
  • DELETE
  • UPSERT
  • carga desde snapshot
  • carga desde SGC
  • hard delete
  • missing_from_source
  • sync diaria
  • operaciones fuera de business_observer

8. Preflight futuro

El archivo de preflight es de solo lectura y valida por catalogo:

  • current_database() = openclaw_business_observer_dev
  • existencia de schema business_observer
  • owner esperado de schema
  • existencia de openclaw_bo_admin, openclaw_bo_writer y openclaw_bo_reader
  • roles requeridos en estado NOLOGIN
  • scope declarado limitado a business_observer
  • ausencia de carga de datos y ausencia de cambios de objetos en el propio preflight

9. Validaciones post-DDL futuras

El archivo de post-checks valida por catalogo:

  • database actual esperada
  • existencia de schema
  • tabla creada
  • owner de schema y tabla
  • cantidad de columnas
  • tabla vacia con 0 filas
  • constraints requeridas
  • indices requeridos
  • roles NOLOGIN
  • writer con SELECT, INSERT, UPDATE y sin DELETE
  • reader con SELECT y sin INSERT, UPDATE, DELETE
  • PUBLIC sin permisos sobre schema ni tabla
  • roles no objetivo sin permisos explicitos indebidos sobre schema ni tabla
  • default privileges futuros configurados para objetos creados por openclaw_bo_admin
  • default privileges futuros esperados para writer y reader
  • default privileges futuros sin DELETE para writer
  • default privileges futuros sin escritura para reader

Todos los controles criticos agregan columna pass para decision PASS/FAIL; la ACL observada de default privileges se conserva solo como evidencia complementaria.

10. Como revisar

Revision recomendada:

  1. leer primero este documento
  2. revisar el preflight sin ejecutarlo todavia
  3. comparar el forward contra SOURCE-003-SALES-ITEMS-COLUMN-MAPPING.md
  4. verificar que las 68 columnas reales esten contempladas
  5. revisar que line_key_v4, line_sequence_v1 y source_row_hash_v1 preserven la decision AMARILLO ACEPTADO
  6. revisar grants de writer, reader, PUBLIC y roles no objetivo
  7. revisar que el rollback no borre el schema ni roles
  8. revisar que los post-checks no contengan DDL ni DML

11. Que no ejecutar todavia

No ejecutar todavia:

  • 003_source_003_dedicated_db_ddl_pilot_preflight.sql
  • 003_source_003_dedicated_db_ddl_pilot_forward.sql
  • 003_source_003_dedicated_db_ddl_pilot_rollback.sql
  • 003_source_003_dedicated_db_ddl_pilot_post_checks.sql
  • ningun extractor de SOURCE-003
  • ninguna carga desde snapshots
  • ninguna sync diaria

12. Riesgos

Riesgo Mitigacion documental
line_key_v4 no es id fisico ERP mantener estado AMARILLO ACEPTADO; apta para piloto analitico, no identidad legal perfecta
fuente viva cargar solo con snapshot/gate futuro, source_row_hash y ventana movil aprobada
multiples resultsets V2 extractor futuro debe forzar Tabla2=1 y Tabla1/3/4/5/6=0
datos personales/logisticos no exponer vistas de consumo sin controles posteriores
checks demasiado duros no bloquear negativos, CMV cero ni notas de credito
permisos heredados o accidentales post-checks con PASS/FAIL para PUBLIC, roles no objetivo y default privileges futuros
ejecucion prematura paquete marcado NO EJECUTAR, guard hard de DB y sin datos

13. Rollback

El rollback propuesto:

  • falla si la database actual no es openclaw_business_observer_dev
  • elimina los 8 indices piloto si existen
  • elimina business_observer.source_003_sales_items si existe
  • no elimina business_observer
  • no elimina roles
  • no elimina default privileges
  • no toca otras tablas

Antes de usarlo en una tarea futura debe existir aprobacion humana explicita y evidencia de backup o estado inicial.

14. Criterios para futuro gate de ejecucion

Antes de ejecutar este paquete en una tarea futura se requiere:

  1. aprobacion humana explicita para ejecutar DDL
  2. safe point Git nuevo
  3. confirmacion de DB dedicada y schema en estado esperado
  4. ejecucion humana autorizada del preflight
  5. backup o evidencia de estado inicial de la DB dedicada
  6. revision final de owner, grants y default privileges
  7. ejecucion del forward en transaccion
  8. ejecucion de post-checks
  9. documentacion de resultado
  10. decision posterior separada antes de cualquier carga de datos

15. Decision

Decision del paquete:

text APTO PARA REVISION

Lectura exacta:

  • apto para revision humana
  • apto como paquete documental de DDL piloto
  • SOURCE-003 V2 sigue como candidata/revalidada para piloto analitico
  • line_key_v4 sigue en AMARILLO ACEPTADO, no identidad legal perfecta
  • no apto para ejecucion automatica
  • no apto para carga piloto
  • no apto para sync diaria
  • no apto para carga masiva
  • no apto para produccion final

16. Validaciones documentales

Validaciones requeridas para cerrar esta tarea:

  • git diff --check
  • mkdocs build --strict

Resultado: PASS en git diff --check y mkdocs build --strict.