SOURCE-001 Clientes VCLIENTES Authority

Fecha: 2026-06-05

Estado: AUTORIDAD PRESERVADA / EVIDENCIA CERRADA

Owner: Gabi / Carlos Canu

Version: v2

Proposito

Preservar como autoridad documental completa la query SELECT_CUSTOMERS_SQL tomada textual del script de sincronizacion de clientes aportado por Gabi:

C:\APV\gestor-de-negocios\backend\app\scheduler\scripts\sync_sgc_customers_canonical.py

Regla de autoridad

• esta copia debe tratarse como autoridad funcional de SOURCE-001
• la autoridad proviene del script de sincronizacion aportado por Gabi
• no corresponde reinterpretar alias, filtros, derivaciones ni orden del SELECT
• Telefono debe considerarse WhatsApp del cliente porque la query lo expresa textual como RTRIM([Telefono]) AS whatsapp
• la extraccion base preservada solo filtra Codigo nulo y no debe reinterpretarse agregando WHERE Estado = 'CLIENTE ACTIVO'
• todo campo derivado desde esta query pertenece al mismo cliente SGC identificado por Codigo
• si en una capa futura se separan grupos logicos como customers_core, customers_contact, customers_address, customers_tax, customers_commercial, customers_sales_owner o customers_visit_schedule, esa separacion debe leerse como descomposicion logica del mismo cliente y no como multiplicacion de clientes
• la sync futura debe preservar CLIENTE ACTIVO, CLIENTE SUSPENDIDO y CLIENTE DE BAJA
• el valor textual de Estado en SGC debe guardarse como estado_raw
• el estado operativo derivado recomendado es: CLIENTE ACTIVO -> active / can_sell = true
• el estado operativo derivado recomendado es: CLIENTE SUSPENDIDO -> suspended / can_sell = false
• el estado operativo derivado recomendado es: CLIENTE DE BAJA -> inactive / can_sell = false
• si Estado o Fecha_Baja indican suspension o baja comercial, esa condicion no implica eliminacion del cliente del dominio historico
• los clientes suspendidos o de baja deben preservarse para analisis historico, perdida de territorio, recuperacion comercial, reactivacion, masa comercial total, recomposicion de masa comercial y desempeno por zona, vendedor y periodo
• la desaparicion completa del registro en una extraccion futura debe tratarse distinto de Estado = CLIENTE DE BAJA
• el futuro diseno Postgres no debe habilitar hard delete por baja comercial
• la forma canonica recomendada en destino para ese identificador es: codigo_cliente = NULLIF(LTRIM(RTRIM([Codigo])), '')
• la clave logica recomendada para relacionar cualquier grupo derivado de SOURCE-001 es: tenant_id + codigo_cliente

Regla de relacion entre grupos derivados

La autoridad preservada no cierra todavia el diseno fisico de tablas.

Si mas adelante la salida de VCLIENTES se clasifica en grupos logicos separados, todos deben seguir subordinados al mismo cliente SGC.

Campo origen comun observado:

• Codigo

Forma observada en la query autoridad:

• RTRIM([Codigo]) AS codigo_cliente

Forma canonica recomendada en destino:

• codigo_cliente = NULLIF(LTRIM(RTRIM([Codigo])), '')

Interpretacion obligatoria:

• todos los grupos logicos derivados de VCLIENTES pertenecen al mismo cliente SGC
• todos los grupos deben relacionarse por tenant_id + codigo_cliente
• ningun grupo debe interpretarse como cliente independiente
• la separacion entre grupos futuros sera documental o logica hasta definir diseno fisico, no una decision de multiplicar clientes

Query autoridad preservada

SELECT
    RTRIM([Codigo]) AS codigo_cliente,
    COALESCE(
        NULLIF(RTRIM([Nombre]), ''),
        NULLIF(RTRIM([Nombre_en_Factura]), ''),
        RTRIM([Codigo])
    ) AS cliente_nombre,
    RTRIM([Nombre_en_Factura]) AS razon_social,
    RTRIM([Direccion_de_pedidos]) AS direccion_pedidos,
    RTRIM([Localidad]) AS localidad,
    RTRIM([Provincia]) AS provincia,
    RTRIM([EntreCalles]) AS entre_calles,
    RTRIM([Zona]) AS zona,
    RTRIM([Nota_en_comprobante]) AS horarios_entrega,
    RTRIM([Telefono]) AS whatsapp,
    RTRIM([Lista_Precio]) AS lista_precio,
    RTRIM([Ramo]) AS canal,
    RTRIM([Categoria]) AS categoria,
    RTRIM([Codigo_vendedor]) AS codigo_vendedor,
    RTRIM([Nombre_Vendedor]) AS nombre_vendedor,

    REPLACE(
        CASE
            WHEN CHARINDEX(' ', LTRIM(RTRIM([Nombre_Vendedor]))) > 0
            THEN LEFT(LTRIM(RTRIM([Nombre_Vendedor])),
                      CHARINDEX(' ', LTRIM(RTRIM([Nombre_Vendedor]))) - 1)
            ELSE LTRIM(RTRIM([Nombre_Vendedor]))
        END,
        '-', ''
    ) AS vendedor_nombre,

    REPLACE(
        CASE
            WHEN CHARINDEX(' ', LTRIM(RTRIM([Nombre_Vendedor]))) > 0
            THEN REPLACE(REPLACE(REPLACE(REPLACE(REPLACE(REPLACE(REPLACE(REPLACE(REPLACE(REPLACE(
                SUBSTRING(
                    LTRIM(RTRIM([Nombre_Vendedor])),
                    CHARINDEX(' ', LTRIM(RTRIM([Nombre_Vendedor]))) + 1,
                    CASE
                        WHEN CHARINDEX(' ', LTRIM(RTRIM([Nombre_Vendedor])),
                                       CHARINDEX(' ', LTRIM(RTRIM([Nombre_Vendedor]))) + 1) > 0
                        THEN CHARINDEX(' ', LTRIM(RTRIM([Nombre_Vendedor])),
                                       CHARINDEX(' ', LTRIM(RTRIM([Nombre_Vendedor]))) + 1)
                             - CHARINDEX(' ', LTRIM(RTRIM([Nombre_Vendedor]))) - 1
                        ELSE LEN(LTRIM(RTRIM([Nombre_Vendedor])))
                    END
                ),
                '0',''),'1',''),'2',''),'3',''),'4',''),'5',''),'6',''),'7',''),'8',''),'9','')
            ELSE NULL
        END,
        '-', ''
    ) AS vendedor_apellido,

    CAST([Fecha_Ultima_Compra] AS date) AS fecha_ultima_compra,
    CAST([Fecha_Alta] AS date) AS fecha_alta,
    CAST([Fecha_Baja] AS date) AS fecha_baja,

    RTRIM([Condicion_de_venta]) AS condicion_venta,
    RTRIM([Condicion_Iva]) AS condicion_iva,
    RTRIM([Cuit]) AS cuit,
    RTRIM([Ing_Brutos]) AS ingresos_brutos,
    RTRIM([Descuento]) AS descuento,
    RTRIM([Cobrar_PIB]) AS cobrar_pib,
    RTRIM([Porc_PIB]) AS porc_pib,
    RTRIM([Limite_Credito]) AS limite_credito,
    RTRIM([MoraPermitida]) AS mora_permitida,
    RTRIM([Estado]) AS estado,
    RTRIM([Estado]) AS estado_texto,
    RTRIM([Fax]) AS administracion,
    RTRIM([mail]) AS email,
    RTRIM([CodFrec]) AS cod_frec,
    RTRIM([Frecuencia]) AS frecuencia,
    RTRIM([lunes]) AS lunes,
    RTRIM([martes]) AS martes,
    RTRIM([miercoles]) AS miercoles,
    RTRIM([jueves]) AS jueves,
    RTRIM([viernes]) AS viernes,
    RTRIM([sabado]) AS sabado
FROM [ecommerce].[dbo].[VCLIENTES]
WHERE [Codigo] IS NOT NULL;

Regla de consumo futuro

• esta autoridad preserva la base sincronizable de clientes y no una vista filtrada solo a clientes vendibles
• cualquier filtro para venta o facturacion debe vivir en vistas o capas de consumo derivadas
• la tabla o base sincronizada debe conservar clientes activos, suspendidos y de baja

Evidencia de origen

• script fuente: C:\APV\gestor-de-negocios\backend\app\scheduler\scripts\sync_sgc_customers_canonical.py
• constante observada: SELECT_CUSTOMERS_SQL
• ejecucion observada en el mismo script: cursor.execute(SELECT_CUSTOMERS_SQL)

Cierre

• SOURCE-001 queda cerrada como autoridad documental preservada
• la fuente autoridad completa es ecommerce.dbo.VCLIENTES
• Telefono queda preservado como WhatsApp del cliente
• no se implemento runtime, SQL nuevo, API, Docker, VPS ni OpenClaw