Sales Blueprint - Business Observer APV¶

Fecha: 2026-06-10

Estado: BLUEPRINT FUNCIONAL V1

Scope: tenant

tenant_id: alpuntodeventa

Owner: Gabi / Carlos Canu

Fuente de verdad: docs/tenants/alpuntodeventa/business-observer/blueprints/SALES-BLUEPRINT.md

Autoridades relacionadas:

1. Definicion del dominio¶

Una Venta es el hecho transaccional itemizado que registra una operacion comercial calculada para APV.

No es solamente un comprobante, una cabecera documental ni un total agregado.

El dominio venta debe preservar:

fecha
hora de origen SGC
comprobante y documento
cliente
SKU
vendedor transaccional
linea tecnica
unidades
importes
impuestos
descuentos
CMV
contribucion
notas de credito
devoluciones
guias y otros documentos relevantes

2. Que representa para OpenClaw/APV¶

Para OpenClaw / APV, venta representa la evidencia principal de actividad comercial real.

Permite responder:

cuanto se vendio
quien vendio
a quien se vendio
que producto se vendio
que margen o contribucion genero
que cuentas fueron activadas, recuperadas, abandonadas o desarrolladas
como se comportan marcas, proveedores, territorios y vendedores

La venta itemizada es el puente entre clientes, productos, vendedores, territorio, ownership, margen y analytics.

3. Fuente primaria actual¶

La fuente primaria candidata actual del dominio venta es SOURCE-003 / Tabla 2 vNext.

Lectura vigente:

Tabla 2 vNext es la candidata canonica para venta itemizada
Tabla 2 es la salida que debe sincronizarse en una futura base conceptual
Tabla 1/3/4/5/6 quedan como reportes derivados o referencias de conciliacion
line_key_v4 esta aceptada en estado AMARILLO ACEPTADO para sync inicial analitico
line_sequence_v1 es columna tecnica de pipeline y no identidad fisica ERP
SOURCE-003 / SGC Ventas debe tratarse como fuente viva
una fecha ya cargada puede cambiar aproximadamente hasta 7 dias hacia atras por liquidacion de entregas, rechazos, anulaciones, refacturacion, descuentos posteriores, notas de credito, ajustes de cuenta corriente y cambios operativos de cobro/entrega
la sync futura no debe basarse solo en ultima fecha cargada; debe contemplar snapshot diario y ventana movil de reproceso

Este blueprint no reemplaza la autoridad de source, inventario ni decision de identidad de linea.

4. Identidad y claves de negocio¶

El grano funcional de venta itemizada es:

fecha
hora_origen_sgc
documento
cliente
sku
vendedor
line_sequence_v1

Grano documental extendido recomendado:

fecha
hora_origen_sgc
tipo_comp
nro_comp
tipo_doc_int
nro_int_doc
documento
codigo_cliente
sku
seller_transactional
line_sequence_v1

Reglas de identidad:

line_key_v4 representa la identidad tecnica aceptada en estado AMARILLO ACEPTADO
line_key_v4 combina identidad documental, hora de origen, cliente, SKU, vendedor y line_sequence_v1
line_sequence_v1 resuelve unicidad agregada para analytics, pero no es un ID fisico del ERP
importes, precios, impuestos o unidades no deben usarse como identidad de venta
el documento ayuda a identidad, pero la venta base del observer debe llegar al item

5. Estados o clasificaciones¶

Clasificaciones que el dominio venta debe preservar:

facturas
comprobantes
documentos internos
guias
notas de credito
devoluciones
motivos de devolucion
anulaciones o estados documentales cuando correspondan
canal transaccional observado
ramo transaccional observado
ventas positivas
importes negativos
ajustes o signos derivados de la logica fuente

Reglas:

notas de credito y negativos deben preservarse
devoluciones y motivos no deben simplificarse fuera del dominio
canal y ramo de SOURCE-003 son senales transaccionales y no reemplazan el canal comercial del cliente en SOURCE-001
un comprobante no debe colapsar lineas itemizadas distintas

6. Relaciones con otros dominios¶

El dominio venta se relaciona con:

Clientes: aporta compras reales, recencia, recuperacion, actividad y riesgo.
Productos: aporta SKU, articulo, marca, proveedor, categoria, costo, precio y mix.
Vendedores: usa seller_transactional como autoria real de venta.
Ownership: permite comparar seller_assigned contra vendedor real, ultima venta, recuperacion, crecimiento, riesgo y abandono.
Territory: permite cruzar ventas con localidad, provincia, zona logistica y territorio comercial derivado.
Analytics: sostiene ventas diarias, margen, contribucion, marcas, proveedores, clientes, SKU y recomposicion comercial.
IA / ML: habilita alertas, prediccion, recomendacion, deteccion de patrones y explicabilidad comercial.

7. Reglas obligatorias¶

Reglas cerradas para el dominio venta:

ventas se atribuyen a seller_transactional
no atribuir una venta al vendedor asignado si la hizo otro vendedor
no sobrescribir seller_transactional con seller_assigned
no usar importes como identidad
no usar totales agregados como identidad de item
preservar notas de credito y negativos
preservar devoluciones y motivos cuando existan
no hacer hard delete
recalculos futuros deben preservar auditoria y trazabilidad
los recalculos de ventas deben contemplar ventana movil, sugerida inicialmente de 10 dias para cubrir una semana operativa mas margen
las fechas piloto o de conciliacion deben congelarse desde snapshot, no desde una relectura posterior de SGC vivo
una linea de venta puede aparecer, cambiar valores, desaparecer de la extraccion activa, quedar anulada o recibir nota de credito o ajuste posterior
la persistencia futura debe resolver cambios con tenant_id + line_key, source_row_hash, last_seen_at y missing_from_source
line_sequence_v1 no es ID fisico ERP
line_key_v4 no debe presentarse como identidad verde o legal perfecta
no simplificar IVA, IIBB, descuentos, CMV ni contribucion
no tratar V_VENTAS cruda como autoridad suficiente por si sola
no convertir este blueprint en query, mapping ni DDL

8. Preguntas de negocio que debe responder¶

Este blueprint debe permitir responder:

cuanto se vendio
quien vendio
a quien se vendio
que SKU se vendio
que marca se vendio
que proveedor se vendio
que categoria, rubro o grupo se vendio
cuanto margen genero
cuanto CMV tuvo
cuanto neto, bruto, IVA, IIBB, descuento y contribucion genero
que venta recupero una cuenta
que vendedor activo una cuenta
que venta desarrollo una cartera
que notas de credito, devoluciones o negativos afectaron la lectura

9. Analytics / IA / ML que habilita¶

El dominio venta habilita:

ventas por dia, cliente, vendedor, SKU, marca y proveedor
margen y contribucion por item
ranking de vendedores transaccionales
lectura de clientes activos, inactivos, recuperados o abandonados
lectura de mix comprado por cliente
medicion de cartera trabajada por vendedor real
deteccion de ventas fuera de cartera asignada
recomposicion de masa comercial
modelos de recuperacion de cuentas
modelos de recomendacion de productos
alertas de margen, devoluciones, descuentos y actividad comercial
explicacion de territorio comercial real

Regla:

cualquier analytics debe conservar trazabilidad hacia la venta itemizada y su vendedor transaccional

10. Diseno futuro relacionado¶

Referencias conceptuales futuras ya documentadas:

source_003_sales_items
source_003_sales_documents
source_003_sales_item_audit
analytics_sales_daily
analytics_sales_by_seller_daily
analytics_sales_by_customer_daily
analytics_sales_by_product_daily
analytics_sales_by_brand_daily
analytics_sales_by_supplier_daily
analytics_cmv_margin_daily
analytics_customer_ownership
analytics_seller_reconciliation
analytics_commercial_territory

Estas referencias no son tablas creadas, no son DDL, no son migraciones y no autorizan implementacion.

11. Que NO es este blueprint¶

Este documento no es:

una query
una cabecera de comprobante
un mapping campo por campo de SOURCE-003
un contrato de datos
una fuente de autoridad
un inventario de resultados
un SQL
un DDL
una migracion
una tabla de ventas
una vista de analytics
una implementacion
una autorizacion para tocar runtime
un reemplazo de SOURCE-003
un reemplazo de SOURCE-INVENTORY-RESULTS-003
un reemplazo de SOURCE-003-LINE-IDENTITY-DECISION

12. Pendientes¶

Quedan pendientes:

validacion adicional de line_key_v4 en backfill o ventana mayor
produccion final de identidad de linea
conciliacion ampliada de Tabla 2 contra reportes derivados cuando negocio lo requiera
diseno fisico final y aprobacion explicita antes de cualquier ejecucion
carga inicial futura
estrategia de recalculo de ventanas moviles
snapshot diario y freeze date para pilotos de SOURCE-003
permisos de consumo de datos transaccionales
performance real
definicion final de vistas o tablas analytics
criterios de auditoria para cambios de importes, signos, notas de credito y devoluciones

13. Confirmaciones de alcance¶

Este blueprint:

no toca runtime
no toca VPS
no toca Docker
no toca PostgreSQL
no ejecuta queries
no crea codigo
no crea tablas
no crea migraciones
no mueve archivos
solo documenta dominio funcional