Customer Blueprint - Business Observer APV¶

Fecha: 2026-06-10

Estado: BLUEPRINT FUNCIONAL V1

Scope: tenant

tenant_id: alpuntodeventa

Owner: Gabi / Carlos Canu

Fuente de verdad: docs/tenants/alpuntodeventa/business-observer/blueprints/CUSTOMER-BLUEPRINT.md

Autoridades relacionadas:

1. Objetivo¶

Definir que es un Cliente para OpenClaw / APV dentro del Business Observer, antes de cualquier tabla, migracion, query, DDL o implementacion.

Este blueprint fija lenguaje de dominio, fronteras, reglas obligatorias, preguntas de negocio y relacion con otras capas documentales.

No reemplaza las fuentes, mappings, contratos, inventarios ni documentos de diseno. Los referencia como autoridad tecnica o evidencia.

2. Que es un Cliente para OpenClaw / APV¶

Un Cliente es la entidad comercial central del Business Observer APV.

No es solamente un registro del ERP ni una fila tecnica de SGC.

Para APV, un cliente es la unidad principal de analisis para:

venta
recuperacion
territorio
logistica
ownership comercial
oportunidades de crecimiento
riesgo comercial
contacto operativo
lectura historica de perdida y recomposicion de masa comercial

El cliente concentra identidad comercial, estado, contacto, direccion, territorio, vendedor asignado, frecuencia de visita, datos comerciales, atributos fiscales y senales historicas de relacion con la empresa.

3. Fuente primaria actual¶

La fuente primaria actual del dominio cliente es SOURCE-001, basada en ecommerce.dbo.VCLIENTES.

Reglas de identidad de fuente:

el origen funcional actual es SOURCE-001 / ecommerce.dbo.VCLIENTES
el campo origen comun es Codigo
la clave logica fuerte recomendada es tenant_id + codigo_cliente
codigo_cliente debe derivarse desde Codigo canonicalizado
todos los grupos futuros del cliente deben seguir subordinados al mismo cliente SGC

Regla de preservacion:

los valores raw deben preservarse cuando representen verdad fuente, evidencia, auditoria o sensibilidad de negocio
los valores normalized deben existir cuando el consumo operativo, analitico o automatizado necesite consistencia
una normalizacion no debe destruir ni reemplazar el valor fuente cuando el campo sea sensible, ambiguo o todavia este en semaforo AMARILLO

4. Identidad del cliente¶

La identidad funcional minima del cliente se compone de:

tenant_id
codigo_cliente
razon_social
nombre_cliente o nombre visible equivalente

Reglas:

codigo_cliente es el identificador comercial fuerte dentro del tenant
razon_social preserva la lectura fiscal o de facturacion visible
nombre_cliente representa el nombre visible principal para negocio
customer_key puede existir en el futuro como clave tecnica interna de OpenClaw, pero no debe reemplazar la autoridad de tenant_id + codigo_cliente sin decision documental posterior
WhatsApp no es identificador del cliente
CUIT no debe ser clave unica primaria del dominio cliente

Motivo funcional:

WhatsApp tiene cobertura incompleta, formatos heterogeneos y repetidos reales entre clientes distintos
CUIT es dato fiscal sensible y puede requerir validacion, normalizacion o tratamiento administrativo propio
el cliente comercial de APV debe poder existir aunque falten datos de contacto o fiscales perfectos

5. Estados del cliente¶

Estados fuente observados y aceptados:

Estado SGC	Estado operativo recomendado	`can_sell`	Lectura funcional
`CLIENTE ACTIVO`	`active`	`true`	cliente vendible
`CLIENTE SUSPENDIDO`	`suspended`	`false`	cliente preservado, no vendible
`CLIENTE DE BAJA`	`inactive`	`false`	cliente preservado, no vendible

Reglas:

can_sell es derivado, no valor fuente
estado_raw debe preservar el texto original de SGC
customer_status no reemplaza estado_raw
un cliente de baja no se elimina
un cliente suspendido no se elimina
la baja comercial no equivale a desaparicion fisica del registro
la desaparicion futura del registro en una extraccion debe tratarse como evento distinto de Estado = CLIENTE DE BAJA

Usos obligatorios de clientes no vendibles:

analisis historico
medicion de perdida de territorio
campanas de recuperacion
lectura de cartera perdida
recomposicion de masa comercial
desempeno por vendedor, zona logistica, localidad, provincia y periodo

6. Contacto¶

Los datos de contacto forman parte del cliente, pero no definen su identidad.

Campos conceptuales relevantes:

whatsapp_raw
whatsapp_normalized
whatsapp_quality_status
email_raw
email_normalized
administracion o contacto administrativo equivalente

Reglas:

Telefono de SOURCE-001 debe leerse como base operativa de WhatsApp
WhatsApp debe preservarse como raw + normalized + quality_status
WhatsApp no debe usarse como clave unica
email tampoco debe usarse como clave unica primaria del dominio cliente
administracion, derivado hoy desde Fax, debe conservar cautela semantica hasta validacion posterior
los datos de contacto son sensibles y deben tratarse con criterio de privacidad, auditoria y minimo acceso necesario

Lectura funcional:

contacto sirve para accion comercial, recuperacion, automatizacion y seguimiento
contacto no corrige ni reemplaza identidad comercial
si el contacto falta o tiene baja calidad, el cliente sigue existiendo

7. Direccion y territorio¶

Los datos territoriales del cliente ordenan lectura comercial, logistica y oportunidad, pero tienen naturalezas distintas.

Campos conceptuales relevantes:

direccion_pedidos
localidad
provincia
zona
entre_calles
horarios_entrega

Reglas:

provincia y localidad son senales territoriales fuertes para analisis comercial
Zona es dimension logistica, no territorio comercial del vendedor
Zona sirve para rutas, reparto, agrupacion operativa y lectura logistica
Zona no debe usarse para inferir vendedor responsable
localidad y provincia deben preservarse como raw + normalized
zona debe preservarse como raw + type + normalized
la normalizacion territorial futura debe seguir la Territory Normalization Strategy

Lectura funcional:

el territorio comercial del vendedor se construye desde su cartera real de clientes asignados y se cruza luego con localidad, provincia, zona logistica, ventas y productos
una zona logistica puede mezclar localidades o provincias y por eso no debe confundirse con una jerarquia comercial cerrada

8. Vendedor asignado¶

El vendedor asignado del cliente viene de SOURCE-001.

Campos conceptuales relevantes:

seller_assigned_code
seller_assigned_name
seller_assigned_raw

Reglas:

Codigo_vendedor y Nombre_Vendedor de SOURCE-001 representan cartera formal asignada
ese vendedor debe tratarse como seller_assigned
seller_assigned no debe confundirse con seller_transactional
el vendedor real de una venta se atribuye desde la transaccion de ventas
las ventas reales deben atribuirse al vendedor transaccional
no se debe sobrescribir seller_assigned con datos de ventas
no se debe sobrescribir seller_transactional con la cartera formal

Lectura funcional:

seller_assigned responde quien tiene formalmente al cliente
seller_transactional responde quien lo trabajo efectivamente en una venta
la diferencia entre ambos es senal analitica y debe preservarse

9. Frecuencia y visitas¶

La frecuencia y los dias de visita representan senales operativas para planificacion comercial y logistica.

Campos conceptuales relevantes:

CodFrec
Frecuencia
lunes
martes
miercoles
jueves
viernes
sabado

Reglas:

CodFrec debe preservarse como codigo fuente de frecuencia
Frecuencia debe preservarse como etiqueta fuente
los dias de lunes a sabado deben conservar su valor raw
la normalizacion futura puede derivar disponibilidad o calendario, pero no debe eliminar la lectura original

Usos:

planificacion de rutas
cadencia comercial
priorizacion de visita
lectura de cobertura territorial
tension entre frecuencia asignada, compras reales y recuperacion comercial

10. Comercial y fiscal¶

El cliente incluye atributos comerciales, crediticios y fiscales que afectan venta, facturacion, riesgo y segmentacion.

Datos comerciales relevantes:

lista de precio
canal
categoria
condicion de venta
descuento
limite de credito
mora permitida
fecha de ultima compra
fecha de alta SGC
fecha de baja SGC

Datos fiscales relevantes:

condicion IVA
CUIT
ingresos brutos
PIB o campos relacionados cuando apliquen

Reglas:

lista de precio, canal y categoria son atributos comerciales del cliente
condicion de venta, limite de credito y mora afectan riesgo operativo
condicion IVA, CUIT e ingresos brutos son datos fiscales sensibles
CUIT debe validarse y normalizarse con cautela, pero no debe ser clave primaria del dominio
fecha_alta_sgc y fecha_baja_sgc deben quedar separadas de created_at y updated_at
created_at y updated_at son metadatos internos de OpenClaw
las fechas SGC preservan historia fuente y eventos comerciales

11. Relacion con otros dominios¶

El dominio cliente se relaciona con:

Ventas / SOURCE-003: aporta compras reales, fecha efectiva de transaccion, vendedor transaccional, comprobantes, SKU, importes y recuperacion comercial
Productos / SOURCE-002: aporta SKU, marca, proveedor, categoria, precio, costo, stock y mix comprado o potencial
Territory: normaliza provincia, localidad y zona logistica sin convertir Zona en vendedor responsable
Ownership: distingue cartera formal, trabajo real, recuperacion, abandono y crecimiento
Seller Reconciliation: compara seller_assigned contra seller_transactional
Analytics: calcula riesgo, actividad, recencia, recuperacion, masa comercial, territorio y oportunidades
ML / IA: puede usar clientes como unidad de prediccion, recomendacion o alerta, siempre con trazabilidad de origen y calidad

Regla transversal:

ninguna capa derivada debe borrar la diferencia entre identidad del cliente, contacto, territorio, cartera formal, transaccion real y atributo fiscal

12. Preguntas de negocio que debe responder¶

Este blueprint debe permitir responder, directa o indirectamente:

quien es el cliente
si puede venderse
quien lo tiene asignado
quien lo trabaja realmente
cuando compro por ultima vez
que territorio representa
que zona logistica lo contiene
si esta perdido, suspendido o recuperable
que señales de recuperacion o abandono muestra
cuantos clientes deben captarse o recuperarse para recomponer masa comercial
donde se perdio territorio comercial
que cartera formal difiere de la actividad transaccional real

13. Reglas obligatorias¶

Reglas cerradas para el dominio cliente:

no hacer hard delete por baja comercial
no filtrar solo clientes activos en la sync base
no usar WhatsApp como clave
no usar CUIT como clave unica primaria del dominio cliente
no usar Zona para inferir vendedor responsable
no sobrescribir seller_assigned con ventas
no sobrescribir seller_transactional con cartera formal
preservar estado_raw
derivar can_sell sin reemplazar el valor fuente
preservar clientes suspendidos y de baja para historico y recuperacion
preservar fechas SGC separadas de created_at y updated_at
preservar raw + normalized donde exista ambiguedad, sensibilidad o necesidad analitica
tratar contacto, datos fiscales y direccion como datos sensibles segun permisos de consumo futuros

14. Diseno futuro relacionado¶

Los siguientes nombres son referencias conceptuales futuras. No son tablas creadas, no son DDL, no son migraciones y no autorizan implementacion.

Capas futuras relacionadas con SOURCE-001:

source_001_customers_core
source_001_customers_contact
source_001_customers_address
source_001_customers_tax
source_001_customers_commercial
source_001_customers_sales_owner
source_001_customers_visit_schedule
analytics_customer_ownership

Regla:

todas estas capas deben permanecer ancladas a tenant_id + codigo_cliente
la separacion ordena dominios funcionales
la separacion no multiplica clientes
la separacion no cierra todavia el diseno fisico final

15. Que NO es este blueprint¶

Este documento no es:

una query
un mapping campo por campo
un contrato de datos
una fuente de autoridad
un inventario de resultados
un SQL
un DDL
una migracion
una implementacion
una autorizacion para tocar runtime
un reemplazo de SOURCE-001
un reemplazo de BUSINESS-OBSERVER-DATA-CONTRACT-001
un reemplazo de SOURCE-001-CLIENTES-MAPPING

16. Pendientes preservados¶

Quedan pendientes:

diseno fisico final de SOURCE-001
normalizacion definitiva de WhatsApp
catalogo territorial real cargado y aprobado para consumo
integracion fisica con ventas y productos
ownership efectivo con umbrales
permisos de consumo para contacto, datos fiscales y direccion
definicion final de historizacion por cambio para atributos comerciales, fiscales, territoriales y de ownership
validacion futura de diferencias entre cartera formal y ventas reales

17. Confirmaciones de alcance¶

Este blueprint:

no toca runtime
no toca VPS
no toca Docker
no toca PostgreSQL
no ejecuta queries
no crea codigo
no crea tablas
no crea migraciones
no mueve archivos
solo documenta dominio funcional