Saltar a contenido

Seller Reconciliation Rules

Fecha: 2026-06-09

Estado: DISENO CONCEPTUAL FUTURO / VALIDACION REAL EXPLORATORIA 2026-06-09

Scope: tenant

tenant_id: alpuntodeventa

Owner: Gabi / Carlos Canu

Fuente de verdad: docs/tenants/alpuntodeventa/business-observer/analytics/SELLER-RECONCILIATION-RULES.md

Documentos relacionados:

  • docs/tenants/alpuntodeventa/business-observer/analytics/CUSTOMER-OWNERSHIP-ANALYTICS.md
  • docs/tenants/alpuntodeventa/business-observer/analytics/SELLER-COMMERCIAL-TERRITORY-VIEW.md
  • docs/tenants/alpuntodeventa/business-observer/BUSINESS-OBSERVER-DATA-CONTRACT-001.md
  • docs/tenants/alpuntodeventa/business-observer/sources/SOURCE-003-CHANNEL-TAXONOMY.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/governance/standards/DATA-DESIGN-STANDARD.md

1. Objetivo

Definir conceptualmente como debe reconciliarse el vendedor asignado al cliente en SOURCE-001 con el vendedor real observado en SOURCE-003, antes de disenar SQL, vistas analiticas, tablas fisicas o materialized views.

Este documento no reemplaza ninguna fuente primaria.

Este documento solo fija la frontera conceptual que el modelo futuro debera preservar.

2. Regla madre

En APV existen dos verdades comerciales que no deben mezclarse:

  • SOURCE-001 define la cartera asignada
  • SOURCE-003 define la actividad comercial real

Regla central:

  • la cartera asignada no debe sobrescribir la autoria real de la venta
  • la autoria real de la venta no debe borrar la cartera asignada
  • la diferencia entre ambas debe preservarse como senal analitica

3. Rol de cada fuente

3.1 SOURCE-001 Clientes

Gobierna:

  • cliente
  • vendedor asignado
  • estado cliente
  • localidad
  • provincia
  • zona logistica
  • frecuencia
  • fecha ultima compra SGC si se preserva como dato fuente

Lectura correcta:

  • SOURCE-001 representa la cartera formal
  • Codigo_vendedor / Nombre_Vendedor representan el responsable esperado
  • esa asignacion expresa ownership comercial teorico y territorio comercial esperado

3.2 SOURCE-003 Ventas

Gobierna:

  • vendedor transaccional
  • fecha de venta
  • comprobante
  • importe
  • cliente
  • SKU

Lectura correcta:

  • SOURCE-003 representa quien hizo realmente la venta
  • el vendedor de la transaccion define la atribucion real de facturacion
  • la venta debe computarse al vendedor que realmente la hizo
  • la sync futura debe salir de SOURCE-003 / Tabla 2 hacia source_003_sales_items; Tabla 1/3/4/5/6 quedan como conciliacion

3.3 SOURCE-002 Productos

Gobierna:

  • SKU
  • articulo
  • marca
  • proveedor
  • categoria
  • atributos de producto necesarios para analisis de mix

Lectura correcta:

  • SOURCE-002 no define vendedor
  • SOURCE-002 enriquece la lectura de la venta real y de la cartera

4. Conceptos principales

4.1 seller_assigned

Vendedor asignado al cliente desde SOURCE-001.

Representa:

  • cartera formal
  • responsable esperado de la cuenta
  • territorio comercial teorico

4.2 seller_transactional

Vendedor observado en SOURCE-003.

Representa:

  • quien realizo realmente la venta
  • la autoria real de la transaccion
  • el vendedor que debe usarse para atribucion de facturacion real

4.3 seller_effective

Vendedor utilizado por una metrica especifica segun contexto.

Regla:

  • puede ser seller_assigned o seller_transactional
  • debe declararse explicitamente en cada metrica futura
  • no debe quedar implicito

4.4 seller_last_sale

Vendedor que realizo la ultima venta general del cliente.

Lectura correcta:

  • no implica necesariamente que sea el vendedor asignado
  • no redefine por si solo la cartera asignada

4.5 assigned_seller_last_sale_at

Fecha de ultima venta realizada por el vendedor asignado al cliente.

Lectura correcta:

  • sirve para medir si el vendedor asignado trabaja o no su cartera
  • debe compararse contra la actividad general del cliente

4.6 transactional_last_sale_at

Fecha de ultima venta general del cliente, sin importar vendedor.

Lectura correcta:

  • sirve para medir actividad real de la cuenta
  • puede ser posterior a la ultima venta del vendedor asignado

4.7 seller_mismatch

Indicador de diferencia entre vendedor asignado y vendedor transaccional.

Lectura correcta:

  • no es un error automatico
  • es una senal analitica valiosa
  • puede indicar desarrollo por terceros, cuenta compartida, abandono, reactivacion o canal compartido

5. Situaciones comerciales que el modelo debe contemplar

El modelo debe soportar explicitamente casos donde:

  • un cliente asignado a un vendedor sea trabajado por otro vendedor
  • un vendedor abandone una cuenta
  • otro vendedor reactive o desarrolle esa cuenta
  • la ultima compra general del cliente sea de un vendedor distinto al asignado
  • la ultima compra del vendedor asignado sea anterior a la ultima compra general
  • un cliente tenga actividad compartida entre vendedores

6. Reglas obligatorias

  • para atribuir ventas, usar seller_transactional
  • para medir cartera asignada, usar seller_assigned
  • para medir territorio comercial formal, partir de clientes asignados
  • para medir desempeno real de ventas, usar vendedor transaccional
  • para detectar abandono de cuenta, comparar actividad del vendedor asignado contra actividad general del cliente
  • para detectar desarrollo por terceros, identificar ventas recientes de vendedores distintos al asignado
  • no sobrescribir Codigo_vendedor / Nombre_Vendedor de SOURCE-001 por una venta aislada de SOURCE-003
  • no asumir que la ultima compra general fue hecha por el vendedor asignado
  • no asumir que una cuenta esta trabajada por el vendedor asignado solo porque tuvo ventas
  • las diferencias assigned vs transactional deben conservarse como senal analitica
  • las ventas deben computarse al vendedor que realmente las hizo

7. Estados analiticos sugeridos

Estados conceptuales futuros:

  • worked_by_assigned_seller
  • worked_by_other_seller
  • shared_account
  • account_abandoned_by_assigned_seller
  • account_reactivated_by_assigned_seller
  • account_reactivated_by_other_seller
  • no_recent_activity
  • seller_mismatch
  • unknown_customer
  • missing_transaction_seller
  • ecommerce_or_shared_channel
  • manual_review

Regla de prudencia:

  • estos estados son lecturas derivadas futuras
  • no deben cargarse como verdad primaria
  • sus umbrales y ventanas de tiempo siguen pendientes

8. Metricas futuras por cliente

Metricas conceptuales futuras:

  • fecha_ultima_compra_general
  • vendedor_ultima_compra
  • fecha_ultima_compra_vendedor_asignado
  • fecha_ultima_compra_vendedor_no_asignado
  • dias_sin_compra_general
  • dias_sin_compra_vendedor_asignado
  • vendedor_asignado_trabaja_cuenta
  • cuenta_trabajada_por_otro_vendedor
  • cuenta_compartida
  • cuenta_abandonada
  • cuenta_reactivada

9. Metricas futuras por vendedor

Metricas conceptuales futuras:

  • clientes_asignados
  • clientes_con_venta_propia
  • clientes_sin_movimiento
  • clientes_operados_por_terceros
  • clientes_recuperados
  • clientes_abandonados
  • ventas_de_cartera_propia
  • ventas_fuera_de_cartera
  • ventas_a_clientes_asignados_a_otros
  • ventas_perdidas_por_actividad_de_terceros
  • cartera_trabajada
  • cartera_no_trabajada
  • cartera_desarrollada_por_otro_vendedor

10. Preguntas de negocio que el modelo debe responder

  • quien tiene asignado el cliente
  • quien le vendio por ultima vez
  • cuando fue la ultima venta del vendedor asignado
  • cuando fue la ultima venta de cualquier vendedor
  • existe otro vendedor desarrollando la cuenta
  • la cuenta fue abandonada por el vendedor asignado
  • la cuenta fue recuperada
  • quien reactivo la cuenta
  • que vendedor esta captando ventas fuera de su cartera
  • cuantos clientes de su cartera trabaja efectivamente cada vendedor
  • cuantos clientes estan siendo desarrollados por terceros
  • que clientes tienen venta reciente pero no del vendedor asignado
  • que clientes tienen vendedor asignado pero no ventas recientes de ese vendedor

11. Interaccion con otras lecturas analiticas

11.1 Territorio comercial formal

Debe partir de:

  • clientes asignados desde SOURCE-001
  • geografia del cliente
  • zona logistica como dimension operativa

11.2 Desempeno real de ventas

Debe partir de:

  • vendedor transaccional desde SOURCE-003
  • importe vendido
  • periodo
  • cliente
  • SKU

11.3 Mix comercial real

Debe partir de:

  • SOURCE-003 para venta real
  • SOURCE-002 para enriquecer SKU, marca, proveedor y categoria

11.4 Seller effective por contexto

Regla obligatoria:

  • si la pregunta es sobre ownership formal, usar seller_assigned
  • si la pregunta es sobre facturacion real, usar seller_transactional
  • si una metrica usa seller_effective, debe declarar que version adopta

11.5 Relacion con Customer Ownership Analytics

Lectura obligatoria:

  • ownership_assigned nace de seller_assigned
  • ownership_last_sale nace de seller_transactional
  • ownership_effective, recuperacion, crecimiento, riesgo y abandono deben respetar esta reconciliacion conceptual y no inventar una tercera verdad primaria del vendedor

12. Validacion real exploratoria 2026-06-09

Validacion ejecutada en modo de solo lectura, sin crear tablas, sin crear vistas, sin modificar datos y registrando solo agregados.

Campos reales respaldados por la autoridad SOURCE-003 / Tabla 2 y por la consulta exploratoria:

  • cliente transaccional: LTRIM(RTRIM(v.CodigoCliente))
  • vendedor transaccional: LTRIM(RTRIM(v.Vendedor))
  • nombre vendedor transaccional: LTRIM(RTRIM(v.NomVendedor))
  • fecha de venta: v.Fecha
  • filtro documental valido: v.Estado <> 'ANULADO'
  • filtro exploratorio prudente para actividad comercial real: TipoComp IN ('FACTURA A','GUIA DE DESPACHO','FACTURA B')

Ventana exploratoria usada:

  • ventana principal: 2026-03-11 a 2026-06-09 (90 dias)
  • cortes complementarios sin cerrar umbrales: 30 / 60 / 90 dias

Resultado agregado observado para reconciliacion en la ventana de 90 dias:

Medida Resultado observado
ventas validas exploratorias 97885
ventas con cliente mapeado a SOURCE-001 97885
ventas sin cliente mapeado 0
ventas con seller_assigned = seller_transactional 95690
ventas con seller_assigned <> seller_transactional 2195
coincidencia sobre ventas mapeadas 97.76%
mismatch sobre ventas mapeadas 2.24%

Resultado agregado observado para ultima venta del cliente en la misma ventana:

Medida Resultado observado
clientes con ultima venta del vendedor asignado 1851
clientes con ultima venta de otro vendedor 47
clientes con ultima venta ambigua por multi-vendedor en la misma fecha 0

Resultado agregado observado para clientes activos asignados sin venta reciente del vendedor asignado:

Ventana Clientes activos con ventas en 90d Sin venta reciente del asignado Con venta reciente de otro vendedor Sin venta reciente en absoluto
30 dias 1898 421 29 392
60 dias 1898 198 29 169
90 dias 1898 28 28 0

Top vendedores transaccionales con ventas sobre cartera ajena (seller_code enmascarado):

Seller Ventas mismatch Clientes distintos
S-016 667 17
S-035 419 15
S-009 172 4
S-032 172 11
S-080 154 7

Top vendedores asignados cuyas carteras recibieron ventas de terceros (seller_code enmascarado):

Seller Ventas mismatch recibidas Clientes distintos
S-080 657 16
S-093 288 7
S-032 207 15
S-072 154 5
S-094 115 1

Distribucion observada de mismatch por canal / ramo:

Canal Ramo Ventas mismatch Clientes distintos
OTROS SUPER CHINO 1369 47
NULL/VACIO SIN ASIGNAR 281 8
OTROS CLIENTE PARTICULAR 279 23
TRADIC ALMACEN GRANDE 124 2
OTROS REVENDEDOR 119 6

Lectura prudente respaldada:

  • la relacion seller_assigned vs seller_transactional es medible con los campos actuales
  • el cliente transaccional quedo mapeado 100% contra SOURCE-001 en la ventana exploratoria
  • el mismatch existe y no es teorico, pero aparece acotado en la ventana de 90 dias
  • no se observaron casos de manual_review por cliente no mapeado, vendedor faltante o ultima venta ambigua en la ventana exploratoria
  • la lectura por canal sigue en AMARILLO: la taxonomia parcial ya permite usar TRADIC, KIOSCO y NULL/VACIO -> SIN ASIGNAR, pero OTROS sigue necesitando apoyo de Ramo y no aparecio evidencia suficiente para cerrar ecommerce o canal compartido a nivel de canal completo

Veredicto exploratorio recomendado:

  • estado general de medibilidad: AMARILLO
  • motivo: medible con evidencia fuerte en cliente, vendedor y fecha, pero con ambiguedad abierta en taxonomia de canal compartido / ecommerce

13. Restricciones obligatorias

  • no crear SQL real todavia
  • no crear vistas fisicas todavia
  • no crear materialized views todavia
  • no cerrar reglas finales de ecommerce o canales compartidos sin evidencia
  • no usar WhatsApp como identificador
  • no excluir clientes de baja del analisis historico
  • no usar Zona como vendedor
  • no usar zona logistica como territorio comercial de vendedor
  • no atribuir ventas al vendedor asignado si la venta la hizo otro vendedor

14. Pendientes preservados

Quedan explicitamente pendientes:

  • SQL real de reconciliacion
  • reglas finales para ecommerce o canales compartidos
  • validar si los subcasos OTROS + REVENDEDOR o clientes multiseller por canal deben escalar a manual_review estable
  • definicion de umbrales de abandono
  • definicion de ventana temporal para cuenta trabajada
  • diseno fisico de vista o materialized view
  • performance real
  • permisos de consumo
  • ampliar la validacion real a otras ventanas y cortes historicos si negocio necesita confirmar estacionalidad o drift comercial
  • ampliar la taxonomia funcional de canal mas alla del cierre parcial documentado en SOURCE-003-CHANNEL-TAXONOMY.md

15. Confirmaciones de alcance

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