Saltar a contenido

Territory Alias Catalog 001 - SOURCE-001 Clientes

Fecha: 2026-06-09

Estado: CATALOGO DOCUMENTAL INICIAL / NO IMPLEMENTADO

Scope: tenant

tenant_id: alpuntodeventa

Owner: Gabi / Carlos Canu

Fuente de verdad: docs/tenants/alpuntodeventa/business-observer/territory/TERRITORY-ALIAS-CATALOG-001.md

Fuentes relacionadas:

  • docs/tenants/alpuntodeventa/business-observer/territory/TERRITORY-NORMALIZATION-STRATEGY.md
  • docs/tenants/alpuntodeventa/business-observer/territory/TERRITORY-HUMAN-REVIEW-001.md
  • 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/BUSINESS-OBSERVER-DATA-CONTRACT-001.md
  • docs/tenants/alpuntodeventa/business-observer/sources/SOURCE-001-SGC-CLIENTES.md

Preparar el inventario documental del catalogo real de alias territoriales para SOURCE-001 Clientes, dejando trazadas:

  • la evidencia raw observada
  • la propuesta de canonicalizacion
  • las reglas futuras de alias
  • la normalizacion de Zona como agrupacion logistica
  • el marco de aprobacion humana posterior

Este documento:

  • no crea tablas
  • no crea migraciones
  • no modifica datos
  • no toca runtime
  • no reemplaza el valor raw observado en el SGC
  • no reemplaza la aprobacion humana final requerida para aliases

2. Alcance inicial

Alcance inicial cubierto por este catalogo:

  • Provincia
  • Localidad
  • Zona

Alcance inicial no cubierto todavia:

  • microzonas fisicas cerradas
  • geocodificacion
  • relaciones geograficas oficiales externas
  • carga real del catalogo en base
  • aprobacion humana final alias por alias

3. Evidencia raw observada

La evidencia real ya documentada para ecommerce.dbo.VCLIENTES deja este inventario base:

3.1 Cobertura territorial observada

Medida Resultado observado
filas totales 11404
Localidad informada 11404
Provincia informada 11404
Zona informada 11403
Zona NULL/VACIO 1
provincias distintas 24
localidades distintas 516
zonas distintas 365

3.2 Valores raw principales de Provincia

Provincia raw Cantidad observada
BUENOS AIRES 7311
CABA 3749
SANTA FE 51
CORDOBA 38
MISIONES 28
ENTRE RIOS 27
RIO NEGRO 19
CHUBUT 18
NEUQUEN 18
CORRIENTES 17

Lectura:

  • Provincia tiene cobertura completa
  • no se observaron NULL/VACIO
  • puede tratarse como senal fuerte con normalizacion conservadora

3.3 Valores raw principales de Localidad

Top 10 pares provincia + localidad observados:

Provincia raw Localidad raw Cantidad observada
CABA PALERMO 303
BUENOS AIRES JOSE C. PAZ 281
CABA RECOLETA 249
CABA BELGRANO 248
CABA BALVANERA 233
BUENOS AIRES SAN MIGUEL 223
CABA ALMAGRO 181
CABA VILLA CRESPO 168
BUENOS AIRES CAMPANA 165
BUENOS AIRES VILLA ADELINA 156

Variantes textuales observadas o explicitamente respaldadas por evidencia:

  • JOSE C. PAZ
  • JOSE C PAZ
  • VILLA ADELINA

Lectura:

  • Localidad tiene cobertura completa
  • la dispersion observada exige alias aprobados
  • la canonicalizacion debe corregir puntuacion y espacios sin borrar el raw

3.4 Valores raw principales de Zona

Zona raw Cantidad observada
NO DEFINIDA 1522
ZONA 13-JOSE C. PAZ 265
ZONA 01-PALERMO 236
ZONA 01-BALVANERA 213
ZONA 13-SAN MIGUEL 181
ZONA 01-RECOLETA 175
ZONA 01-ALMAGRO 158
ZONA 08-BELGRANO 154
ZONA 15-CAMPANA 154
ZONA 01-VILLA CRESPO 143

Resumen estructural observado de Zona:

Tipo de valor observado Resultado
NO DEFINIDA 1522
NULL/VACIO 1
con prefijo ZONA 9437
texto libre no prefijado 444
zonas con 1 provincia 289
zonas multi-provincia 76
clientes en zonas multi-provincia 6365

Ejemplos agregados de dispersion admitida:

  • NO DEFINIDA aparece en 3 provincias y 137 localidades
  • ZONA 06-RAMOS MEJIAS aparece en 3 provincias
  • MISIONES aparece como Zona y cubre 2 provincias
  • CORRIENTES aparece como Zona y cubre 2 provincias

Lectura:

  • Zona no es geografia pura
  • en SOURCE-001, Zona representa una agrupacion logistica y no un territorio comercial del vendedor
  • Zona necesita normalizacion documental, pero no debe reinterpretarse como ownership comercial
  • zonas multi-provincia no son error automatico

4. Propuesta de canonicalizacion

4.1 Regla general

Toda canonicalizacion futura debe preservar:

  • alias_raw
  • canonical_value
  • evidencia de origen
  • capacidad de volver al valor observado

Regla obligatoria:

  • la limpieza no debe ser destructiva
  • raw y canonical deben convivir

4.2 Provincia

Propuesta inicial:

  • conservar Provincia exacta como raw
  • usar un canon textual conservador en mayusculas estables
  • no inferir cambios semanticos sin evidencia adicional

Nivel esperado de automatizacion inicial:

  • automatic para trim y espacios controlados
  • suggested si aparece abreviatura o variante no observada todavia

4.3 Localidad

Propuesta inicial:

  • conservar Localidad exacta como raw
  • remover diferencias solo textuales aprobadas: puntuacion, espacios duplicados y abreviaturas controladas
  • no fusionar localidades distintas por similitud superficial

Ejemplo canonico documentado:

  • JOSE C. PAZ -> JOSE C PAZ

4.4 Zona logistica

Propuesta inicial:

  • conservar Zona exacta como raw
  • clasificar zona_type como logistic_zone, undefined o unknown
  • definir despues canonical_value dentro del tipo
  • preservar el prefijo ZONA cuando sea parte util del valor observado
  • preservar el numero de zona como agrupador logistico de localidades
  • admitir como canon esperado formatos Zona xx - Localidad y ZONA 00 - INTERIOR DEL PAIS

Ejemplos documentados:

  • NO DEFINIDA -> zona_type = undefined
  • NULL/VACIO -> zona_type = unknown

Interpretacion:

  • NO DEFINIDA es dato observado, no ausencia
  • NULL/VACIO es ausencia de dato, no valor territorial

5. Reglas de alias

Reglas iniciales para el catalogo:

  1. el valor raw nunca se pisa ni se reemplaza en origen
  2. un alias solo puede apuntar a un canon cuando haya evidencia suficiente
  3. la normalizacion textual simple no habilita fusion semantica agresiva
  4. NO DEFINIDA debe preservarse como valor observado
  5. NULL/VACIO debe registrarse como ausencia diferenciada
  6. zonas multi-provincia pueden seguir activas sin marcarse como error
  7. una misma Zona puede requerir manual_review aunque su texto sea estable
  8. si una regla cambia el significado y no solo la forma, requiere aprobacion humana

Reglas textuales sugeridas para Localidad y Provincia:

  • trim de extremos
  • compresion de espacios internos repetidos
  • remocion controlada de puntuacion solo cuando no cambie identidad
  • unificacion de abreviaturas aprobadas

Reglas textuales sugeridas para Zona:

  • trim de extremos
  • preservacion de ZONA cuando sea parte de la taxonomia observada
  • no convertir automaticamente zonas no prefijadas en zonas prefijadas
  • no asumir que una zona textual igual a provincia representa provincia canonica

6. Regla semantica de Zona

Taxonomia documental vigente de zona_type para SOURCE-001:

  • logistic_zone
  • undefined
  • unknown

Lectura funcional de cada clase:

  • logistic_zone: agrupacion de entrega, reparto, recorrido y armado de rutas
  • undefined: el origen declara no definicion
  • unknown: falta dato o no hay clasificacion confiable todavia

Criterio inicial de asignacion:

  • NO DEFINIDA -> undefined
  • NULL/VACIO -> unknown
  • ZONA nn-... debe interpretarse como logistic_zone
  • zonas textuales no prefijadas como MISIONES o CORRIENTES requieren manual_review porque pueden representar macrozona logistica o uso legado

7. Nivel de confianza

Estados documentales permitidos para el catalogo:

  • automatic
  • suggested
  • manual_review

Criterio inicial:

  • automatic: normalizacion textual obvia sin cambio semantico
  • suggested: propuesta razonable con evidencia parcial pero sin aprobacion final
  • manual_review: caso ambiguo, multi-significado o con impacto semantico

Ejemplos:

  • JOSE C. PAZ -> JOSE C PAZ: automatic o suggested segun aprobacion del equipo
  • NO DEFINIDA -> undefined: automatic
  • NULL/VACIO -> unknown: automatic
  • MISIONES como Zona: manual_review

Paquete de revision humana relacionado:

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

8. Regla de aprobacion futura

Todo alias futuro aprobado debera poder registrar como minimo:

  • approved_by
  • approved_at
  • source_evidence

Interpretacion:

  • approved_by identifica a la persona o rol que valida el alias
  • approved_at fija la fecha efectiva de aprobacion
  • source_evidence referencia la evidencia agregada o documento que respalda la decision

Esta estructura es solo documental y no debe leerse como DDL cerrado:

  • 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

Lectura sugerida de campos:

  • territory_level: province, locality, zone o futuro equivalente
  • territory_type: tipo semantico del territorio canonico, en especial para Zona
  • confidence_status: automatic, suggested o manual_review
  • active: permite desactivar alias sin borrar evidencia historica

10. Decisiones documentadas

  • Provincia queda respaldada como senal territorial fuerte
  • Localidad queda respaldada como senal territorial fuerte con higiene textual
  • Zona queda respaldada como senal logistica y requiere normalizacion semantica no destructiva
  • Zona no define vendedor responsable
  • la pregunta por territorio comercial del vendedor debe resolverse con clientes asignados + ventas + productos + geografia
  • NO DEFINIDA debe preservarse y mapearse como undefined
  • NULL/VACIO debe diferenciarse y mapearse como unknown
  • zonas multi-provincia no se tratan como error automatico
  • el catalogo debe ser no destructivo y trazable

11. Advertencia obligatoria

Este catalogo no debe hacer limpieza destructiva.

Regla madre:

  • ningun valor raw observado en SOURCE-001 debe perderse por la existencia de una forma canonica posterior

12. Pendientes preservados

Este catalogo deja explicitamente pendientes:

  • diseno fisico final
  • carga real del catalogo
  • revision humana de aliases
  • definicion fisica final de vistas analiticas de territorio comercial
  • cruce final con SOURCE-002 y SOURCE-003
  • geocodificacion futura

13. Confirmaciones de alcance

  • sin runtime
  • sin tablas
  • sin migraciones
  • sin modificaciones de datos
  • sin datos personales
  • solo documentacion