Saltar a contenido

Business Observer - Al Punto de Venta

Scope: tenant
tenant_id: alpuntodeventa
Owner: Gabi / Carlos Canu
Estado: definicion documental con inventario real iniciado
Fuente de verdad: docs/tenants/alpuntodeventa/business-observer/README.md portal_visible = yes

Autoridad funcional principal: docs/tenants/alpuntodeventa/business-observer/BUSINESS-OBSERVER-GOVERNANCE-MODEL.md

Que es

Este espacio documenta el Business Observer del tenant alpuntodeventa.

Su objetivo es ordenar, en lenguaje simple, como APV quiere usar el observer para leer riesgo comercial, crecimiento y prioridades de accion.

La capa Customer Ownership Analytics agrega la lectura conceptual de quien trabaja realmente cada cliente sin reemplazar la cartera formal ni la autoria real de las ventas.

La capa Blueprints define los dominios funcionales principales del Business Observer APV antes de tablas, SQL, migraciones o implementacion.

Blueprints funcionales vigentes:

Visibilidad en Knowledge Portal

Este espacio tenant queda clasificado como portal_visible = yes para su overview, governance funcional, blueprints principales, contratos de datos y evidencia relevante.

Criterio local:

  • Business Observer README, governance model y blueprints principales: portal_visible = yes
  • contratos funcionales de datos: portal_visible = yes
  • disenos estables y evidencia relevante: portal_visible = yes o portal_visible = technical_reference, segun funcion documental
  • SQL de autoridad de fuentes: portal_visible = technical_reference o portal_visible = internal_only, segun sensibilidad y necesidad de soporte
  • change packets: portal_visible = pending_review o portal_visible = internal_only
  • runtime, seguridad, credenciales o detalle operativo sensible: portal_visible = internal_only

Regla critica vigente para SOURCE-003:

  • el piloto dedicado de SOURCE-003 queda cerrado como hito VERDE publicado: DDL ejecutado VERDE, CSV preparado VERDE, candidate load VERDE, post-checks VERDE, 1886 filas cargadas y batch 1827f887-9499-4579-b4f3-234d54f41f7f
  • la evidencia publica vive en SOURCE-003 Pilot Load Execution 002
  • la validacion DB controlada del runner quedo registrada en SOURCE-003 Runner Preflight DB 001: el runner conecto, valido fingerprint y ejecuto el preflight autorizado, pero el resultado funcional correcto es PREFLIGHT BLOQUEADO / TABLA NO VACIA ESPERADA POR PILOTO YA CARGADO
  • la validacion DB read-only de status quedo registrada en SOURCE-003 Runner Status DB 001: el runner valido fingerprint y ejecuto el SQL autorizado de post-checks con PASS, 1886 filas del batch 1827f887-9499-4579-b4f3-234d54f41f7f, sin modificar datos
  • la semantica vigente del runner separa explicitamente: preflight-before-load como gate estricto de tabla vacia y status / verify-existing-pilot como verificacion read-only del piloto ya cargado; post-checks queda como alias legacy de status y ningun PASS de lectura habilita escritura
  • sync diaria, carga masiva y produccion final siguen BLOQUEADAS
  • el proximo frente recomendado es automatizar en Python el flujo reproducible raw -> prepared CSV; el generador ya existe con resultado REPRODUCIBLE ESTRUCTURAL / SHA DIFERENTE por diferencia acotada a id, y ya existe tambien un runner Python controlado para la futura orquestacion preflight/status -> candidate load -> post-checks -> rollback, pero con modos de escritura bloqueados en esta revision porque la tabla dedicada ya tiene 1886 filas del batch piloto verde; tambien existe el primer skeleton del Python importer formal en SOURCE-003 Python Importer Skeleton 001, con inspect-source implementado como inspeccion local read-only de raw snapshot y prepared CSV: PASS, raw sha256 07092c284b5b636b8a31cd616ef5b4fa5d0ce499b81c767437842b1f7edfcbc3, prepared sha256 3f16a957a79fc84d4ca37930988287cb81f05166210d057fcf8b45007f184afe, 1886 filas, 83 columnas, batch 1827f887-9499-4579-b4f3-234d54f41f7f, fecha unica 2026-06-09, record_status = active, CSV preparado fuera de Git, sin DB, sin SQL, sin runner y sin datos escritos; validate-prepared queda tambien implementado como validacion local read-only del prepared historico y generated existente: ambos CSV fuera de Git, SHA256 esperados, 1886 filas, 83 columnas, batch 1827f887-9499-4579-b4f3-234d54f41f7f, fecha unica 2026-06-09, record_status = active, source_row_hash y line_key no vacios, y comparacion REPRODUCIBLE ESTRUCTURAL ACEPTADO con 82/83 columnas coincidentes y diferencia esperada en id; cualquier nueva lectura DB debe distinguir entre preflight-before-load y status, y cualquier nueva ejecucion real sigue requiriendo un gate separado; clientes y productos siguen no iniciados
  • el plan controlado para el futuro load-raw del importer queda documentado en SOURCE-003 Importer Load Raw Plan: define alcance futuro solo para local-dev o DB dedicada, precondiciones, fingerprint DB, batch explicito, target table gobernada, staging, transaccion, idempotencia, deduplicacion, rollback por batch, logs, auditoria, riesgos y criterios de aceptacion; decision LOAD-RAW PLAN DOCUMENTADO / NO IMPLEMENTADO / NO EJECUTABLE; no implementa Python, no toca PostgreSQL, no ejecuta SQL, no crea DDL, no genera CSV y no habilita sync diaria, carga masiva, produccion, OpenClaw executor ni jobs automaticos
  • la revision tecnica documental del contrato load-raw queda publicada en SOURCE-003 Load Raw Technical Review: confirma que el plan respeta el contrato RAW, preserva separacion raw / core / mart, bloquea postgres-sandbox como produccion y deja recomendacion final APTO PARA DISENAR DDL RAW / NO APTO PARA IMPLEMENTAR LOAD-RAW TODAVIA; no implementa Python, no crea DDL, no ejecuta SQL, no toca PostgreSQL y mantiene bloqueados sync diaria, carga masiva, produccion y OpenClaw executor
  • el paquete DDL RAW candidato queda publicado en SOURCE-003 Raw DDL Candidate: propone business_observer.raw_source_003_sales_items, aclara que business_observer.source_003_sales_items es PILOTO y no RAW final, incluye columnas del prepared CSV mas metadata RAW obligatoria loaded_at, clave tecnica id, clave logica por batch tenant_id + sync_batch_id + line_key, constraints, indices, owner, grants, rollback que aborta si hay filas y post-checks con row_count = 0; no se ejecuto SQL, no se toco PostgreSQL, no se creo tabla real, no se modifico Python y no se habilita load-raw
  • la revision tecnica del paquete DDL RAW candidato queda publicada en SOURCE-003 Raw DDL Candidate Technical Review: resultado APTO PARA EJECUCION LOCAL-DEV / NO APTO PARA PRODUCCION / NO APTO PARA IMPLEMENTAR LOAD-RAW TODAVIA; confirma separacion con tabla piloto, metadata RAW obligatoria, columnas prepared CSV mas loaded_at, clave tecnica id, clave logica por batch, constraints, indices, ownership/grants, PUBLIC sin privilegios, writer sin DELETE, preflight, forward, rollback y post-checks; no se ejecuto SQL, no se toco PostgreSQL, no se creo tabla real, no se modifico Python, no se genero CSV y no se habilita carga de datos
  • el forward DDL RAW local-dev queda ejecutado y publicado en SOURCE-003 Raw DDL Local Dev Forward 001: preflight PASS, forward OK y post-checks PASS contra openclaw_business_observer_dev; la tabla business_observer.raw_source_003_sales_items queda creada vacia con row_count = 0, owner openclaw_bo_admin, 84 columnas, 21 constraints, 9 indices, writer sin DELETE, reader read-only y PUBLIC sin privilegios; no se cargo dato, no se toco Python, no se ejecuto runner/importer load-raw, no se genero CSV y produccion sigue bloqueada
  • el plan del futuro promote-core queda documentado en SOURCE-003 Importer Promote Core Plan: define la promocion futura desde business_observer.raw_source_003_sales_items hacia la tabla candidata business_observer.core_source_003_sales_items, limitada al batch 1827f887-9499-4579-b4f3-234d54f41f7f, con reglas de normalizacion, tipos, claves logicas, idempotencia, deduplicacion, rollback/rebuild por batch, validaciones pre/post y relacion futura con mart; decision PROMOTE-CORE PLAN DOCUMENTADO / NO IMPLEMENTADO / NO EJECUTADO, apto para disenar DDL CORE candidato, no apto para produccion ni sync diaria
  • el forward DDL CORE local-dev queda ejecutado y publicado en SOURCE-003 Core DDL Local Dev Forward 001: preflight PASS, forward OK y post-checks PASS contra openclaw_business_observer_dev; la tabla business_observer.core_source_003_sales_items queda creada vacia con row_count = 0, owner openclaw_bo_admin, 66 columnas, 22 constraints, 10 indices, writer sin DELETE, reader read-only y PUBLIC sin privilegios; RAW conserva el batch autorizado de 1886 filas segun preflight y no hubo escrituras contra RAW ni tabla piloto; no se cargo dato, no se toco Python, no se ejecuto promote-core, runner/importer ni CSV, y produccion sigue bloqueada
  • el gate documental para el futuro promote-core --execute local-dev queda publicado en SOURCE-003 Promote Core Local Dev Execution Gate: define DB permitida openclaw_business_observer_dev, RAW source business_observer.raw_source_003_sales_items, CORE target business_observer.core_source_003_sales_items, batch 1827f887-9499-4579-b4f3-234d54f41f7f, RAW batch rows = 1886, CORE row_count inicial = 0, 1886 filas esperadas a promover, 66 columnas CORE, fingerprint DB obligatorio, postgres-sandbox prohibido, confirmaciones futuras, transformacion RAW -> CORE, idempotencia, bloqueo por batch duplicado, transaccion, validaciones pre/post, rollback/rebuild por batch, evidencia minima y criterio PASS/FAIL/BLOCKED; decision documental GATE PROMOTE-CORE DOCUMENTADO / NO EJECUTADO, no apto para produccion ni sync diaria
  • el gate execute del importer queda implementado y publicado en SOURCE-003 Promote Core Execute Gate Implementation 001: promote-core sigue DRY_RUN; promote-core --execute exige confirmaciones explicitas y queda BLOCKED si faltan o son incompletas; preserva db_write=false, data_written=false, sync_enabled=false, sin modificar RAW, sin cargar CORE, sin runner, sin CSV, sin rollback real, sin VPS, Docker, OpenClaw, NPM, Portainer, push ni deploy
  • la ruta futura de escritura del importer queda preparada y publicada en SOURCE-003 Promote Core Write Path Implementation 001: promote-core sigue DRY_RUN y promote-core --execute sigue BLOCKED; future_write_path documenta fingerprint obligatorio, bloqueo postgres-sandbox, bloqueo de batch duplicado CORE, transaccion futura, idempotencia, post-check CORE batch rows = 1886, preservacion de source_row_hash y line_key, timestamps gobernados y rollback/rebuild, con write_path_enabled=false, data_written=false y sync_enabled=false
  • el write real local-dev del importer queda implementado y publicado en SOURCE-003 Promote Core Write Implementation 001: no se ejecutaron confirmaciones completas; la ruta queda detras de write_path_enabled=true, con transaccion RAW -> CORE, INSERT controlado en CORE, sin modificar RAW, bloqueo por batch duplicado, rollback automatico ante error, fingerprint obligatorio, postgres-sandbox prohibido, id CORE deterministico gobernado y timestamps gobernados; data_written=false, sync_enabled=false y CORE conserva row_count = 0
  • la promocion real local-dev queda ejecutada y publicada en SOURCE-003 Promote Core Local Dev Execution 001: PASS, inserted_rows=1886, CORE total/batch 1886, RAW batch preservado en 1886, duplicados CORE 0, claves y hashes completos, timestamps no nulos, idempotencia BLOCKED sin nuevas filas, sync_enabled=false y produccion false; no se modifico RAW ni MART, no se genero CSV, no hubo runner, VPS, Docker, OpenClaw, NPM, Portainer, push ni deploy
  • el plan del futuro build-mart queda documentado en SOURCE-003 Importer Build Mart Plan: define el flujo futuro desde business_observer.core_source_003_sales_items, batch 1827f887-9499-4579-b4f3-234d54f41f7f, con MART V1 candidato para ventas por dia, vendedor, cliente, SKU/producto, zona/territorio si aplica y rentabilidad/CMV si aplica; decision BUILD-MART PLAN DOCUMENTADO / NO IMPLEMENTADO / NO EJECUTADO, apto para disenar DDL MART candidato, no apto para produccion ni sync diaria
  • build-mart queda implementado en safe mode y publicado en SOURCE-003 Importer Build Mart Safe Mode 001: python scripts/source_003_importer.py build-mart devuelve DRY_RUN, valida fingerprint DB aprobado, CORE batch 1886, las cuatro MART en 0 filas y agrega estimaciones 1 diario, 25 por vendedor, 173 por cliente y 180 por SKU; build-mart --execute devuelve BLOCKED, db_write=false, data_written=false, sync_enabled=false
  • el paquete DDL CORE candidato queda publicado en SOURCE-003 Core DDL Candidate: propone business_observer.core_source_003_sales_items como capa de negocio normalizada desde business_observer.raw_source_003_sales_items, con clave tecnica id, claves de trazabilidad tenant_id, sync_batch_id, line_key y source_row_hash, 66 columnas, 22 constraints, 10 indices, owner openclaw_bo_admin, PUBLIC sin privilegios, writer sin DELETE, rollback que aborta si hay filas y post-checks con row_count = 0; no se ejecuto SQL, no se toco PostgreSQL, no se modifico Python y no se cargo data
  • la autoridad anterior de ventas queda preservada sin reemplazo
  • la nueva query completa de ventas queda documentada como vNext candidate
  • Tabla 2 queda como salida canonica futura de sync itemizada
  • Tabla 1/3/4/5/6 quedan como referencias de calculo ERP y conciliacion
  • SOURCE-003 / SGC Ventas es fuente viva: una fecha ya cargada puede cambiar aproximadamente hasta 7 dias hacia atras por entregas, rechazos, cobros, descuentos, notas de credito, anulaciones, refacturacion o ajustes de cuenta corriente
  • la sync futura no debe usar incremental simple por ultima fecha cargada
  • la estrategia recomendada combina carga historica inicial, snapshot diario, ventana movil inicial de 10 dias, upsert por tenant_id + line_key, comparacion por source_row_hash, last_seen_at, missing_from_source y no hard delete
  • la validacion real de Tabla 2 y la proxima fecha piloto deben congelarse desde snapshot, no desde SGC vivo

Regla critica vigente para SOURCE-001:

  • Cliente es la entidad comercial central del observer, no solo una fila del ERP
  • tenant_id + codigo_cliente es la clave logica fuerte actual del dominio
  • Zona representa una agrupacion logistica para rutas y reparto
  • Zona no define vendedor responsable
  • el territorio comercial del vendedor se deriva de su cartera real de clientes asignados y del cruce con geografia, ventas y productos

Como se separa

Esto es Core

El Business Observer Core pertenece a OpenClaw cuando se trata de:

  • capacidad reutilizable de observar negocio
  • deteccion generica de clientes en riesgo
  • deteccion generica de oportunidades de crecimiento
  • aislamiento por tenant
  • gobierno de datos
  • permisos
  • trazabilidad
  • auditoria

Ese material vive en la documentacion global y debe poder servir tambien para otros tenants futuros.

Esto es APV

Este espacio documenta solo lo que pertenece a alpuntodeventa, por ejemplo:

  • reglas comerciales propias
  • prioridades de negocio propias
  • ejemplos de marcas, productos y proveedores propios
  • criterios operativos propios
  • decisiones comerciales propias

Reglas de este espacio

  • usa capacidades Core reutilizables
  • documenta decisiones especificas de APV
  • no mezcla reglas de otros tenants
  • no duplica sin necesidad la documentacion global
  • referencia al Core cuando el contenido pertenece a OpenClaw

Relacion con otros tenants

La Directa tendra en el futuro su propio espacio documental de Business Observer.

Ese futuro espacio no debe compartir automaticamente reglas comerciales de APV.

Referencias Core