SOURCE-001 Clientes Mapping

Fecha: 2026-06-09

Estado: MAPEO CONCEPTUAL FUTURO / NO IMPLEMENTADO

Scope: tenant

tenant_id: alpuntodeventa

Owner: Gabi / Carlos Canu

Fuente de verdad: docs/tenants/alpuntodeventa/business-observer/mappings/SOURCE-001-CLIENTES-MAPPING.md

Autoridad base relacionada: docs/tenants/alpuntodeventa/business-observer/source-authority/SOURCE-001-CLIENTES-VCLIENTES-AUTHORITY.md

Fuente funcional relacionada: docs/tenants/alpuntodeventa/business-observer/sources/SOURCE-001-SGC-CLIENTES.md

Contrato relacionado: docs/tenants/alpuntodeventa/business-observer/BUSINESS-OBSERVER-DATA-CONTRACT-001.md

Estandar global relacionado: docs/governance/standards/DATA-DESIGN-STANDARD.md

1. Proposito

Este documento baja SOURCE-001 a un primer mapeo origen-destino campo por campo, sin crear tablas, sin cerrar SQL fisico y sin abrir runtime.

La intencion es dejar documentado como deberia viajar cada dato de ecommerce.dbo.VCLIENTES hacia bloques logicos futuros de la Data Foundation de OpenClaw Business Observer.

2. Reglas obligatorias ya cerradas

• tenant_id + codigo_cliente es la clave logica fuerte del dominio cliente derivado de SOURCE-001
• codigo_cliente debe canonicalizarse como NULLIF(LTRIM(RTRIM([Codigo])), '')
• estado_raw conserva el valor textual original de SGC
• customer_status y can_sell son derivados y no reemplazan estado_raw
• WhatsApp debe guardarse como raw + normalized + quality_status
• WhatsApp no es identificador unico del cliente
• Telefono / WhatsApp no debe usarse como clave unica ni como ancla de relacion entre grupos
• clientes CLIENTE DE BAJA y CLIENTE SUSPENDIDO no deben eliminarse
• filtros de venta o facturacion deben vivir en vistas o capas de consumo
• fecha_alta_sgc no equivale a created_at
• created_at y updated_at son timestamps internos de OpenClaw
• extracted_at y last_seen_at controlan sincronizacion y reconciliacion
• source_row_hash controla deteccion de cambios de fila
• sync_batch_id permite auditar la corrida de sync
• la estrategia territorial canonica previa al diseno fisico final vive en: docs/tenants/alpuntodeventa/business-observer/territory/TERRITORY-NORMALIZATION-STRATEGY.md
• el catalogo documental inicial de aliases territoriales vive en: docs/tenants/alpuntodeventa/business-observer/territory/TERRITORY-ALIAS-CATALOG-001.md
• customers_address debe preservar territorio como raw + normalized aunque los nombres fisicos finales sigan abiertos

3. Bloques logicos destino

Los bloques logicos recomendados para el primer mapeo documental son:

• customers_core
• customers_contact
• customers_address
• customers_tax
• customers_commercial
• customers_sales_owner
• customers_visit_schedule
• source_001_customer_audit

Regla de interpretacion:

• estos bloques son logicos y no cierran todavia la estrategia final de tablas fisicas
• todos siguen subordinados al mismo cliente SGC
• todos deben relacionarse por tenant_id + codigo_cliente

4. Matriz campo por campo

Campo origen SGC	Alias / expresion autoridad	Campo destino recomendado	Bloque logico	Tipo PostgreSQL sugerido	Naturaleza	Hash	Sensible	Indice	Uso futuro	Observaciones
Codigo	RTRIM([Codigo]) AS codigo_cliente	codigo_cliente	customers_core	text	normalized	si	no	si	operacion, BI, ML, IA, automatizacion, auditoria	clave logica fuerte junto con tenant_id; canonicalizar con NULLIF(LTRIM(RTRIM([Codigo])), '')
Nombre, Nombre_en_Factura, Codigo	COALESCE(NULLIF(RTRIM([Nombre]), ''), NULLIF(RTRIM([Nombre_en_Factura]), ''), RTRIM([Codigo])) AS cliente_nombre	customer_name	customers_core	text	derived	si	no	si	operacion, BI, ML, IA	nombre visible principal; no reemplaza razon_social
Nombre_en_Factura	RTRIM([Nombre_en_Factura]) AS razon_social	legal_name	customers_core	text	raw	si	si	si	operacion, BI, auditoria	puede coincidir con el nombre visible o venir vacio
Direccion_de_pedidos	RTRIM([Direccion_de_pedidos]) AS direccion_pedidos	delivery_address_raw	customers_address	text	raw	si	si	no	operacion, BI, IA	direccion operativa; no cerrar todavia parsing estructurado
Localidad	RTRIM([Localidad]) AS localidad	city_raw	customers_address	text	raw	si	si	si	operacion, BI, ML, IA	corrida real 2026-06-08 observo cobertura completa (11404/11404) y 516 valores distintos; preservar raw y resolver su equivalente canonico en localidad_normalized segun TERRITORY-NORMALIZATION-STRATEGY
Localidad	RTRIM([Localidad]) AS localidad	city_normalized	customers_address	text	normalized	no	si	si	operacion, BI, ML, IA	capa canonica para alias territoriales, puntuacion, abreviaturas y variantes como JOSE C. PAZ / JOSE C PAZ; debe gobernarse por TERRITORY-ALIAS-CATALOG-001 y no reemplaza el valor original
Provincia	RTRIM([Provincia]) AS provincia	state_province_raw	customers_address	text	raw	si	si	si	operacion, BI, ML, IA	corrida real 2026-06-08 observo cobertura completa (11404/11404) y 24 provincias distintas; preservar valor fuente exacto
Provincia	RTRIM([Provincia]) AS provincia	state_province_normalized	customers_address	text	normalized	no	si	si	operacion, BI, ML, IA	canon territorial fuerte para consumo analitico; no elimina el raw
EntreCalles	RTRIM([EntreCalles]) AS entre_calles	cross_streets_raw	customers_address	text	raw	si	si	no	operacion, IA	referencia complementaria de ubicacion
Zona	RTRIM([Zona]) AS zona	logistic_zone_raw	customers_address	text	raw	si	no	si	operacion, BI, ML, IA, automatizacion	corrida real 2026-06-08 observo cobertura casi completa (11403/11404), 365 valores distintos, 1522 casos NO DEFINIDA y mezcla multi-provincia en parte del catalogo; en SOURCE-001 debe leerse como agrupacion logistica para rutas y no como territorio comercial del vendedor
Zona	RTRIM([Zona]) AS zona	logistic_zone_type	customers_address	text	derived	no	no	si	operacion, BI, ML, IA, automatizacion	clasificacion canonica requerida para SOURCE-001: logistic_zone, undefined o unknown; NO DEFINIDA debe mapear a undefined y NULL/VACIO a unknown
Zona	RTRIM([Zona]) AS zona	logistic_zone_normalized	customers_address	text	normalized	no	no	si	operacion, BI, ML, IA, automatizacion	forma canonica futura de zona logistica; debe gobernarse por TERRITORY-ALIAS-CATALOG-001, preservar raw, admitir formatos Zona xx - Localidad y no confundir NO DEFINIDA con NULL/VACIO
Nota_en_comprobante	RTRIM([Nota_en_comprobante]) AS horarios_entrega	delivery_notes_raw	customers_address	text	raw	si	si	no	operacion, IA	hoy sirve como nota operativa; no asumir estructura de horario cerrada
Telefono	RTRIM([Telefono]) AS whatsapp	whatsapp_raw	customers_contact	text	raw	si	si	no	operacion, BI, IA, automatizacion, auditoria	no usar como identificador unico
Telefono	RTRIM([Telefono]) AS whatsapp	whatsapp_normalized	customers_contact	text	normalized	no	si	si	operacion, automatizacion, IA	normalizacion definitiva pendiente por formatos heterogeneos
Telefono	RTRIM([Telefono]) AS whatsapp	whatsapp_quality_status	customers_contact	text	derived	no	si	si	operacion, BI, automatizacion, auditoria	semaforo esperado al menos validado, observado, pendiente o equivalente
Lista_Precio	RTRIM([Lista_Precio]) AS lista_precio	price_list_code_raw	customers_commercial	text	raw	si	no	si	operacion, BI, ML, IA	utilidad comercial plausible; falta cierre de catalogo y vigencia real
Ramo	RTRIM([Ramo]) AS canal	channel_raw	customers_commercial	text	raw	si	no	si	operacion, BI, ML, IA	tratar como clasificacion comercial textual hasta validar catalogo
Categoria	RTRIM([Categoria]) AS categoria	customer_category_raw	customers_commercial	text	raw	si	no	si	operacion, BI, ML, IA	clasificacion comercial del cliente; puede requerir normalizacion posterior
Codigo_vendedor	RTRIM([Codigo_vendedor]) AS codigo_vendedor	seller_code_raw	customers_sales_owner	text	raw	si	no	si	operacion, BI, ML, IA, automatizacion	ownership comercial relevante; corrida real 2026-06-08 observo cobertura completa y relacion 1:1 con Nombre_Vendedor dentro de VCLIENTES
Nombre_Vendedor	RTRIM([Nombre_Vendedor]) AS nombre_vendedor	seller_name_raw	customers_sales_owner	text	raw	si	no	si	operacion, BI, IA	nombre visible del owner comercial
Nombre_Vendedor	derivado como vendedor_nombre	seller_first_name	customers_sales_owner	text	derived	no	no	no	operacion, IA	derivacion util para presentacion; no tratar como verdad fuerte mientras no se valide parsing
Nombre_Vendedor	derivado como vendedor_apellido	seller_last_name	customers_sales_owner	text	derived	no	no	no	operacion, IA	derivacion util para presentacion; mantener seller_name_raw como respaldo principal
Fecha_Ultima_Compra	CAST([Fecha_Ultima_Compra] AS date) AS fecha_ultima_compra	last_purchase_date	customers_commercial	date	normalized	si	no	si	operacion, BI, ML, IA, automatizacion	campo clave para riesgo comercial, recurrencia y reactivacion
Fecha_Alta	CAST([Fecha_Alta] AS date) AS fecha_alta	fecha_alta_sgc	customers_core	date	normalized	si	no	si	operacion, BI, ML, IA, auditoria	no equivale a created_at interno
Fecha_Baja	CAST([Fecha_Baja] AS date) AS fecha_baja	fecha_baja_sgc	customers_core	date	normalized	si	no	si	operacion, BI, ML, IA, auditoria	preserva hito comercial; no implica hard delete
Condicion_de_venta	RTRIM([Condicion_de_venta]) AS condicion_venta	payment_terms_raw	customers_commercial	text	raw	si	no	si	operacion, BI, automatizacion	termino comercial relevante para venta y facturacion
Condicion_Iva	RTRIM([Condicion_Iva]) AS condicion_iva	vat_condition_raw	customers_tax	text	raw	si	si	si	operacion, BI, auditoria	condicion fiscal textual del cliente
Cuit	RTRIM([Cuit]) AS cuit	tax_id_raw	customers_tax	text	raw	si	si	si	operacion, BI, auditoria, automatizacion	dato fiscal sensible; posible normalizacion posterior separada
Cuit	RTRIM([Cuit]) AS cuit	tax_id_normalized	customers_tax	text	normalized	no	si	si	operacion, BI, automatizacion	validacion simple ya mencionada en la evidencia, pero no cerrar todavia reglas fiscales finales
Ing_Brutos	RTRIM([Ing_Brutos]) AS ingresos_brutos	gross_income_tax_id_raw	customers_tax	text	raw	si	si	no	operacion, BI, auditoria	dato impositivo complementario
Descuento	RTRIM([Descuento]) AS descuento	discount_rule_raw	customers_commercial	text	raw	si	no	no	operacion, BI, ML	puede requerir futura separacion entre porcentaje, regla y vigencia
Cobrar_PIB	RTRIM([Cobrar_PIB]) AS cobrar_pib	collect_pib_raw	customers_tax	text	raw	si	si	no	operacion, BI, auditoria	significado operativo exacto aun pendiente
Porc_PIB	RTRIM([Porc_PIB]) AS porc_pib	pib_percentage_raw	customers_tax	numeric(8,3)	raw	si	si	no	operacion, BI, auditoria	conviene preservar valor fuente y, si hiciera falta, normalizar aparte
Limite_Credito	RTRIM([Limite_Credito]) AS limite_credito	credit_limit_raw	customers_commercial	numeric(18,3)	raw	si	si	no	operacion, BI, ML, automatizacion	no cerrar sin validar formato monetario real del origen
MoraPermitida	RTRIM([MoraPermitida]) AS mora_permitida	allowed_arrears_raw	customers_commercial	text	raw	si	si	no	operacion, BI, automatizacion	semantica exacta pendiente; no cerrar tipo final mas alla de recomendacion documental
Estado	RTRIM([Estado]) AS estado	estado_raw	customers_core	text	raw	si	no	si	operacion, BI, ML, IA, automatizacion, auditoria	debe conservar CLIENTE ACTIVO, CLIENTE SUSPENDIDO, CLIENTE DE BAJA
Estado	RTRIM([Estado]) AS estado	customer_status	customers_core	text	derived	no	no	si	operacion, BI, ML, IA, automatizacion	derivacion recomendada: active, suspended, inactive
Estado	RTRIM([Estado]) AS estado	can_sell	customers_core	boolean	derived	no	no	si	operacion, automatizacion, IA	derivado recomendado: true solo para CLIENTE ACTIVO
Estado	RTRIM([Estado]) AS estado_texto	estado_texto_raw	customers_core	text	raw	no	no	no	auditoria	alias duplicado del mismo valor; util solo si se quiere preservar compatibilidad con nomenclaturas fuente
Fax	RTRIM([Fax]) AS administracion	admin_contact_raw	customers_contact	text	raw	si	si	no	operacion, IA	hoy interpretado como contacto administrativo; semantica exacta dudosa
mail	RTRIM([mail]) AS email	email_raw	customers_contact	text	raw	si	si	si	operacion, BI, automatizacion, IA, auditoria	contacto sensible; puede haber multiples formatos invalidos
mail	RTRIM([mail]) AS email	email_normalized	customers_contact	citext	normalized	no	si	si	operacion, automatizacion, IA	util para contacto y matching liviano, nunca como clave unica cerrada por ahora
CodFrec	RTRIM([CodFrec]) AS cod_frec	visit_frequency_code_raw	customers_visit_schedule	text	raw	si	no	si	operacion, BI, automatizacion, IA	corrida real 2026-06-08 observo 4 codigos con mapeo 1:1 a Frecuencia: FVC001, FVC002, FVC003, FVC004
Frecuencia	RTRIM([Frecuencia]) AS frecuencia	visit_frequency_label_raw	customers_visit_schedule	text	raw	si	no	si	operacion, BI, automatizacion, IA	consistencia real pendiente de validar
lunes	RTRIM([lunes]) AS lunes	visit_monday_raw	customers_visit_schedule	text	raw	si	no	no	operacion, BI, automatizacion	corrida real 2026-06-08 observo solo S, N y NULL/VACIO; mantener raw hasta cerrar modelo fisico
martes	RTRIM([martes]) AS martes	visit_tuesday_raw	customers_visit_schedule	text	raw	si	no	no	operacion, BI, automatizacion	mismo criterio documental que lunes; no hubo texto libre sorpresa en la corrida observada
miercoles	RTRIM([miercoles]) AS miercoles	visit_wednesday_raw	customers_visit_schedule	text	raw	si	no	no	operacion, BI, automatizacion	mismo criterio documental que lunes; no hubo texto libre sorpresa en la corrida observada
jueves	RTRIM([jueves]) AS jueves	visit_thursday_raw	customers_visit_schedule	text	raw	si	no	no	operacion, BI, automatizacion	mismo criterio documental que lunes; no hubo texto libre sorpresa en la corrida observada
viernes	RTRIM([viernes]) AS viernes	visit_friday_raw	customers_visit_schedule	text	raw	si	no	no	operacion, BI, automatizacion	mismo criterio documental que lunes; no hubo texto libre sorpresa en la corrida observada
sabado	RTRIM([sabado]) AS sabado	visit_saturday_raw	customers_visit_schedule	text	raw	si	no	no	operacion, BI, automatizacion	mismo criterio documental que lunes; sabado mostro mayor volumen de S pero sin salir del set S/N/NULL

5. Auditoria y sync derivados de la fila completa

4.1 Regla critica sobre Zona y territorio comercial

• Zona en SOURCE-001 representa una dimension logistica y no comercial
• Zona sirve para rutas, reparto, logistica y agrupacion de localidades
• Zona no debe usarse para inferir vendedor responsable
• el vendedor responsable sale de seller_code_raw y seller_name_raw
• la pregunta por territorio comercial del vendedor debe responderse desde su cartera real de clientes asignados
• ese territorio comercial debe poder cruzarse con localidad, provincia, zona logistica, ventas, SKU, marcas, proveedores y categorias

5. Auditoria y sync derivados de la fila completa

Estos campos no vienen como una sola columna puntual del SELECT, pero son obligatorios a nivel de diseno documental para que SOURCE-001 cumpla el DATA-DESIGN-STANDARD.

Fuente origen	Campo destino recomendado	Bloque logico	Tipo PostgreSQL sugerido	Naturaleza	Hash	Sensible	Indice	Uso futuro	Observaciones
fila completa VCLIENTES	source_row_hash	source_001_customer_audit	text	derived	no	no	si	operacion, automatizacion, auditoria	hash de cambios de fila; debe incluir todos los campos relevantes ya canonicalizados
corrida de extraccion	sync_batch_id	source_001_customer_audit	text	derived	no	no	si	operacion, auditoria	permite auditar cada corrida de sync
metadata de proceso	source_system	source_001_customer_audit	text	derived	no	no	si	operacion, auditoria	valor esperado: mssql:mssql-sgc-ecommerce o alias oficial vigente
metadata de proceso	source_object	source_001_customer_audit	text	derived	no	no	si	operacion, auditoria	valor esperado: ecommerce.dbo.VCLIENTES
metadata de proceso	source_query_version	source_001_customer_audit	text	derived	no	no	no	auditoria	versiona la autoridad o la logica de extraccion usada
metadata de proceso	extracted_at	source_001_customer_audit	timestamptz	derived	no	no	si	operacion, auditoria	marca cuando la fila fue leida del origen
metadata de proceso	last_seen_at	source_001_customer_audit	timestamptz	derived	no	no	si	operacion, auditoria	clave para reconciliacion y desaparicion de filas
metadata interna OpenClaw	created_at	source_001_customer_audit	timestamptz	derived	no	no	si	operacion, auditoria	timestamp interno de alta en OpenClaw; no copiar desde Fecha_Alta
metadata interna OpenClaw	updated_at	source_001_customer_audit	timestamptz	derived	no	no	si	operacion, auditoria	timestamp interno de actualizacion en OpenClaw
metadata de calidad	validation_status	source_001_customer_audit	text	derived	no	no	si	operacion, BI, auditoria	fila o lote validado, observado, pendiente o fallido
metadata de calidad	validation_notes	source_001_customer_audit	text	derived	no	si	no	auditoria	notas de excepcion concretas; no reemplazan modelado

6. Reglas de hash e indices recomendadas

Campos recomendados para participar del source_row_hash:

• codigo_cliente
• cliente_nombre
• razon_social
• direccion_pedidos
• localidad
• provincia
• entre_calles
• zona
• horarios_entrega
• whatsapp
• lista_precio
• canal
• categoria
• codigo_vendedor
• nombre_vendedor
• fecha_ultima_compra
• fecha_alta
• fecha_baja
• condicion_venta
• condicion_iva
• cuit
• ingresos_brutos
• descuento
• cobrar_pib
• porc_pib
• limite_credito
• mora_permitida
• estado
• administracion
• email
• cod_frec
• frecuencia
• lunes
• martes
• miercoles
• jueves
• viernes
• sabado

Indices documentales minimos recomendados:

• tenant_id + codigo_cliente
• tenant_id + customer_status
• tenant_id + seller_code_raw
• tenant_id + last_purchase_date
• tenant_id + visit_frequency_code_raw cuando la evidencia de frecuencia se confirme
• source_row_hash
• last_seen_at
• sync_batch_id

7. Decisiones que este documento no cierra todavia

Este mapeo no debe tomarse como cierre de diseno fisico final aunque ya exista evidencia util sobre vendedor, frecuencia y dias, porque todavia falta cerrar:

• normalizacion definitiva de WhatsApp
• diseno fisico final derivado de la estrategia territorial canonica para Localidad, Provincia y Zona
• estrategia fisica final de tablas, historicos y particion logica

Lectura obligatoria:

• el documento mapea bloques logicos, no tablas finales
• no define DDL
• no define migraciones
• no define politica final de historizacion fina por bloque

8. Pendientes preservados

• decidir si customers_sales_owner queda solo como bloque embebido o si a futuro conviene entidad referencial adicional contra un maestro vendedor
• decidir si customers_visit_schedule conviene quedar como bloque raw fortalecido o avanzar luego a una estructura semantica mas fuerte
• validar reglas finales de normalizacion WhatsApp para decidir si conviene E.164, un canon local controlado o doble representacion
• cargar y aprobar humanamente el catalogo real de alias territoriales, sinonimos y relaciones canonicas ya inventariado en TERRITORY-ALIAS-CATALOG-001
• decidir si la capa territorial futura requerira geocodificacion posterior
• definir estrategia fisica final para estos bloques sin romper tenant_id + codigo_cliente

9. Confirmaciones de alcance

• no se tocaron runtimes
• no se ejecutaron queries en esta tarea
• no se crearon tablas
• no se crearon migraciones
• no se cerro SQL fisico