Territory 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/TERRITORY-BLUEPRINT.md

Autoridades relacionadas:

1. Definicion del dominio¶

Territory es el dominio que ordena la lectura territorial de clientes, ventas, zonas logisticas y territorio comercial derivado.

Debe separar dos conceptos:

territorio logistico
territorio comercial del vendedor

La zona del SGC pertenece primero a la lectura logistica. El territorio comercial del vendedor se deriva de cartera asignada, ventas reales, geografia y productos.

2. Que representa para OpenClaw/APV¶

Para OpenClaw / APV, territorio representa la capacidad de entender:

donde esta un cliente
que zona logistica lo cubre
que localidades y provincias se agrupan operativamente
que vendedor trabaja una cartera real
donde se perdio masa comercial
donde hay clientes recuperables
que productos, marcas y proveedores explican un territorio

Territory permite conectar geografia, logistica, cartera, venta real, ownership y recuperacion comercial.

3. Fuente primaria actual¶

La fuente primaria actual para territorio logistico de clientes es SOURCE-001.

Campos fuente relevantes:

Zona
Localidad
Provincia

Lectura vigente:

Zona SGC es logistica para armado de rutas, despacho y reparto
el formato esperado para zona es Zona xx - Localidad
debe admitirse ZONA 00 - INTERIOR DEL PAIS
localidad y provincia son senales territoriales fuertes
Zona no define vendedor
Zona no define ownership comercial

El territorio comercial del vendedor deriva del cruce futuro de:

cartera asignada desde SOURCE-001
ventas reales desde SOURCE-003
geografia de clientes
productos, marcas y proveedores desde SOURCE-002

4. Identidad y claves de negocio¶

Identidades conceptuales del dominio:

tenant_id + provincia_normalized
tenant_id + localidad_normalized
tenant_id + zona_normalized
tenant_id + logistic_zone_normalized
tenant_id + seller_assigned + periodo + territorio
tenant_id + seller_transactional + periodo + territorio

Reglas:

provincia_raw y provincia_normalized deben convivir
localidad_raw y localidad_normalized deben convivir
zona_raw, zona_type y zona_normalized deben convivir
el catalogo de alias territoriales debe sostener normalizaciones aprobadas o pendientes
Zona puede agrupar localidades y provincias para operacion logistica
el vendedor no es clave primaria de la zona logistica

5. Estados o clasificaciones¶

Clasificaciones territoriales:

provincia
localidad
zona logistica
undefined
unknown
microzona opcional
territorio comercial formal
territorio comercial real
territorio perdido
territorio recuperable
territorio en riesgo

Clasificaciones de zona_type:

logistic_zone
undefined
unknown

Reglas:

NO DEFINIDA debe preservarse como valor observado
NULL/VACIO no equivale a NO DEFINIDA
zonas multi-provincia no son error automatico
zona logistica no es territorio comercial del vendedor

6. Relaciones con otros dominios¶

El dominio territory se relaciona con:

Cliente: aporta direccion, localidad, provincia, zona logistica y cartera asignada.
Ventas: aporta actividad real por fecha, cliente, vendedor transaccional, SKU y documento.
Producto: aporta SKU, marca, proveedor, categoria, rubro y mix para explicar territorio comercial.
Ownership: permite leer quien trabaja realmente una cuenta dentro de un territorio.
Territory Alias Catalog: sostiene aliases, valores canonicos, aprobacion, confianza y evidencia.
Analytics: calcula territorio perdido, recuperable, trabajado, no trabajado y masa comercial.
IA / ML: puede priorizar recuperacion, detectar patrones territoriales y explicar oportunidades.

7. Reglas obligatorias¶

Reglas cerradas para territory:

Zona SGC es logistica para armado de rutas
Zona no define vendedor
Zona no define ownership comercial
no usar zona logistica para inferir vendedor responsable
preservar raw + normalized en provincia, localidad y zona
preservar zona_type
no eliminar NO DEFINIDA
diferenciar NULL/VACIO de NO DEFINIDA
usar catalogo de aliases para normalizacion gobernada
territorio comercial del vendedor debe derivarse de cartera asignada, ventas reales, geografia y productos
no convertir territorio comercial derivado en fuente primaria sin evidencia
no crear geocodificacion ni automatizacion sin decision posterior

8. Preguntas de negocio que debe responder¶

Este blueprint debe permitir responder:

que zona logistica cubre un cliente
que localidades agrupa una zona
que provincias aparecen en una zona logistica
que vendedor trabaja que cartera real
que territorio perdio clientes
que territorio es recuperable
cuantos clientes recuperar para recomponer masa comercial
que vendedor tiene actividad real fuera de su cartera formal
que marcas, proveedores o SKU explican un territorio
donde hay abandono, recuperacion o crecimiento
que zonas logisticas concentran oportunidades comerciales

9. Analytics / IA / ML que habilita¶

Territory habilita:

analytics de clientes por provincia, localidad y zona logistica
analytics de ventas por territorio logistico
analytics de territorio comercial por vendedor
deteccion de territorio perdido
deteccion de territorio recuperable
recomposicion de masa comercial por zona, localidad o vendedor
lectura de mix territorial por SKU, marca y proveedor
priorizacion de visitas o recuperaciones
alertas territoriales de abandono
modelos de expansion, recuperacion y cobertura
explicacion territorial para recomendaciones comerciales

Regla:

los modelos analiticos pueden consumir valores normalizados, pero la auditoria debe poder volver a los valores raw

10. Diseno futuro relacionado¶

Referencias conceptuales futuras:

territory_alias_catalog
logistic_zones
logistic_zone_localities
analytics_commercial_territory
capas de cliente con provincia_raw, provincia_normalized, localidad_raw, localidad_normalized, zona_raw, zona_type y zona_normalized

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:

un catalogo territorial cargado
una normalizacion definitiva
una geocodificacion
una asignacion 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 territorial
una vista analytics
una implementacion
una autorizacion para tocar runtime
un reemplazo de TERRITORY-NORMALIZATION-STRATEGY
un reemplazo de TERRITORY-ALIAS-CATALOG-001

12. Pendientes¶

Quedan pendientes:

carga real y aprobacion humana del catalogo de aliases territoriales
normalizacion definitiva de localidades y provincias cuando aplique
definicion fisica final de catalogos territoriales
definicion fisica final de analytics comercial territorial
cruce final con ventas, productos y ownership
criterio futuro de geocodificacion si negocio lo aprueba
permisos de consumo territorial por rol
performance real de consultas territoriales
reglas de recuperacion territorial automatizada, si se aprueban

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