Saltar a contenido

Seller Commercial Territory View

Fecha: 2026-06-09

Estado: DISENO CONCEPTUAL FUTURO / NO IMPLEMENTADO

Scope: tenant

tenant_id: alpuntodeventa

Owner: Gabi / Carlos Canu

Fuente de verdad: docs/tenants/alpuntodeventa/business-observer/analytics/SELLER-COMMERCIAL-TERRITORY-VIEW.md

Documentos relacionados:

  • docs/tenants/alpuntodeventa/business-observer/analytics/CUSTOMER-OWNERSHIP-ANALYTICS.md
  • docs/tenants/alpuntodeventa/business-observer/BUSINESS-OBSERVER-DATA-CONTRACT-001.md
  • docs/tenants/alpuntodeventa/business-observer/analytics/SELLER-RECONCILIATION-RULES.md
  • docs/tenants/alpuntodeventa/business-observer/mappings/SOURCE-001-CLIENTES-MAPPING.md
  • docs/tenants/alpuntodeventa/business-observer/sources/SOURCE-001-SGC-CLIENTES.md
  • docs/tenants/alpuntodeventa/business-observer/sources/SOURCE-002-SGC-PRODUCTOS.md
  • docs/tenants/alpuntodeventa/business-observer/sources/SOURCE-003-SGC-VENTAS-COMPROBANTES.md
  • docs/tenants/alpuntodeventa/business-observer/territory/TERRITORY-NORMALIZATION-STRATEGY.md
  • docs/governance/standards/DATA-DESIGN-STANDARD.md

1. Objetivo

Definir conceptualmente la futura vista analitica que debe responder preguntas sobre territorio comercial del vendedor en APV.

La vista no define verdad primaria.

La vista organiza una lectura derivada para consumo analitico a partir de:

  • cartera real de clientes asignados al vendedor
  • geografia comercial del cliente
  • zona logistica del cliente
  • ventas reales
  • mix real de SKU, marcas, proveedores y categorias

Preguntas objetivo:

  • cuantos clientes activos tiene cada vendedor por localidad y provincia
  • cuantos clientes de baja tiene cada vendedor y donde se concentran
  • que territorio comercial perdio o puede recuperar cada vendedor
  • que venden realmente los vendedores por zona, localidad y provincia
  • que mix de marcas, proveedores, categorias y SKU define cada cartera

2. Naturaleza de la capa

Esta vista futura es una capa derivada de analytics.

No es:

  • fuente primaria
  • base sincronizada
  • reemplazo de SOURCE-001, SOURCE-002 o SOURCE-003
  • definicion fisica cerrada

Lectura obligatoria:

  • SOURCE-001 sigue gobernando cliente, ownership comercial y territorio base
  • SOURCE-002 sigue gobernando producto por tenant_id + SKU
  • SOURCE-003 sigue gobernando ventas calculadas por item
  • la base sincronizada futura recomendada para esas ventas es source_003_sales_items derivada de Tabla 2
  • la reconciliacion entre seller_assigned y seller_transactional debe seguir las reglas documentadas en SELLER-RECONCILIATION-RULES.md
  • esta vista solo combina y ordena esas senales para consumo analitico

3. Fuentes necesarias

Fuentes minimas obligatorias:

  • SOURCE-001 Clientes
  • SOURCE-002 Productos
  • SOURCE-003 Ventas / Comprobantes

Rol de cada fuente:

  • SOURCE-001: cliente, estado comercial, vendedor, localidad, provincia y zona logistica
  • SOURCE-002: SKU, articulo, marca, proveedor, categoria y otros atributos maestros del producto
  • SOURCE-003: venta real, periodo, cliente transaccional, vendedor transaccional, SKU vendido y contexto historico de la linea

4. Claves de cruce esperadas

Claves minimas recomendadas para el diseno posterior:

  • tenant_id + codigo_cliente
  • tenant_id + SKU
  • vendedor desde SOURCE-001: seller_code_raw / seller_name_raw o equivalente canonico posterior

Lectura de cruce esperada:

  • SOURCE-001 debe anclar la cartera real por tenant_id + codigo_cliente
  • SOURCE-003 debe cruzar cliente y venta por la identidad comercial del cliente mas la linea transaccional calculada
  • la lectura de vendedor debe preservar seller_assigned desde SOURCE-001 y seller_transactional desde SOURCE-003, sin colapsarlas en un solo valor
  • SOURCE-002 debe enriquecer cada linea vendida por tenant_id + SKU
  • si SOURCE-003 expone alias de articulo o SKU con diferencias de formato, el diseno posterior debera resolver un canon comun sku/articulo sin perder el valor raw

5. Dimensiones minimas

Dimensiones que la vista debe exponer o soportar:

  • vendedor
  • tipo de vendedor usado por la lectura: assigned, transactional o effective
  • cliente
  • estado cliente
  • localidad
  • provincia
  • zona logistica
  • SKU
  • marca
  • proveedor
  • categoria
  • periodo

Regla de lectura:

  • la vista debe preservar capacidad de volver a raw + normalized cuando la territorialidad o el SKU requieran auditoria
  • la capa analitica debe privilegiar consumo sobre valores normalizados

6. Metricas futuras

Metricas o lecturas objetivo documentadas:

  • clientes activos por vendedor y localidad
  • clientes de baja por vendedor y provincia
  • territorio perdido por vendedor
  • territorio recuperable
  • ventas por vendedor y zona logistica
  • SKU vendidos por vendedor y localidad
  • marcas vendidas por vendedor y provincia
  • proveedores dominantes por cartera
  • mix de productos
  • oportunidades de recuperacion
  • clientes necesarios para recomponer masa comercial

Lectura funcional recomendada:

  • algunas metricas nacen por agregacion directa
  • otras requieren derivacion posterior sobre historicos, recencia o reglas de negocio
  • esta vista conceptual no cierra aun formulas exactas ni ventanas de tiempo

Relacion adicional con ownership:

  • la lectura territorial futura debe poder cruzarse con CUSTOMER-OWNERSHIP-ANALYTICS.md
  • eso permite distinguir territorio formal, territorio efectivamente trabajado, cuentas recuperadas, cuentas abandonadas y cuentas desarrolladas por terceros

7. Restricciones obligatorias

  • no usar Zona para inferir vendedor
  • no excluir clientes de baja del analisis historico
  • no usar WhatsApp como identificador
  • preservar raw + normalized
  • separar analisis operativo de fuente sincronizada

Restricciones derivadas adicionales:

  • no colapsar el territorio comercial del vendedor a una sola etiqueta de zona
  • no reemplazar SOURCE-003 por una lectura resumida de ventas
  • no perder la cartera completa por filtrar solo clientes actualmente vendibles
  • no usar solo textos de proveedor o marca como ancla de relacion si existe SKU

8. Regla central de territorio comercial

Pregunta incorrecta:

  • cual es el territorio del vendedor segun Zona

Pregunta correcta:

  • cual es el territorio comercial del vendedor segun su cartera real de clientes asignados, la geografia de esos clientes, sus ventas reales y el mix de productos efectivamente vendido

Conclusion documental:

  • Zona sigue siendo una dimension logistica
  • el vendedor sigue saliendo de SOURCE-001
  • el territorio comercial del vendedor debe construirse como capa derivada

9. Diseno conceptual futuro de la vista

9.1 Granularidad recomendada

Granularidad base recomendada:

  • una fila por tenant_id + periodo + vendedor + cliente + SKU

Justificacion:

  • permite agregar despues por vendedor, cliente, localidad, provincia, zona, marca, proveedor o categoria
  • evita perder mix de producto al subir demasiado pronto a nivel vendedor
  • mantiene una frontera clara entre cartera, transaccion y producto

Granularidad alternativa futura para consumo acelerado:

  • snapshots agregados por periodo + vendedor + localidad
  • snapshots agregados por periodo + vendedor + provincia
  • snapshots agregados por periodo + vendedor + zona_logistica

Pero:

  • esas materializaciones futuras deben derivarse de la granularidad base y no reemplazarla como diseno rector

9.2 Columnas principales recomendadas

Columnas conceptuales minimas:

  • tenant_id
  • period_date o equivalente de periodo base
  • period_year
  • period_month
  • period_week si negocio lo necesitara despues
  • seller_code
  • seller_name
  • seller_assigned_code
  • seller_assigned_name
  • seller_transactional_code
  • seller_transactional_name
  • seller_effective_code
  • seller_effective_name
  • seller_mismatch
  • codigo_cliente
  • customer_name
  • customer_status
  • can_sell
  • provincia_raw
  • provincia_normalized
  • localidad_raw
  • localidad_normalized
  • zona_logistica_raw
  • zona_logistica_type
  • zona_logistica_normalized
  • sku
  • articulo_raw
  • marca_raw
  • proveedor_codigo
  • proveedor_nombre
  • categoria_raw
  • source_001_last_purchase_date cuando ayude a riesgo o recuperacion
  • sales_units
  • sales_bultos si la futura capa logra sostenerlo sin inventar
  • sales_amount_net
  • sales_amount_final
  • documents_count
  • line_count
  • is_customer_active_snapshot
  • is_customer_inactive_snapshot

Columnas derivadas recomendadas para analitica posterior:

  • territory_loss_flag
  • territory_recovery_flag
  • commercial_mass_flag
  • recovery_opportunity_flag

Regla:

  • esos flags son conceptuales y deben quedar claramente marcados como derivados, no como verdad primaria

9.3 Filtros minimos de consumo

Filtros minimos que la capa deberia soportar bien:

  • tenant_id
  • periodo desde / hasta
  • vendedor
  • estado de cliente
  • provincia
  • localidad
  • zona logistica
  • SKU
  • marca
  • proveedor
  • categoria

Filtros operativos recomendados para tableros posteriores:

  • solo clientes activos
  • incluir clientes de baja
  • solo cartera con ventas
  • cartera completa aunque no haya ventas en el periodo

10. Indices y materializacion futura

Sin crear nada ahora, la recomendacion conceptual futura es:

  • indice por tenant_id + seller_code + period_date
  • indice por tenant_id + codigo_cliente + period_date
  • indice por tenant_id + sku + period_date
  • indice por tenant_id + provincia_normalized + localidad_normalized
  • indice por tenant_id + zona_logistica_normalized + period_date

Materializaciones futuras plausibles:

  • agregado mensual por vendedor y localidad
  • agregado mensual por vendedor y provincia
  • agregado mensual por vendedor y zona logistica
  • agregado mensual por vendedor, marca y proveedor

Regla de prudencia:

  • la materializacion futura debe responder a patrones reales de consumo
  • no conviene materializar antes de validar cardinalidad, volumen y frecuencia real de uso

11. Advertencias de performance

  • cruzar cartera completa de clientes con ventas itemizadas puede crecer rapido
  • enriquecer cada linea con producto, marca, proveedor y categoria puede volver pesada una vista no materializada
  • incluir historico completo de clientes de baja aumenta valor analitico pero tambien volumen
  • agregar demasiado pronto por vendedor puede ocultar huecos de mix y recuperacion
  • dejar la granularidad demasiado baja puede volver costosos tableros ejecutivos si no existe luego una capa resumida

Recomendacion:

  • separar despues la capa base analitica de las vistas resumidas de consumo
  • validar volumen real de SOURCE-003 antes de cerrar cualquier estrategia de materializacion

12. Pendientes preservados

Este documento deja explicitamente pendientes:

  • diseno SQL real
  • creacion fisica de vista o materialized view
  • validacion con datos reales de SOURCE-002 y SOURCE-003
  • validacion real de coincidencia entre vendedor asignado y vendedor transaccional
  • umbrales finales para abandono, reactivacion y cuenta compartida
  • reglas finales para ecommerce o canales compartidos
  • validacion de performance real
  • permisos de consumo
  • formulas finales de territorio perdido, recuperable y recomposicion de masa comercial

13. Confirmaciones de alcance

  • sin runtime
  • sin queries
  • sin tablas
  • sin vistas fisicas
  • sin migraciones
  • solo documentacion