Territory Normalization Strategy - SOURCE-001 Clientes

Fecha: 2026-06-09

Estado: ESTRATEGIA CANONICA DOCUMENTADA / NO IMPLEMENTADA

Scope: tenant

tenant_id: alpuntodeventa

Owner: Gabi / Carlos Canu

Fuente de verdad: docs/tenants/alpuntodeventa/business-observer/territory/TERRITORY-NORMALIZATION-STRATEGY.md

Fuentes relacionadas:

• docs/tenants/alpuntodeventa/business-observer/SOURCE-INVENTORY-RESULTS-001.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/BUSINESS-OBSERVER-DATA-CONTRACT-001.md
• docs/tenants/alpuntodeventa/business-observer/territory/TERRITORY-ALIAS-CATALOG-001.md
• docs/tenants/alpuntodeventa/business-observer/territory/TERRITORY-HUMAN-REVIEW-001.md
• docs/governance/standards/DATA-DESIGN-STANDARD.md

1. Objetivo

Definir la estrategia canonica de normalizacion territorial para SOURCE-001 Clientes antes de cerrar el diseno fisico futuro.

Esta estrategia:

• no crea tablas
• no crea migraciones
• no ejecuta queries
• no toca runtime
• no reemplaza la evidencia ya registrada
• deja referenciado el catalogo documental inicial de alias territoriales en: docs/tenants/alpuntodeventa/business-observer/territory/TERRITORY-ALIAS-CATALOG-001.md

2. Lectura base respaldada por evidencia

Al 2026-06-08, la evidencia real documentada para ecommerce.dbo.VCLIENTES deja esta lectura operativa:

• Provincia tiene cobertura completa y puede tratarse como senal fuerte
• Localidad tiene cobertura completa y puede tratarse como senal fuerte, aunque requiere higiene textual
• Zona tiene cobertura casi completa, pero no debe leerse como geografia pura ni como territorio comercial del vendedor
• existen variantes textuales de localidad, por ejemplo JOSE C. PAZ y JOSE C PAZ
• existen zonas NO DEFINIDA, zonas con prefijo ZONA y zonas no prefijadas
• existen zonas multi-provincia y eso no debe tratarse como error automatico
• falta aprobacion humana final sobre aliases territoriales

3. Arquitectura territorial canonica

La arquitectura canonica futura para cliente debe preservar niveles territoriales separados y trazables.

Nivel 1 - Provincia

Campos canonicos:

• provincia_raw
• provincia_normalized

Nivel 2 - Localidad

Campos canonicos:

• localidad_raw
• localidad_normalized

Nivel 3 - Zona logistica

Campos canonicos:

• zona_raw
• zona_type
• zona_normalized

Regla canonica inicial de zona_type para SOURCE-001:

• logistic_zone
• undefined
• unknown

Nivel 4 - Microzona opcional

Campo canonico opcional:

• microzona_normalized

Nivel 5 - Territorio comercial derivado

Campos relacionados:

• codigo_vendedor
• nombre_vendedor
• cartera real de clientes asignados
• localidad y provincia de esos clientes
• zona logistica de esos clientes
• ventas reales desde SOURCE-003
• SKU, marca, proveedor y categoria desde SOURCE-002 y SOURCE-003

Lectura:

• el vendedor responsable sale de Codigo_vendedor / Nombre_Vendedor
• el vendedor no reemplaza Provincia, Localidad ni Zona
• el territorio comercial del vendedor no se responde con Zona
• el territorio comercial del vendedor debe derivarse de su cartera real de clientes asignados y del cruce posterior con ventas, productos y geografia

4. Reglas canonicas de normalizacion

4.1 Reglas transversales

• toda normalizacion debe preservar el valor original del SGC
• no hacer hard clean destructivo
• raw y normalized deben convivir
• los modelos analiticos deben consumir normalized
• auditoria, trazabilidad y soporte deben poder volver al raw

4.2 Provincia

• Provincia puede considerarse senal fuerte por cobertura completa
• debe mantenerse como provincia_raw + provincia_normalized
• la normalizacion de provincia puede ser estricta y conservadora porque la evidencia muestra cobertura total

4.3 Localidad

• Localidad puede considerarse senal fuerte por cobertura completa
• requiere normalizacion textual controlada
• debe mantenerse como localidad_raw + localidad_normalized
• variantes como JOSE C. PAZ y JOSE C PAZ deben resolverse por alias aprobados y no por limpieza destructiva

4.4 Zona

• Zona no debe tratarse como geografia pura
• Zona debe tratarse como agrupacion logistica para rutas, reparto, despacho y armado operativo de recorridos
• Zona debe mantenerse como zona_raw + zona_type + zona_normalized
• Zona no debe usarse para inferir vendedor responsable
• Zona no define ownership comercial
• el formato correcto esperado para Zona en SOURCE-001 es Zona xx - Localidad
• el numero xx agrupa localidades para operacion logistica
• para interior del pais debe admitirse ZONA 00 - INTERIOR DEL PAIS
• NO DEFINIDA debe conservarse como valor observado y no eliminarse
• NULL/VACIO debe diferenciarse de NO DEFINIDA
• zonas multi-provincia no son error automatico; pueden representar cobertura operativa amplia

4.5 Null, vacio y valores observados

• NO DEFINIDA implica valor textual observado y debe preservarse
• NULL/VACIO implica ausencia de dato y debe quedar diferenciado
• unknown aplica cuando un valor existe pero aun no puede clasificarse con confianza suficiente
• undefined aplica cuando el propio origen declara falta de definicion, por ejemplo NO DEFINIDA

5. Criterio canonico de zona

La zona necesita semantica separada de la geografia y de la cartera comercial.

• logistic_zone: agrupa entrega, distribucion, reparto o recorrido logistico
• undefined: el origen explicita no definicion, por ejemplo NO DEFINIDA
• unknown: existe valor observado, pero aun no hay clasificacion confiable

6. Usos futuros que esta estrategia habilita

Casos habilitados:

• territorio fertil
• territorio perdido
• recuperacion comercial
• clientes activos por vendedor y localidad
• clientes de baja por vendedor y provincia
• ventas por vendedor y zona logistica
• marcas vendidas por vendedor y localidad
• proveedores dominantes por cartera de vendedor
• territorio perdido por vendedor
• oportunidades de recuperacion por vendedor
• mix de SKU por localidad, provincia y vendedor
• clientes a captar para recomponer masa comercial por vendedor
• oportunidades por zona logistica
• rutas logisticas
• alertas
• dashboards
• analisis con Python
• machine learning
• interaccion futura con LLM / IA

Regla de diseno:

• los casos de uso futuros deben consumir normalized
• los motores de auditoria, trazabilidad y explicacion deben poder volver a raw

7. Criterio de diseno fisico futuro

Esta estrategia no cierra tablas finales, pero si fija criterios para el diseno posterior.

7.1 customers_address

customers_address debe guardar raw + normalized para territorio.

Minimo esperado:

• provincia_raw
• provincia_normalized
• localidad_raw
• localidad_normalized
• zona_raw
• zona_type
• zona_normalized
• microzona_normalized solo si corresponde

7.2 Catalogo territorial separado

Debe considerarse una capa separada de catalogo territorial para sostener:

• normalizaciones aprobadas
• catalogo canonico de zonas logisticas
• relaciones futuras entre provincia, localidad, zona y microzona

Y debe poder cruzarse despues con:

• cartera real por vendedor
• ventas reales
• SKU
• marcas
• proveedores
• categorias

7.3 Tabla futura de alias territoriales

Debe considerarse una tabla o catalogo de alias con estos campos minimos:

• alias_raw
• canonical_value
• confidence_status
• approved_by
• approved_at

Inventario documental inicial ya preparado en:

• docs/tenants/alpuntodeventa/business-observer/territory/TERRITORY-ALIAS-CATALOG-001.md

Paquete de revision humana preparado en:

• docs/tenants/alpuntodeventa/business-observer/territory/TERRITORY-HUMAN-REVIEW-001.md

Campos sugeridos ampliados para el catalogo futuro:

• tenant_id
• source_system
• source_field
• alias_raw
• canonical_value
• territory_level
• territory_type
• confidence_status
• approved_by
• approved_at
• active
• notes
• created_at
• updated_at

7.4 Consumo analitico y auditoria

• los modelos analiticos deben consumir valores normalized
• las auditorias deben poder reconstruir el valor raw
• raw no debe descartarse aunque normalized exista

8. Decisiones documentadas

• Provincia queda tratada como senal territorial fuerte
• Localidad queda tratada como senal territorial fuerte con higiene textual
• Zona queda tratada como senal logistica antes que como geografia pura
• Zona requiere zona_type
• NO DEFINIDA se preserva como valor observado
• NULL/VACIO no equivale a NO DEFINIDA
• zonas multi-provincia no se consideran error automatico
• en SOURCE-001, Zona queda definida como agrupacion logistica y no comercial
• Zona no debe usarse para inferir vendedor responsable
• el vendedor responsable sale de Codigo_vendedor / Nombre_Vendedor
• el territorio comercial del vendedor se deriva de clientes asignados, geografia, ventas y productos; no de Zona
• toda normalizacion territorial futura debe preservar raw + normalized

9. Pendientes que esta estrategia preserva

Esta estrategia no debe interpretarse como cierre de estos puntos:

• diseno fisico final de tablas
• normalizacion definitiva de WhatsApp
• carga real del catalogo de alias territoriales
• revision humana final de aliases territoriales
• definicion fisica final de vistas analiticas de territorio comercial
• cruce final con SOURCE-002 y SOURCE-003
• decision futura de geocodificacion

10. Confirmaciones de alcance

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