Saltar a contenido

Business Observer Data Contract 001 - APV

Fecha: 2026-06-10

Estado: CONTRATO FUNCIONAL DE DATOS

Scope: tenant

tenant_id: alpuntodeventa

Owner: Gabi / Carlos Canu

Fuente de verdad: docs/tenants/alpuntodeventa/business-observer/BUSINESS-OBSERVER-DATA-CONTRACT-001.md

1. Proposito

Este contrato existe para convertir la auditoria de datos ya realizada en una guia funcional clara para futuras bases Postgres, datasets del tenant y scripts de sincronizacion del Business Observer de APV.

Su funcion no es implementar nada todavia.

Su funcion es evitar que una futura base nazca por intuicion, por comodidad tecnica o por copia de estructuras genericas sin relacion directa con negocio.

El contrato conecta:

  • necesidades reales de UC001 a UC009
  • evidencia y gobierno de datos
  • futura preparacion de dataset tenant
  • futura traduccion a entidades Postgres
  • futura sincronizacion y validacion

Regla madre:

ningun dato debe entrar por suposicion.

Todo dato debe nacer de un caso de uso real, con origen esperado, responsable, frecuencia y criterio minimo de calidad.

Regla transversal adicional:

historicos por valor de decision

Todo dato util para indicadores, toma de decisiones, patrones, tendencias, alertas o aprendizaje futuro debe contemplar historico desde el diseno.

Esto aplica cuando el dato permita:

  • medir evolucion
  • detectar patrones
  • explicar tendencias
  • generar alertas
  • mejorar decisiones comerciales
  • alimentar aprendizaje futuro

No implica guardar todo sin criterio ni sin limite.

Implica disenar historicos livianos, trazables y utiles.

Regla transversal adicional para SOURCE-002:

  • tenant_id + SKU es la clave canonica del dominio producto
  • todo dato que salga de SOURCE-002 debe interpretarse como atributo, medicion, relacion vigente o relacion historica del SKU
  • articulo, marca, estado, stock, stock en bultos, costos, descuentos de compra, precios, listas, IVA, margenes, descuento permitido, precio oferta, proveedor, categoria, subcategoria, unidad de medida, palletizado, fechas operativas e historicos utiles quedan subordinados a esa clave
  • el analisis por proveedor o por marca debe derivarse desde los SKU asociados y no desde valores textuales sueltos
  • politica comercial, promociones, estrategia comercial, actividad comercial y volumetria / logistica tambien deben quedar explicitamente subordinadas a tenant_id + SKU

Regla transversal adicional para SOURCE-001:

  • tenant_id + codigo_cliente es la clave logica recomendada del dominio cliente derivado de VCLIENTES
  • codigo_cliente debe canonicalizarse como NULLIF(LTRIM(RTRIM([Codigo])), '')
  • la validacion real del 2026-06-08 sobre VCLIENTES observo 11401 filas, 11401 codigos normalizados distintos, 0 codigos nulos o vacios y 0 codigos duplicados distintos
  • la validacion real del 2026-06-08 sobre Telefono usado como WhatsApp observo 11401 filas, 7107 telefonos informados, 4294 vacios, 350 telefonos repetidos distintos entre clientes y mayoria de formatos controlables de 10 a 13 digitos tras quitar separadores
  • una corrida real posterior del mismo 2026-06-08 para vendedor y frecuencia observo 11404 filas, lo que confirma que VCLIENTES es una fuente viva y refuerza la necesidad futura de sync_batch_id, extracted_at y last_seen_at
  • en esa corrida real posterior del 2026-06-08, Codigo_vendedor y Nombre_Vendedor aparecieron completos en 11404/11404 filas y sostuvieron relacion 1:1, con 76 codigos distintos, 76 nombres distintos y 0 inconsistencias en ambos sentidos dentro de VCLIENTES
  • en esa misma corrida real posterior del 2026-06-08, CodFrec y Frecuencia aparecieron completos en 11404/11404 filas, con 4 codigos y 4 etiquetas en relacion 1:1, sin inconsistencias
  • en esa misma corrida real posterior del 2026-06-08, los campos diarios lunes a sabado solo observaron S, N y NULL/VACIO, sin texto libre sorpresa
  • en otra corrida real del 2026-06-08 orientada a territorialidad, Localidad y Provincia aparecieron completas en 11404/11404 filas, Zona aparecio informada en 11403/11404, se observaron 24 provincias, 516 localidades y 365 zonas distintas
  • en esa misma corrida territorial del 2026-06-08, Zona mostro una taxonomia util pero imperfecta: 1522 casos NO DEFINIDA, 1 NULL/VACIO, 9437 casos con prefijo ZONA, 444 valores no prefijados y 76 zonas multi-provincia que involucran 6365 clientes
  • por evidencia real observada, tenant_id + codigo_cliente puede tratarse como clave logica fuerte de SOURCE-001 mientras se preserve esa canonicalizacion
  • por esa misma evidencia, whatsapp no debe tratarse como identificador unico del cliente
  • por esa misma evidencia, seller_code_raw, seller_name_raw, visit_frequency_code_raw y visit_frequency_label_raw pueden tratarse como senales operativas aprovechables del cliente dentro de SOURCE-001
  • por esa misma evidencia, city_raw, state_province_raw y logistic_zone_raw pueden tratarse como senales territoriales aprovechables del cliente, con semaforo AMARILLO y sin asumir todavia una jerarquia geografica perfectamente normalizada
  • la estrategia canonica futura para territorio de SOURCE-001 queda documentada en: docs/tenants/alpuntodeventa/business-observer/territory/TERRITORY-NORMALIZATION-STRATEGY.md
  • el inventario documental inicial del catalogo real de aliases territoriales para SOURCE-001 queda documentado en: docs/tenants/alpuntodeventa/business-observer/territory/TERRITORY-ALIAS-CATALOG-001.md
  • esa estrategia fija provincia_raw + provincia_normalized, localidad_raw + localidad_normalized y zona_raw + zona_type + zona_normalized como arquitectura territorial canonica previa al diseno fisico final
  • en SOURCE-001, Zona queda definida por negocio como agrupacion logistica para rutas y reparto, no como territorio comercial del vendedor
  • el vendedor responsable de cada cliente debe salir de Codigo_vendedor / Nombre_Vendedor
  • ese vendedor de SOURCE-001 debe tratarse como seller_assigned
  • el territorio comercial del vendedor debe derivarse de su cartera real de clientes asignados y del cruce posterior con geografia, ventas reales y productos
  • el vendedor observado en SOURCE-003 debe tratarse como seller_transactional
  • la atribucion real de facturacion debe usar seller_transactional y no debe sobrescribirse con seller_assigned
  • la diferencia entre seller_assigned y seller_transactional debe preservarse como senal analitica
  • el canal transaccional observado en SOURCE-003 debe preservarse como channel_raw y no debe sobrescribir el canal comercial del cliente en SOURCE-001
  • Ramo de SOURCE-003 debe preservarse como senal complementaria porque en la validacion real explica mejor a OTROS y a SIN ASIGNAR
  • la taxonomia funcional parcial de canal para SOURCE-003 queda documentada en sources/SOURCE-003-CHANNEL-TAXONOMY.md
  • no corresponde inferir ecommerce o shared_channel solo por OTROS
  • ese catalogo inicial documenta evidencia raw, reglas de alias, clasificacion de Zona, niveles automatic/suggested/manual_review y metadata futura de aprobacion approved_by, approved_at y source_evidence
  • la futura sync de SOURCE-001 debe preservar whatsapp_raw o valor fuente equivalente cuando el formato sea ambiguo
  • no corresponde cerrar normalizacion definitiva de whatsapp mientras sigan apareciendo formatos heterogeneos o ambiguos en la fuente
  • todos los grupos de datos derivados de SOURCE-001 deben interpretarse como atributos, contactos, direcciones, datos fiscales, datos comerciales, ownership comercial o calendario de visita del mismo cliente SGC
  • si se usan grupos logicos como customers_core, customers_contact, customers_address, customers_tax, customers_commercial, customers_sales_owner y customers_visit_schedule, esa separacion es solo logica y no una multiplicacion de clientes
  • el primer mapeo campo por campo vigente de esa separacion queda documentado en: docs/tenants/alpuntodeventa/business-observer/mappings/SOURCE-001-CLIENTES-MAPPING.md
  • ningun grupo derivado de SOURCE-001 debe leerse como cliente independiente mientras el origen comun siga siendo Codigo
  • la extraccion base de SOURCE-001 no debe agregar WHERE Estado = 'CLIENTE ACTIVO'
  • la sync futura de SOURCE-001 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
  • los filtros de venta o facturacion deben vivir en vistas, datasets derivados o capas de consumo y no en la base sincronizada
  • un cliente con fecha_baja, estado suspendido, estado de baja o inactividad no debe tratarse como eliminado del dominio comercial historico
  • la suspension o baja debe preservarse como estado o evento historico del cliente
  • esos clientes deben seguir disponibles para analisis historico, medicion de perdida de territorio, recuperacion comercial, campanas de reactivacion, calculo de 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

2. Principio rector

Flujo oficial:

Contrato funcional de datos

↓

Dataset del tenant alpuntodeventa

↓

Diseno Postgres futuro

↓

Scripts de sincronizacion

↓

Validaciones

↓

Observer operativo futuro

Interpretacion:

  • primero se define que dato hace falta y para que sirve
  • despues se define como se organiza dentro del dataset APV
  • recien luego se transforma en tablas futuras
  • solo despues tiene sentido pensar sincronizacion y validacion
  • el observer operativo debe ser consecuencia del contrato, no su reemplazo

3. Reglas de separacion tenant

  • todo dato de APV debe quedar aislado por tenant
  • no se deben mezclar datos de APV con La Directa
  • todo dataset futuro debe respetar tenant_id, contexto y owner
  • Core define patrones reutilizables de gobierno, trazabilidad y aislamiento
  • APV define sus datos, reglas comerciales, prioridades y criterios propios
  • un dato reusable de Core no habilita mezcla de contenido concreto entre tenants
  • una futura tabla, vista, export o script que no preserve contexto tenant no queda aceptado

4. Clasificacion de datos del contrato

4.1 Regla de territorio comercial del vendedor

Pregunta incorrecta:

  • cual es el territorio del vendedor segun Zona

Pregunta correcta:

  • cual es el territorio comercial del vendedor segun clientes asignados, geografia, ventas reales y mix de productos

Reglas cerradas:

  • Zona en SOURCE-001 es dimension logistica
  • Zona no define vendedor
  • el vendedor responsable sale de Codigo_vendedor / Nombre_Vendedor
  • el territorio comercial del vendedor se construye desde: clientes asignados al vendedor, localidad y provincia de esos clientes, zona logistica, ventas reales, SKU, marcas, proveedores y categorias
  • el cruce analitico final debe sostenerse con SOURCE-001, SOURCE-002 y SOURCE-003

Documento conceptual relacionado:

  • la futura capa analitica especifica para responder territorio comercial del vendedor queda documentada en: docs/tenants/alpuntodeventa/business-observer/analytics/SELLER-COMMERCIAL-TERRITORY-VIEW.md
  • la reconciliacion conceptual entre vendedor asignado y vendedor real de la venta queda documentada en: docs/tenants/alpuntodeventa/business-observer/analytics/SELLER-RECONCILIATION-RULES.md
  • la futura capa conceptual para identificar quien trabaja realmente cada cliente queda documentada en: docs/tenants/alpuntodeventa/business-observer/analytics/CUSTOMER-OWNERSHIP-ANALYTICS.md
  • esa capa debe preservar por separado ownership formal, ultima venta, ownership efectivo, recuperacion, crecimiento, riesgo y abandono sin reemplazar la autoria real de la venta

A. Datos existentes del ERP / SGC / sistema de ventas

Datos que razonablemente deberian existir ya en fuentes operativas de APV, como clientes, vendedores, productos, ventas, comprobantes, stock y maestros comerciales.

B. Datos existentes que deben validarse

Datos plausibles pero aun no confirmados con suficiente calidad, cobertura o vigencia, como historicos, zonas, supervisores, vigencias o unidades por bulto.

C. Datos nuevos a capturar

Datos que hoy no tienen una fuente madura y deberian capturarse en el futuro, como demanda no atendida, relevamientos, acciones comerciales o resultados de esas acciones.

D. Datos calculados futuros

Datos que no deben cargarse como verdad primaria sino derivarse luego con trazabilidad, como riesgo comercial, margen estimado, rentabilidad estimada, score de prioridad o recomendacion priorizada.

E. Datos de gobierno comercial

Datos que ordenan foco y ownership comercial, como objetivos, metas, prioridades, responsables, ventanas y criterios de cumplimiento.

F. Datos de auditoria y trazabilidad

Datos que permiten explicar origen, vigencia, responsable, ultima actualizacion y confianza de cada lectura futura.

5. Catalogo funcional de datos

Dato funcional Descripcion Categoria Origen esperado Responsable de generacion Responsable de validacion Frecuencia esperada Nivel de confianza inicial Casos de uso consumidores Prioridad Observaciones
codigo de cliente Identificador comercial estable del cliente A ERP / SGC / maestro clientes sistema origen direccion comercial / administracion diaria o por sync alta UC001, UC002, UC003, UC004, UC007, UC008 alta clave base para trazabilidad
razon social / nombre Nombre comercial del cliente A maestro clientes sistema origen administracion comercial diaria o por sync alta UC001, UC002, UC003, UC004, UC007, UC008 alta debe evitar duplicados
localidad Ubicacion comercial del cliente B maestro clientes sistema origen supervision comercial diaria o por sync media UC004, UC006, UC008, UC009 media validar consistencia de nombres
provincia Provincia asociada al cliente B maestro clientes sistema origen supervision comercial diaria o por sync media UC004, UC006, UC008, UC009 media importante para lectura territorial
zona Agrupacion logistica de clientes para rutas, reparto y operacion B maestro clientes / definicion operativa sistema origen / operacion comercial supervision comercial semanal o por cambio media UC002, UC003, UC005, UC006, UC007, UC008, UC009 media no usar para inferir vendedor responsable; puede requerir normalizacion
vendedor asignado Vendedor responsable del cliente A maestro clientes sistema origen direccion comercial diaria o por sync alta UC001, UC002, UC003, UC004, UC007, UC008 alta control critico de ownership
estado comercial Estado funcional del cliente B maestro clientes / direccion comercial sistema origen / direccion comercial direccion comercial semanal o por cambio media UC001, UC002, UC007, UC008 media distinguir activo, inactivo, pausado o baja; baja no implica eliminacion
fecha baja cliente Fecha en la que el cliente pasa a baja comercial B maestro clientes sistema origen / direccion comercial direccion comercial semanal o por cambio media UC001, UC002, UC003, UC005, UC007, UC008, UC009 alta debe preservarse como hito historico y no como criterio de borrado
fecha ultima compra Ultima fecha de compra confirmada A ventas / comprobantes sistema origen direccion comercial diaria alta UC001, UC002, UC005, UC007 alta base para riesgo comercial
codigo vendedor Identificador estable del vendedor A maestro vendedores sistema origen direccion comercial diaria o por sync alta UC001 a UC009 alta clave operativa minima
nombre vendedor Nombre del vendedor A maestro vendedores sistema origen direccion comercial diaria o por sync alta UC001 a UC009 alta lectura humana y ownership
supervisor Responsable jerarquico del vendedor B maestro vendedores / direccion comercial sistema origen / direccion comercial direccion comercial semanal o por cambio media UC002, UC003, UC005, UC007, UC009 media validar vigencia organizacional
zona vendedor Agrupacion operativa o logistico-administrativa del vendedor B maestro vendedores sistema origen supervision comercial semanal o por cambio media UC002, UC003, UC005, UC006, UC007, UC009 media no asumir equivalencia exacta con la zona del cliente ni con su territorio comercial
estado vendedor Estado funcional del vendedor B maestro vendedores sistema origen direccion comercial semanal o por cambio media UC001, UC002, UC003, UC007 media activo, licencia, baja, etc.
SKU Identificador operativo del item A maestro productos sistema origen administracion comercial diaria o por sync alta UC002, UC004, UC005, UC006, UC007, UC008, UC009 alta granularidad real de stock, precio y venta
descripcion Descripcion comercial del item A maestro productos sistema origen administracion comercial diaria o por sync alta UC002, UC004, UC006, UC008, UC009 alta debe ser interpretable para negocio
marca Marca del producto o SKU A maestro productos sistema origen direccion comercial diaria o por sync alta UC001, UC002, UC003, UC004, UC006, UC007, UC008, UC009 alta critica para regla 90/10
proveedor Proveedor asociado al SKU; debe conservar Cod Proveedor como identificador de negocio y Proveedor como nombre legible A maestro productos / compras sistema origen compras / direccion comercial diaria o por sync alta UC002, UC003, UC006, UC007, UC008, UC009 alta no usar solo el texto de proveedor como clave analitica
categoria Categoria comercial B maestro productos sistema origen direccion comercial diaria o por sync media UC001, UC008, UC009 media revisar normalizacion
unidades por bulto Conversion comercial a bultos B maestro productos sistema origen administracion comercial diaria o por sync media UC004, UC005, UC008, UC009 media importante para comparacion operativa
estado producto Estado funcional del producto B maestro productos sistema origen direccion comercial semanal o por cambio media UC002, UC006, UC008, UC009 media activo, discontinuado, pausado
producto estrategico si/no Marca de prioridad comercial del producto E direccion comercial direccion comercial gerencia comercial por ventana media UC002, UC007, UC008, UC009 media dato de gobierno, no transaccional
marca estrategica si/no Marca de prioridad comercial de la marca E direccion comercial direccion comercial gerencia comercial por ventana media UC001, UC002, UC007, UC008, UC009 alta no confundir con marca normal
fecha venta Fecha del hecho de venta A ventas / comprobantes sistema origen administracion comercial diaria alta UC001, UC002, UC003, UC005, UC006, UC008, UC009 alta base temporal principal
tipo comprobante Tipo documental de la operacion A comprobantes sistema origen administracion comercial diaria alta UC005, UC001, UC002 alta distinguir facturas, notas, etc.
estado comprobante Estado del comprobante segun logica documental de SOURCE-003 A comprobantes sistema origen administracion comercial diaria alta UC005, UC001, UC002 alta no inferir anulados fuera de la query autoridad
cliente en venta Referencia del cliente en la transaccion A ventas / comprobantes sistema origen administracion comercial diaria alta UC001, UC002, UC003, UC004, UC007, UC008 alta debe cruzar contra maestro
vendedor en venta Referencia del vendedor en la transaccion A ventas / comprobantes sistema origen direccion comercial diaria alta UC001, UC002, UC003, UC005, UC007 alta ownership real de la venta
SKU en venta SKU vendido A ventas / comprobantes sistema origen administracion comercial diaria alta UC002, UC003, UC004, UC005, UC006, UC008, UC009 alta no reemplazar por producto agregado
unidades Unidades vendidas A ventas / comprobantes sistema origen administracion comercial diaria alta UC002, UC003, UC004, UC005, UC008, UC009 alta medida operativa base
bultos Equivalencia comercial en bultos B ventas / conversion de producto sistema origen administracion comercial diaria media UC004, UC005, UC008, UC009 media depende de unidades por bulto
venta neta Importe neto de la venta A ventas / comprobantes sistema origen administracion / direccion comercial diaria alta UC001, UC002, UC003, UC005, UC006, UC007, UC008 alta aclarar criterio neto
line_key o clave funcional de linea Identificador robusto de la linea itemizada sincronizada B derivado de SOURCE-003 / Tabla 2 capa futura de sync direccion comercial / datos diaria media UC001, UC002, UC003, UC005, UC006, UC008, UC009 alta necesaria porque un comprobante podria repetir el mismo SKU
proveedor en venta Codigo proveedor historico preservado en la transaccion A SOURCE-003 / Tabla 2 sistema origen compras / direccion comercial diaria alta UC002, UC003, UC006, UC007, UC008, UC009 alta en SOURCE-003, Proveedor = codigo proveedor
razon social proveedor en venta Nombre o razon social historica del proveedor preservada en la transaccion A SOURCE-003 / Tabla 2 sistema origen compras / direccion comercial diaria alta UC002, UC003, UC006, UC007, UC008, UC009 alta en SOURCE-003, RazonSocial_Proveedor = nombre proveedor
precio historico de venta Precio unitario o de linea preservado al momento de la transaccion A SOURCE-003 / Tabla 2 sistema origen administracion comercial diaria alta UC001, UC002, UC003, UC005, UC006, UC007, UC008 alta no depender del maestro actual
descuentos historicos Descuentos de linea o al pie preservados en la transaccion A SOURCE-003 / Tabla 2 sistema origen administracion comercial diaria alta UC001, UC002, UC003, UC005, UC006, UC007, UC008 alta necesarios para paridad economica
impuestos historicos IVA, IIBB y otros importes calculados preservados por linea A SOURCE-003 / Tabla 2 sistema origen administracion comercial diaria alta UC005, UC006, UC007, UC008, UC009 alta respetar precision y reglas de signo
costo historico de venta Costo asociado a la linea al momento de la transaccion B SOURCE-003 / Tabla 2 sistema origen direccion comercial / administracion diaria media UC006, UC007, UC008, UC009 alta no reconstruir luego desde PRODUCTS vigente
marca historica en venta Marca preservada dentro de la transaccion B SOURCE-003 / Tabla 2 sistema origen direccion comercial diaria media UC001, UC002, UC003, UC006, UC007, UC008, UC009 alta protege cambios futuros del maestro
peso, volumen y bultos historicos Contexto logistico preservado por linea de venta B SOURCE-003 / Tabla 2 sistema origen operaciones / administracion comercial diaria media UC004, UC005, UC008, UC009 alta no recalcular despues desde el producto vigente
costo Costo asociado al item vendido B costos / ventas sistema origen direccion comercial / administracion diaria o por vigencia media UC006, UC007, UC008 alta validar vigencia y cobertura
margen estimado Aproximacion de margen comercial D calculado desde venta y costo capa derivada futura direccion comercial diaria o por analisis baja-media UC006, UC007, UC008 media explicitar como estimado
rentabilidad estimada Lectura derivada de rentabilidad D capa derivada futura capa derivada futura direccion comercial / gerencia diaria o por analisis baja-media UC006, UC007, UC008 media no tratar como verdad exacta
stock actual Stock vigente observado A stock / ERP sistema origen compras / operaciones diaria o intradiaria media-alta UC004, UC007, UC008, UC009 alta validar si es teorico o vendible
stock diario al cierre Snapshot diario de stock C futura captura o export diario proceso futuro de captura compras / operaciones diaria baja UC004, UC005, UC008, UC009 media clave para historico de disponibilidad
fecha/hora de corte Momento del snapshot de stock F stock / proceso futuro sistema origen / proceso futuro operaciones diaria o intradiaria media UC005, UC009 alta sin fecha de corte el stock pierde valor
SKU en stock SKU del registro de stock A stock / ERP sistema origen operaciones diaria o intradiaria alta UC004, UC005, UC008, UC009 alta debe cruzar con maestro
unidades en stock Unidades disponibles o teoricas A stock / ERP sistema origen operaciones diaria o intradiaria media-alta UC004, UC005, UC008, UC009 alta aclarar disponible vs teorico
bultos en stock Equivalencia en bultos del stock B stock / conversion producto sistema origen operaciones diaria o intradiaria media UC004, UC005, UC009 media dependiente de conversion valida
estado de faltante Senal de disponibilidad critica D derivacion futura / operaciones capa derivada futura operaciones / compras diaria media UC004, UC005, UC007, UC009 media no cargar sin criterio explicito
costo vigente Ultimo costo aceptado como vigente A costos / listas internas sistema origen administracion / direccion comercial por cambio media UC006, UC007 alta costo sin fecha no sirve
fecha ultima actualizacion costo Fecha de vigencia del costo B costos / listas internas sistema origen administracion por cambio media UC006, UC007 alta dato critico para comparabilidad
precio lista vigente Precio propio vigente A listas de precio sistema origen direccion comercial / administracion por cambio media-alta UC006, UC007 alta debe quedar separado de competencia
fecha vigencia precio Fecha desde la que aplica el precio B listas de precio sistema origen administracion por cambio media UC006, UC007 alta precio sin vigencia no es util
precio especial si aplica Precio especial negociado B listas / acuerdos comerciales direccion comercial / administracion direccion comercial por evento baja-media UC006, UC007 media usar con contexto y owner
fecha relevamiento Fecha del relevamiento de mercado C formulario futuro / vendedor vendedor supervision comercial por evento baja-media UC004, UC006, UC009 media todo relevamiento debe tener fecha
vendedor relevamiento Vendedor que informa C formulario futuro / vendedor vendedor supervision comercial por evento media UC004, UC006, UC009 media ownership humano claro
cliente relevamiento Cliente vinculado al relevamiento C formulario futuro / vendedor vendedor supervision comercial por evento media UC004, UC006 media puede ser opcional segun contexto
SKU/marca relevada Item o marca observada C formulario futuro / vendedor vendedor direccion comercial por evento media UC004, UC006, UC009 media permitir granularidad flexible
precio esperado Precio que el cliente considera razonable C relevamiento vendedor vendedor supervision comercial por evento baja UC004, UC006 media dato subjetivo; no tratar como hecho
precio competencia Precio observado en competencia C relevamiento vendedor vendedor direccion comercial por evento baja-media UC006 media declarar contexto de comparabilidad
fecha compra competidor Fecha de compra a competidor informada C relevamiento vendedor / cliente vendedor supervision comercial por evento baja UC006 baja-media puede no existir siempre
fecha oferta competidor Fecha de oferta o promocion observada C relevamiento vendedor vendedor supervision comercial por evento baja UC006 baja-media clave para no leer precios fuera de tiempo
comentario relevamiento Comentario libre contextual C relevamiento vendedor vendedor supervision comercial por evento baja-media UC004, UC006, UC009 media no reemplaza campos estructurados
nivel de confianza relevamiento Grado de confianza del relevamiento F formulario futuro vendedor supervision comercial por evento media UC004, UC006, UC009 media ayuda a filtrar lecturas debiles
fecha informe demanda Fecha del reporte de demanda no atendida C formulario futuro / vendedor vendedor supervision comercial por evento media UC004, UC007, UC009 alta base minima de la captura manual
cliente demanda Cliente afectado por demanda no atendida C formulario futuro / vendedor vendedor supervision comercial por evento media UC004, UC007 alta clave para accion comercial
vendedor demanda Vendedor que reporta la demanda C formulario futuro / vendedor vendedor supervision comercial por evento media UC004, UC007, UC009 alta ownership del reporte
SKU/marca solicitada Producto o marca pedida y no atendida C formulario futuro / vendedor vendedor direccion comercial por evento media UC004, UC007, UC009 alta permitir item o marca si no hay SKU
cantidad solicitada opcional Cantidad estimada requerida C formulario futuro / vendedor vendedor supervision comercial por evento baja UC004, UC009 media opcional para no bloquear captura
precio esperado opcional Precio que el cliente hubiera aceptado C formulario futuro / vendedor vendedor supervision comercial por evento baja UC004, UC006 baja-media no debe exigirse siempre
causa probable Motivo probable de no atencion C formulario futuro / vendedor vendedor supervision comercial por evento baja-media UC004, UC009 media idealmente normalizada
sustituto aceptado si/no Si hubo sustitucion aceptada C formulario futuro / vendedor vendedor supervision comercial por evento media UC004, UC006, UC007 media separa perdida total de parcial
quiere aviso de reposicion si/no Preferencia de seguimiento del cliente C formulario futuro / vendedor vendedor supervision comercial por evento media UC004, UC007, UC009 baja-media util para accion futura
fecha accion Fecha de accion comercial C registro futuro de acciones vendedor / supervisor / direccion direccion comercial por evento media UC003, UC007 media trazabilidad minima
tipo accion Tipo normalizado de accion comercial C registro futuro de acciones vendedor / supervisor / direccion direccion comercial por evento media UC003, UC007 media requiere catalogo futuro
responsable accion Persona o rol responsable E registro futuro de acciones vendedor / supervisor / direccion direccion comercial por evento alta UC003, UC007 media ownership obligatorio
cliente objetivo accion Cliente alcanzado por la accion C registro futuro de acciones vendedor / supervisor supervision comercial por evento media UC003, UC007 media puede ser cliente, marca o proveedor
SKU/marca/proveedor objetivo Foco de la accion C registro futuro de acciones vendedor / supervisor direccion comercial por evento media UC003, UC007, UC009 media declarar sujeto principal
resultado esperado Resultado que se busca obtener E registro futuro de acciones responsable accion direccion comercial por evento media UC003, UC007 media conecta accion y aprendizaje
resultado observado Resultado real posterior C registro futuro de acciones responsable accion direccion comercial por evento baja-media UC003, UC007 media base del aprendizaje comercial
objetivo Objetivo comercial declarado E direccion comercial direccion comercial gerencia comercial por ventana alta UC002, UC003, UC005, UC007, UC008, UC009 media no es transaccion, es gobierno
meta Expresion medible del objetivo E direccion comercial direccion comercial gerencia comercial por ventana alta UC002, UC003, UC005, UC007, UC008, UC009 media requiere owner y ventana
owner Responsable del objetivo o meta E direccion comercial direccion comercial gerencia comercial por ventana alta UC002, UC003, UC005, UC007, UC008, UC009 media no se aceptan metas sin owner
ventana Periodo de vigencia de la meta E direccion comercial direccion comercial gerencia comercial por ventana alta UC002, UC003, UC005, UC007, UC008, UC009 media mensual, trimestral, etc.
unidad de medida Unidad usada para evaluar la meta E direccion comercial direccion comercial gerencia comercial por ventana alta UC002, UC003, UC005, UC007, UC008, UC009 media volumen, clientes, mix, etc.
estado meta Estado de cumplimiento de la meta D capa derivada futura / gobierno capa derivada futura direccion comercial semanal o por corte media UC003, UC007 baja-media no es dato fuente primario
criterio de cumplimiento Regla funcional para decidir si se cumple E direccion comercial direccion comercial gerencia comercial por ventana alta UC003, UC005, UC007 media evita interpretaciones ambiguas
fecha calendario Fecha de referencia del calendario A calendario oficial / capa tiempo sistema origen / calendario futuro direccion comercial / administracion diaria alta UC005 alta grano base temporal
dia calendario Numero o etiqueta del dia calendario A calendario oficial sistema origen administracion diaria alta UC005 media apoyo descriptivo
dia laborable teorico Si el dia era laborable en teoria B calendario oficial sistema origen administracion anual o por calendario alta UC005 alta no equivale a dia trabajado real
feriado si/no Marca de feriado B calendario oficial sistema origen administracion anual o por calendario alta UC005 alta relevante para comparabilidad
comprobantes emitidos si/no Evidencia de actividad documental D derivacion desde comprobantes capa derivada futura administracion comercial diaria media-alta UC005 alta regla APV de evidencia comercial
dia trabajado real si/no Lectura funcional de dia realmente trabajado D derivacion futura desde calendario y comprobantes capa derivada futura direccion comercial diaria media UC005, UC009 alta no asumir automatico sin criterio
recomendacion Texto o etiqueta de la recomendacion D capa derivada futura observer futuro direccion comercial por evento baja-media UC007 baja-media salida futura, no fuente primaria
origen recomendacion Senales y UC que la originan F capa derivada futura observer futuro direccion comercial por evento media UC007 baja-media trazabilidad obligatoria
evidencia recomendacion Resumen de evidencia usada F capa derivada futura observer futuro direccion comercial por evento media UC007 baja-media no recomendar sin evidencia visible
prioridad recomendacion Orden relativo de atencion D capa derivada futura observer futuro direccion comercial por evento baja-media UC007 baja-media no es hecho observado
responsable recomendacion Actor objetivo o owner E capa derivada futura / direccion comercial observer futuro / direccion comercial direccion comercial por evento media UC007 baja-media debe quedar claro quien decide
estado recomendacion Estado de ejecucion humana C seguimiento futuro actor humano responsable direccion comercial por evento baja-media UC003, UC007 baja sirve para recomendado vs ejecutado
resultado recomendacion Resultado posterior observado C seguimiento futuro actor humano responsable direccion comercial por evento baja UC003, UC007 baja no confundir con promesa

6. Matriz dato vs UC001-UC009

Bloque de datos UC001 UC002 UC003 UC004 UC005 UC006 UC007 UC008 UC009
clientes y estado comercial X X X X X X
vendedores, supervisores y zonas X X X X X X X X
productos, SKU, marcas y proveedores X X X X X X X X
categorias y unidades por bulto X X X X
ventas historicas X X X X X X X X
comprobantes y estado documental X X X
stock actual X X X X X
stock diario al cierre X X X X
costos y precios propios vigentes X X X
precios / contexto de competencia X X X
relevamientos de vendedores X X X
demanda no atendida X X X
acciones comerciales y resultados X X
objetivos, metas y owners X X X X X X
calendario operativo X X
recomendaciones y trazabilidad X X

Lectura funcional:

  • UC001 depende sobre todo de identidad comercial consistente y ultima compra
  • UC002 necesita cartera, producto, marca y foco comercial vigente
  • UC003 depende de registrar accion, resultado y responsable
  • UC004 necesita captura manual minima mas contexto de stock
  • UC005 exige capa temporal gobernada
  • UC006 requiere fecha y vigencia en todos los precios y costos
  • UC007 solo es responsable si hereda senales confiables de los demas UC
  • UC008 depende de surtido historico y catalogo limpio
  • UC009 necesita unir stock, faltantes, proveedor y evidencia de reclamo

7. MVP de datos para primera implementacion futura

Nivel MVP 1

Incluye:

  • clientes
  • vendedores
  • productos
  • marcas
  • proveedores
  • ventas historicas
  • comprobantes
  • stock actual
  • costos y precios propios vigentes

UC activables parcialmente:

  • UC001: si
  • UC002: si
  • UC005: si, en lectura basica por comprobantes
  • UC006: si, en lectura interna de costo y precio propio
  • UC008: si, en version inicial
  • UC009: si, con foco en stock actual y proveedor
  • UC007: solo de forma muy limitada y siempre explicada

Nivel MVP 2

Agrega:

  • stock diario al cierre
  • calendario operativo
  • demanda no atendida manual
  • relevamiento simple de vendedores

UC que ganan traccion:

  • UC004: pasa de intuicion a lectura funcional minima
  • UC005: mejora fuerte por dias efectivos y cortes de stock
  • UC006: gana contexto temporal y territorial
  • UC009: mejora al poder mirar faltantes y reclamos en el tiempo
  • UC007: mejora, pero sigue dependiendo de calidad de origen

Nivel MVP 3

Agrega:

  • precios competencia
  • acciones comerciales
  • resultados de acciones
  • objetivos y metas
  • sustituciones

UC que se vuelven mas maduros:

  • UC003: gana memoria comercial y aprendizaje real
  • UC006: mejora comparabilidad de pricing
  • UC007: pasa a tener una base mas seria para priorizacion
  • UC004: diferencia mejor venta perdida, sustitucion y oportunidad estimada
  • UC002 y UC008: se conectan mejor con foco comercial gobernado

Regla de priorizacion:

conviene abrir primero lo que hace confiables UC001, UC002, UC005, UC006, UC008 y UC009, antes de intentar sofisticar UC007.

7.1 Aclaracion de fuente de ventas calculadas

Para APV, el contrato deja explicitamente asentado que la capa transaccional de ventas y comprobantes debera respetar una fuente calculada y no una lectura cruda del ERP:

  • SOURCE-003: ventas / comprobantes calculados desde la query compartida por Gabi, registrada en esta iteracion como vNext candidate
  • salida principal documentada: Tabla 2 - Detalle items (composicion BalanceCtaCteFinal)
  • autoridad candidata preservada: source-authority/SOURCE-003-VENTAS-VNEXT-TABLA2-AUTHORITY.sql
  • autoridad anterior preservada: source-authority/SOURCE-003-VENTAS-TABLA2-AUTHORITY.sql
  • inventario real de Tabla 2 vNext: SOURCE-INVENTORY-RESULTS-003.md
  • decision de identidad de linea: design/SOURCE-003-LINE-IDENTITY-DECISION.md
  • diseno DDL documental futuro: design/SOURCE-003-SALES-ITEMS-DDL-DESIGN.md
  • analisis de deriva confirmado: SOURCE-003-DRIFT-ANALYSIS-001.md

Reglas de contrato:

  • SOURCE-003 debe tratar la query compartida por Gabi como autoridad funcional estricta de calculo y como candidata vNext para sync
  • SOURCE-003 / SGC Ventas debe tratarse como fuente viva, no como historico congelado por fecha de comprobante
  • el SGC puede modificar, anular, refacturar o ajustar comprobantes aproximadamente hasta 7 dias hacia atras por liquidacion de entregas, rechazos de clientes, anulaciones, refacturacion, descuentos posteriores, notas de credito, ajustes de cuenta corriente y cambios operativos de cobro/entrega
  • no debe usarse incremental simple basado solo en ultima fecha cargada
  • una fecha ya cargada puede cambiar si se reextrae desde SGC vivo
  • una linea puede aparecer, cambiar valores, desaparecer de la extraccion activa, quedar anulada o recibir nota de credito o ajuste posterior
  • SOURCE-003 debe sincronizar solo Tabla 2
  • Tabla 1, Tabla 3, Tabla 4, Tabla 5 y Tabla 6 deben tratarse como reportes derivados reconstruibles desde Tabla 2
  • la base sincronizada conceptual futura recomendada es source_003_sales_items
  • esa base debe preservar datos raw, datos normalizados, metricas calculadas por item y trazabilidad de sync
  • el DDL documental futuro de esa base ya queda preservado como diseno revisable; no es migracion ni autorizacion de ejecucion
  • la query vNext ya cuenta con inventario real controlado de Tabla 2, pero no queda declarada como runtime productivo ni como DDL ejecutable
  • el estado oficial de preservacion de autoridad queda registrado en source-authority/SOURCE-AUTHORITY-REGISTRY.md
  • no debe reemplazar calculos por campos crudos del ERP
  • no debe tratar V_VENTAS como autoridad suficiente por si sola
  • debe respetar la composicion completa entre V_VENTAS, VCLIENTES, PRODUCTS, VPROVEEDORES y calculos
  • no debe simplificar IVA, IIBB, descuentos, CMV, notas de credito, guias, motivos ni BalanceCtaCteFinal
  • debe preservar suficiente precision para evitar diferencias futuras por redondeo
  • debe modelar el grano esperado como: fecha + cliente + comprobante + documento + SKU + seller_transactional + linea_tecnica
  • debe contemplar una line_key o clave funcional robusta para no colapsar lineas cuando un comprobante repite el mismo SKU
  • la decision humana acepta line_key_v4 en estado AMARILLO ACEPTADO para sync inicial analitico de ventas itemizadas
  • line_key_v4 se compone con: fecha, hora_origen_sgc, tipo_comp, nro_comp, tipo_doc_int, nro_int_doc, documento, codigo_cliente, sku, vendedor y line_sequence_v1
  • no existe line_id_source fisico disponible en la vista SGC accesible
  • line_sequence_v1 debe preservarse como columna tecnica de pipeline basada en ROW_NUMBER(); resuelve unicidad agregada, pero no representa identidad fisica ERP
  • el alcance de line_key_v4 es Business Observer, analytics, BI, IA y ML; no es auditoria legal perfecta de renglones ERP
  • la regla preservada source_row_hash_v1 debe cubrir las 68 columnas reales de Tabla 2 V2 segun el mapping CSV/PostgreSQL vigente, incluyendo identidad documental, cliente, vendedor, producto, proveedor, entrega, reparto, unidades, precios, descuentos, impuestos, importes, CMV, costos, canal, ramo, motivo de devolucion, peso, volumen y bultos
  • debe preservar contexto historico de transaccion: costo, proveedor, marca, precio, descuentos, impuestos, peso, volumen y bultos
  • cualquier sync futuro debera combinar carga historica inicial, snapshot diario, ventana movil inicial sugerida de 10 dias y trazabilidad de cambios
  • la persistencia futura debera hacer upsert por tenant_id + line_key, comparar source_row_hash, refrescar last_seen_at si no cambia, actualizar si cambia y marcar missing_from_source si deja de aparecer en una extraccion full o ventana controlada
  • no debe hacer hard delete sobre ventas sincronizadas
  • el freeze date de pilotos, conciliaciones y cortes auditables debe salir del snapshot tomado, no de una consulta posterior a SGC vivo
  • debe preservar el estado raw del comprobante si la salida o una extension de autoridad lo expone
  • antes de produccion final, se debe revalidar line_key_v4 en backfill o ventana mayor adicional, confirmar escalas numericas, schema destino, permisos y particionado por fecha

Tablas derivadas futuras recomendadas desde source_003_sales_items:

  • analytics_sales_daily
  • analytics_sales_by_seller_daily
  • analytics_sales_by_customer_daily
  • analytics_sales_by_product_daily
  • analytics_sales_by_brand_daily
  • analytics_sales_by_supplier_daily
  • analytics_sales_rejections_daily
  • analytics_cmv_margin_daily
  • analytics_sales_logistics_daily

7.2 Aclaracion de fuentes de stock futuras

Para APV, el contrato deja explicitamente separadas dos capas futuras:

  • SOURCE-002: maestro de productos vigente y fuente base de stock actual, proveedor, costos, precios y logistica comercial
  • SOURCE-002C: snapshot diario de inventario al cierre aproximado de 17:00
  • SOURCE-002D: stock intradiario liviano con frecuencia funcional sugerida de 10 minutos

La separacion es obligatoria porque:

  • una capa sirve para historia diaria gobernada
  • la otra sirve para estado vivo y deteccion intradiaria de reposicion

La frontera con SOURCE-002 tambien es obligatoria porque:

  • SOURCE-002 es la autoridad vigente del maestro de productos
  • la query preservada de SOURCE-002 queda confirmada por Gabi como autoridad vigente de ahora en adelante
  • tenant_id + SKU queda documentado como clave canonica del dominio producto
  • todo dato que salga de SOURCE-002 debe leerse como atributo, medicion, relacion vigente o relacion historica del SKU
  • SKU NOT IN ('0124', '3857', '3998', '3793') queda documentado como la primera lista conocida de exclusiones operativas
  • esos SKU se excluyen porque pueden representar articulos usados para operaciones internas o no tradicionales de compra/venta y no productos comerciales normales
  • SOURCE-002C agrega historia diaria
  • SOURCE-002D agrega seguimiento intradiario liviano

Reglas de contrato:

  • SOURCE-002 sigue siendo la fuente base vigente para stock actual dentro del maestro de productos
  • cualquier futuro script de sincronizacion de SOURCE-002 debera tratar la lista de exclusiones operativas como configurable
  • SOURCE-002C no reemplaza SOURCE-002D
  • SOURCE-002D no reemplaza SOURCE-002C
  • SOURCE-002C no reemplaza SOURCE-002
  • SOURCE-002D no reemplaza SOURCE-002
  • ninguna de las dos implica todavia implementacion, tabla final, script definitivo ni API

7.3 Separacion futura de producto, stock y valores economicos

Sin disenar tablas reales, el contrato recomienda esta separacion conceptual futura para Postgres:

  • producto maestro: identidad estable del SKU, marca, categoria, proveedor, estado, unidades por bulto, PLU, logistica y atributos relativamente lentos
  • stock actual: ultima observacion intradiaria liviana por SKU, con timestamp y origen
  • stock historico diario: fotografia diaria por SKU con corte de cierre y contexto minimo de producto
  • listas de precios: capa separada para precios por lista y por SKU, con vigencia y trazabilidad
  • costos: capa separada para costo vigente y sus cambios con fecha efectiva
  • impuestos: capa separada o bloque economico separado para IVA y otros atributos fiscales que cambien en el tiempo
  • margenes y descuentos: capa separada para margen, descuentos de compra, descuento permitido y reglas comerciales variables

Regla conceptual:

  • tenant_id + SKU debe seguir siendo la ancla comun entre todas las capas futuras derivadas del maestro de productos
  • no conviene guardar todo dentro de una sola entidad de producto
  • tampoco conviene historizar cada dominio con el mismo nivel de detalle
  • el detalle historico debe responder a cambio real y utilidad comercial

Documento de soporte:

  • SOURCE-002-FUTURE-LAYER-MAPPING.md: baja esta separacion a una matriz de campos y capas futuras recomendadas
  • SOURCE-002-ECONOMIC-LAYER.md: cierra la decision de modelar listas de precios como filas normalizadas por SKU + lista_codigo y no como columnas fijas L1..L9 en la capa destino principal; tambien documenta que CostoListaProveedor es precio de lista proveedor, que Dcto Compra 1..3 son descuentos encadenados y que Costo es el costo unitario neto final a pagar al proveedor; ademas deja el ejemplo real de L7 compartido por Gabi para validar el patron repetible MargenLn, PrecioLn, IVAPrecioLn y PrecioNetoLn

7.4 Regla documental para precios, costos, impuestos y margenes

Como estos valores pueden cambiar durante el dia, la recomendacion documental es una combinacion liviana:

  • dentro del producto maestro: solo el ultimo valor vigente visible para lectura operativa actual
  • en snapshot diario: un valor de cierre opcional y resumido cuando haga falta contexto historico
  • en historial por cambio: la trazabilidad principal de listas, costos, impuestos, margenes y descuentos cuando cambie un valor

Esta combinacion es la mas prudente porque:

  • evita que el maestro pierda utilidad operativa
  • evita que el snapshot diario cargue demasiada historia
  • evita perder cambios intradiarios relevantes si solo se pisa el ultimo valor

Lectura contractual:

  • precio y costo no deberian vivir solo dentro del maestro
  • precio y costo tampoco deberian vivir solo en snapshot diario
  • el historico por cambio es el lugar documental correcto para trazabilidad fina
  • SOURCE-002D no debe transportar precio, costo, impuesto, margen ni descuento
  • SOURCE-002C puede conservar stock de cierre y un contexto economico resumido, pero no debe reemplazar los historiales por cambio

7.5 Cierre de cobertura documental de SOURCE-002

Queda documentado adicionalmente que la autoridad preservada de SOURCE-002 devuelve 81 campos en su SELECT vigente y que los 81 campos quedan:

  • clasificados documentalmente
  • relacionados por tenant_id + SKU
  • asignados a una capa futura conceptual
  • tipificados como vigente, historico util, snapshot proyectado o auditoria futura segun corresponda

Referencia oficial del detalle campo por campo:

  • SOURCE-002-FUTURE-LAYER-MAPPING.md

Resultado documental:

  • no quedan campos de SOURCE-002 fuera de documentacion
  • no quedan campos de SOURCE-002 sin relacion clara con tenant_id + SKU
  • no quedan campos de SOURCE-002 sin capa futura asignada

Cobertura documental SOURCE-002: 100% de campos del SELECT clasificados.

8. Futuro diseno Postgres

Sin disenar SQL ni nombres finales de tablas productivas, este contrato deja estas reglas:

  • toda tabla futura debe alinearse con docs/governance/standards/DATA-DESIGN-STANDARD.md
  • cada entidad funcional podra transformarse luego en tablas Postgres
  • cualquier nombre de tabla mencionado en el futuro durante diseno conceptual debera considerarse tentativo y no definitivo
  • cada tabla futura debera declarar al menos origen, owner, fecha de actualizacion y estado de validacion
  • cada tabla futura debera respetar separacion tenant y contexto comercial
  • no se deben crear tablas sin caso de uso asociado
  • no se debe crear una tabla solo porque el sistema origen la tenga
  • la estructura futura debe diferenciar dato real, relevado, estimado y calculado
  • las entidades de auditoria y trazabilidad son parte del contrato, no un agregado opcional

Aplicacion contractual minima para APV:

  • created_at y updated_at internos son obligatorios salvo excepcion documentada
  • fecha_alta_sgc no reemplaza created_at
  • fecha_modificacion_origen, si existe, debe vivir separada de updated_at
  • source_row_hash debe evaluarse cuando convenga detectar cambios sin comparar campo por campo
  • sync_batch_id debe evaluarse para trazabilidad de sync y auditoria
  • last_seen_at debe evaluarse para reconciliacion y desaparicion de filas en origen
  • features_json y metadata_json solo deben usarse para metadata flexible o preparacion analitica no critica
  • JSON no debe reemplazar columnas criticas del negocio

Actualizacion documental 2026-06-10:

  • el primer diseno fisico conceptual PostgreSQL para Business Observer APV queda documentado en docs/tenants/alpuntodeventa/business-observer/design/POSTGRES-PHYSICAL-ARCHITECTURE.md
  • ese documento baja este contrato y el DATA-DESIGN-STANDARD a grupos de tablas futuras para sync, auditoria, clientes, productos, ventas, territorio y analytics
  • no crea DDL, migraciones, tablas, queries ni vistas fisicas
  • preserva como pendientes la validacion real de Tabla 2, la conciliacion contra Tabla 1/3/4/5/6, la preparacion piloto/documental de line_key_v4, permisos y performance real
  • el DDL documental futuro de source_003_sales_items queda preservado en docs/tenants/alpuntodeventa/business-observer/design/SOURCE-003-SALES-ITEMS-DDL-DESIGN.md y su SQL documental no ejecutable en docs/tenants/alpuntodeventa/business-observer/design/sql/001_source_003_sales_items_design.sql

9. Futuro diseno de scripts de sincronizacion

Sin crear scripts, este contrato define que cada script futuro debera documentar como minimo:

  • nombre
  • origen
  • destino
  • frecuencia
  • campos esperados
  • validaciones
  • manejo de errores
  • evidencia de ultima corrida
  • owner
  • casos de uso afectados

Reglas funcionales:

  • ningun script debera cargar datos sin identificar el tenant
  • ningun script debera promover a dato real algo que era relevado o estimado
  • ningun script debera ocultar errores de cobertura, duplicado o vigencia
  • si un script sincroniza SOURCE-001, no debera filtrar la extraccion base a solo CLIENTE ACTIVO
  • si un script sincroniza SOURCE-001, debera preservar en la base sincronizada CLIENTE ACTIVO, CLIENTE SUSPENDIDO y CLIENTE DE BAJA
  • si un script sincroniza SOURCE-001, debera guardar Estado como estado_raw y derivar el estado operativo en una capa posterior o explicitamente trazada
  • si un script sincroniza SOURCE-001, debera aplicar filtros de venta o facturacion solo en vistas o capas de consumo derivadas y no en la base sincronizada
  • si un script sincroniza SOURCE-001, debera distinguir entre baja comercial explicita y desaparicion completa del registro en una extraccion
  • si un script sincroniza SOURCE-001, no debera habilitar hard delete por baja comercial
  • si un script sincroniza SOURCE-002, debera externalizar la lista de SKU excluidos como regla operativa configurable y trazable
  • si un script sincroniza SOURCE-003, debera reprocesar una ventana movil controlada, sugerida inicialmente de 10 dias
  • si un script sincroniza SOURCE-003, debera usar upsert por tenant_id + line_key y comparar source_row_hash
  • si un script sincroniza SOURCE-003, debera refrescar last_seen_at para filas sin cambios y actualizar la fila cuando cambie source_row_hash
  • si un script sincroniza SOURCE-003, debera marcar missing_from_source cuando una linea deje de aparecer dentro de una extraccion full o ventana controlada
  • si un script sincroniza SOURCE-003, no debera hacer hard delete
  • si un script sincroniza SOURCE-003, debera congelar fechas piloto desde snapshot y no desde una relectura posterior de SGC vivo
  • toda corrida futura debera dejar evidencia trazable para auditoria

9.1 Rutina futura segura y liviana

Rutina documental recomendada:

  • alta frecuencia: SOURCE-002D solo para stock intradiario liviano
  • una vez por dia: SOURCE-002C para snapshot diario de stock y contexto minimo de producto
  • por cambio: listas de precios, costos, impuestos, margenes y descuentos
  • opcional en cierre diario: snapshot economico resumido de cierre si negocio necesita comparar el valor con el stock del mismo dia

Regla de carga:

  • consultar mas seguido solo lo que cambia rapido y es liviano
  • consultar una vez por dia lo que sirve para historia comparativa
  • preservar por cambio lo que perderia trazabilidad al sobrescribirse

Decision documental adicional para SOURCE-002:

  • tenant_id + SKU es la clave canonica del dominio producto
  • la capa economica principal debe normalizar listas de precios como entidad repetible por SKU + lista_codigo
  • PrecioL1..PrecioL9 y campos equivalentes no deben ser el diseno estructural principal de tablas futuras
  • si el ERP agrega L10, L11 u otras listas, el modelo principal no debe requerir cambio de estructura
  • la semantica de costo de compra debe preservar CostoListaProveedor como precio de lista proveedor, Dcto Compra 1..3 como descuentos encadenados y Costo como costo unitario neto final
  • Cod Proveedor debe preservarse como identificador de negocio del proveedor asociado al SKU
  • Proveedor debe preservarse como nombre o razon social legible asociado al SKU
  • Marca debe preservarse como atributo comercial asociado al SKU
  • si aparece codigo de marca en el futuro, debera preservarse junto con Marca
  • JSON o payload agregado solo puede usarse como cache, vista materializada o auditoria secundaria

10. Validaciones minimas futuras

Validaciones base requeridas:

  • cantidad de registros
  • fechas maximas
  • duplicados
  • clientes sin vendedor
  • productos sin marca
  • ventas anuladas excluidas
  • stock negativo
  • costos nulos
  • precios nulos
  • comprobantes fuera de periodo
  • datos manuales incompletos

Lectura recomendada:

  • si falla identidad comercial, se degrada UC001, UC002 y UC008
  • si falla tiempo o vigencia, se degrada UC005 y UC006
  • si fallan datos manuales, se degradan UC003, UC004, UC006 y UC009
  • UC007 debe heredar bloqueos o alertas de calidad, no ignorarlos

11. Riesgos

Riesgos principales:

  • crear tablas antes de definir datos
  • confundir dato estimado con dato real
  • mezclar tenants
  • usar precios sin vigencia
  • usar stock no confiable
  • cargar datos manuales sin validacion
  • sobrecargar vendedores
  • construir recomendaciones con datos debiles

Riesgo rector:

querer llegar a recomendaciones maduras antes de estabilizar identidad, vigencia, calendario y disponibilidad.

12. Reglas de aceptacion de un dato

Un dato entra al contrato solo si:

  • sirve a un UC real
  • tiene origen claro
  • tiene responsable
  • tiene frecuencia
  • tiene uso definido
  • tiene criterio minimo de calidad

Un dato no deberia entrar si:

  • existe solo por intuicion tecnica
  • no tiene consumidor funcional claro
  • mezcla APV con otro tenant
  • no puede distinguirse de una estimacion o comentario
  • no tiene nadie responsable de explicarlo o corregirlo

12.1 Regla de historizacion por valor de decision

Todo dominio de datos futuro debe evaluar, desde diseno, si necesita historizacion por valor de decision.

Aplicacion minima ya documentada para APV:

  • cambios de costo
  • cambios de precio y listas
  • cambios de IVA
  • cambios de margen y descuento
  • quiebres de stock
  • recuperaciones de stock
  • ingresos de mercaderia
  • snapshots diarios utiles

Criterio contractual:

  • si el dato solo aporta lectura actual, puede quedar como vigente
  • si el dato ayuda a comparar en el tiempo, explicar comportamiento o disparar alertas, debe contemplar historico por cambio, vigencia o snapshot
  • la historizacion debe ser proporcionada al uso y no una acumulacion sin criterio

13. Proximo paso recomendado

El siguiente paso documental correcto, antes de cualquier implementacion, debe ser:

inventario de fuentes reales

Justificacion:

  • la auditoria ya identifico que datos parecen existir y cuales faltan
  • este contrato ya definio para que sirve cada dato y quien lo consume
  • todavia falta confirmar campo por campo que existe de verdad en APV
  • sin ese inventario no conviene pasar todavia a mapeo origen-destino completo
  • tampoco conviene disenar conceptualmente Postgres sin saber que calidad y cobertura real tienen las fuentes

Orden recomendado:

  1. inventario de fuentes reales
  2. mapeo origen-destino
  3. diseno conceptual Postgres

Actualizacion al 2026-06-08:

  • el primer mapeo origen-destino de SOURCE-001 ya queda documentado en mappings/SOURCE-001-CLIENTES-MAPPING.md
  • eso no reemplaza el inventario real pendiente de otras fuentes ni habilita cerrar todavia diseno fisico final de Postgres

Actualizacion al 2026-06-10:

  • el primer diseno fisico conceptual de PostgreSQL ya queda documentado en design/POSTGRES-PHYSICAL-ARCHITECTURE.md
  • sigue pendiente convertir ese diseno en DDL, migraciones, carga inicial y validaciones reales antes de cualquier implementacion

Validacion de coherencia

Resultado:

  • no contradice la auditoria de datos: SI
  • no duplica el rol de DATA-NEEDS.md: SI; DATA-NEEDS queda como sintesis y este documento como contrato detallado
  • no disena SQL: SI
  • no disena APIs: SI
  • no disena IA: SI
  • no declara implementacion: SI
  • respeta Core vs Tenant: SI
  • respeta APV vs La Directa: SI
  • vincula todos los datos con UC001 a UC009: SI

Confirmaciones de alcance

  • no se tocaron tablas
  • no se crearon bases
  • no se crearon scripts
  • no se toco runtime
  • no se toco VPS
  • no se toco Docker
  • no se toco OpenClaw runtime
  • no se toco Portainer
  • no se toco NPM
  • no se disenaron APIs
  • no se diseno IA