Ownership 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/OWNERSHIP-BLUEPRINT.md

Autoridades relacionadas:

1. Definicion del dominio¶

Ownership es la lectura analitica que permite entender quien trabaja realmente una cuenta en APV.

No es una reasignacion automatica de cartera.

El dominio ownership compara y preserva dos verdades comerciales:

seller_assigned desde SOURCE-001
seller_transactional desde SOURCE-003

Desde esa comparacion nacen lecturas derivadas como ultima venta, trabajo efectivo, recuperacion, crecimiento, riesgo y abandono.

2. Que representa para OpenClaw/APV¶

Para OpenClaw / APV, ownership representa la diferencia entre:

quien tiene formalmente asignado un cliente
quien lo vendio realmente
quien lo trabajo por ultima vez
quien lo esta desarrollando
quien lo recupero
quien lo abandono o lo puso en riesgo

Esta lectura ayuda a proteger cartera, medir trabajo real, detectar drift comercial y recomponer masa comercial sin borrar la cartera formal ni la autoria real de ventas.

3. Fuente primaria actual¶

Ownership no nace de una sola fuente.

Fuentes primarias actuales:

SOURCE-001 define seller_assigned
SOURCE-003 define seller_transactional

Documentos analiticos relacionados:

CUSTOMER-OWNERSHIP-ANALYTICS.md define la lectura conceptual de quien trabaja realmente cada cliente
SELLER-RECONCILIATION-RULES.md define la reconciliacion entre cartera asignada y ventas reales

Regla:

ninguna fuente reemplaza a la otra
SOURCE-001 gobierna cartera formal
SOURCE-003 gobierna autoria real de venta

4. Identidad y claves de negocio¶

La identidad funcional minima de ownership se apoya en:

tenant_id
codigo_cliente
seller_assigned
seller_transactional
fecha o corte analitico
ventana de analisis cuando corresponda

Conceptos obligatorios:

ownership_assigned: cartera formal desde seller_assigned
ownership_last_sale: vendedor de ultima venta real desde seller_transactional
ownership_effective: vendedor que concentra actividad real dentro de una ventana validada
ownership_recovery: vendedor que reactiva una cuenta luego de inactividad relevante
ownership_growth: vendedor que desarrolla importe, recurrencia, mix, marcas, proveedores o SKU
ownership_risk: senal de deterioro o drift del ownership asignado
ownership_abandonment: senal de no trabajo reciente del vendedor asignado

Regla:

cualquier clave futura debe conservar cliente, vendedor asignado, vendedor transaccional y fecha de corte sin colapsar diferencias

5. Estados o clasificaciones¶

Estados analiticos conceptuales:

assigned_and_worked
assigned_but_inactive
worked_by_other_seller
shared_ownership
effectively_owned_by_other_seller
recovered_by_assigned_seller
recovered_by_other_seller
growing_under_assigned_seller
growing_under_other_seller
abandoned_by_assigned_seller
no_recent_activity
manual_review

Reglas:

estos estados son derivados
no son verdad primaria
no deben cerrar automatizaciones sin ventanas y umbrales aprobados
ownership_effective no reemplaza automaticamente a ownership_assigned

6. Relaciones con otros dominios¶

El dominio ownership se relaciona con:

Cliente: el cliente es la cuenta sobre la que se mide ownership.
Ventas: la venta define seller_transactional, ultima venta, recuperacion y actividad real.
Producto: explica crecimiento por SKU, marca, proveedor, categoria y mix.
Territory: permite ubicar cartera asignada, actividad real, abandono y recuperacion por geografia o zona logistica.
Seller Reconciliation: conserva la diferencia entre cartera formal y actividad transaccional.
Analytics: produce cortes por cliente, vendedor, periodo y estado de ownership.
IA / ML: puede priorizar alertas, recuperaciones y recomendaciones con trazabilidad.

7. Reglas obligatorias¶

Reglas cerradas para ownership:

no reemplazar seller_assigned automaticamente
preservar diferencias assigned vs transactional
ventas se atribuyen al vendedor real
no atribuir venta real al vendedor asignado si la hizo otro
no borrar la cartera formal por una venta aislada
no declarar ownership_effective sin ventana y umbrales
definir ventanas y umbrales antes de automatizar
no usar Zona para inferir vendedor responsable
no excluir clientes suspendidos o de baja del analisis historico cuando la pregunta sea recuperacion o perdida
no confundir ultima venta con ownership definitivo
no convertir una senal analitica en reasignacion operativa sin decision humana y documental

8. Preguntas de negocio que debe responder¶

Este blueprint debe permitir responder:

quien trabaja realmente el cliente
quien lo tiene asignado
quien le vendio por ultima vez
si fue abandonado
si fue recuperado
si otro vendedor lo esta desarrollando
si la cartera formal coincide con la actividad real
que vendedor recupero una cuenta
que vendedor hace crecer una cuenta
que vendedor trabaja clientes fuera de su cartera
cuantos clientes asignados no tienen actividad reciente
cuantos clientes recuperar para recomponer masa comercial

9. Analytics / IA / ML que habilita¶

Ownership habilita:

analytics de cartera trabajada y no trabajada
reconciliacion seller_assigned vs seller_transactional
deteccion de cuentas abandonadas
deteccion de cuentas recuperadas
deteccion de desarrollo por terceros
ranking de recuperacion por vendedor
alertas de riesgo de cartera
recomendaciones de accion comercial
modelos de probabilidad de recuperacion
modelos de drift de cartera
explicaciones de crecimiento por mix, marca, proveedor o territorio

Regla:

toda salida analitica debe declarar si usa seller_assigned, seller_transactional u ownership_effective

10. Diseno futuro relacionado¶

Referencias conceptuales futuras:

analytics_customer_ownership
analytics_seller_reconciliation
analytics_commercial_territory
cortes por cliente y fecha de analisis
cortes por vendedor y periodo
ventanas futuras para abandono, recuperacion, crecimiento y efectividad

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 reasignacion de cartera
una automatizacion de vendedores
una query
un mapping campo por campo
un contrato de datos
una fuente de autoridad
un inventario de resultados
un SQL
un DDL
una migracion
una tabla analytics
una vista fisica
una implementacion
una autorizacion para tocar runtime
un reemplazo de CUSTOMER-OWNERSHIP-ANALYTICS
un reemplazo de SELLER-RECONCILIATION-RULES

12. Pendientes¶

Quedan pendientes:

definir ventana temporal oficial para ownership_effective
definir umbrales de abandono
definir umbrales de recuperacion
definir umbrales de crecimiento
definir reglas finales de cuentas compartidas
ampliar validacion real si negocio requiere historico mayor
diseno fisico futuro de analytics
permisos de consumo por vendedor, supervisor y direccion
performance real
reglas de automatizacion o alertas, si se aprueban mas adelante

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