Product 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/PRODUCT-BLUEPRINT.md

Autoridades relacionadas:

1. Definicion del dominio¶

Un Producto es la entidad de catalogo comercial que APV vende, compra, precio, analiza y cruza contra ventas, clientes, proveedores, marcas, territorios y acciones comerciales.

No es solamente un SKU tecnico del ERP.

El SKU es la identidad canonica actual del producto, pero el dominio producto incluye tambien:

articulo o descripcion comercial
marca
proveedor
categoria, rubro o grupo cuando aplique
costos
precios
impuestos, margenes y descuentos cuando esten documentados
estado comercial
politica comercial vigente
senales para mix, margen, recuperacion y recomendacion

2. Que representa para OpenClaw/APV¶

Para OpenClaw / APV, producto representa la unidad comercial que explica:

que se vende
que marcas y proveedores mueven la venta
que mix compra cada cliente
que productos generan margen
que productos activan, recuperan o desarrollan cuentas
que SKU sostienen oportunidades de crecimiento, abastecimiento e IA

El producto es el puente entre catalogo, venta itemizada, margen, proveedor, marca, territorio y recuperacion comercial.

3. Fuente primaria actual¶

La fuente primaria actual del dominio producto es SOURCE-002, basada en la autoridad preservada para maestro de productos SGC.

Lectura vigente:

SOURCE-002 es la fuente base actual para producto, marca, estado, stock, proveedor, costos, precios, IVA, margenes, descuentos y fechas operativas
tenant_id + SKU es la clave canonica del dominio producto
todo dato derivado desde SOURCE-002 debe interpretarse como atributo, medicion, relacion vigente o relacion historica del mismo SKU
SOURCE-002C y SOURCE-002D son capas futuras separadas para stock y no reemplazan a SOURCE-002

Este blueprint no copia el inventario de campos de SOURCE-002. Lo referencia como autoridad de source y como evidencia documental.

4. Identidad y claves de negocio¶

La identidad canonica actual del producto es:

tenant_id
sku

Campos funcionales de identidad y lectura humana:

sku
articulo
descripcion
marca
cod_proveedor
proveedor

Reglas:

tenant_id + sku es la clave canonica del dominio producto
sku debe preservarse como valor fuente y como valor canonicalizado cuando corresponda
articulo o descripcion comercial ayudan a lectura humana, pero no son clave
marca es atributo comercial asociado al SKU
proveedor debe preservar identificador de negocio y nombre legible
si aparece codigo de marca en el futuro, debe preservarse junto con el texto de marca
categoria, rubro o grupo pueden enriquecer segmentacion, pero no reemplazan al SKU
no se debe sobrescribir un SKU sin trazabilidad de origen, fecha y motivo

5. Estados o clasificaciones¶

Clasificaciones conceptuales del dominio producto:

estado comercial del producto
producto activo, pausado, discontinuado o equivalente cuando la fuente lo sostenga
producto estrategico o de foco comercial cuando la regla exista
producto excluido operativamente, cuando exista una lista gobernada
marca
proveedor
categoria
rubro
grupo
subcategoria
politica comercial vigente

Reglas:

estado_raw o valor fuente equivalente debe preservarse
el estado normalizado no debe borrar el estado fuente
una exclusion operativa no debe leerse automaticamente como baja historica
los productos no vendibles o excluidos deben poder preservarse para trazabilidad cuando negocio lo requiera
categorias, rubros y grupos deben tratarse como clasificaciones del SKU, no como identidades paralelas

6. Relaciones con otros dominios¶

El dominio producto se relaciona con:

Ventas / SOURCE-003: aporta ventas reales por SKU, fecha, cliente, vendedor transaccional, importes, descuentos, CMV, contribucion, notas de credito y devoluciones.
Clientes: se relaciona via compras reales, mix comprado, frecuencia de compra, recuperacion, activacion y sensibilidad comercial.
Ownership: permite explicar que vendedor desarrolla una cuenta por marcas, proveedores, categorias, margen y expansion de mix.
Territory: permite leer que productos, marcas o proveedores se venden por localidad, provincia, zona logistica o territorio comercial derivado.
Proveedor: debe analizarse desde los SKU asociados, no desde textos sueltos.
Marca: debe analizarse desde los SKU asociados y su venta real.
Analytics: calcula mix, margen, contribucion, rotacion, recuperacion y oportunidades.
IA / ML: puede recomendar productos, detectar canastas, explicar recuperacion, priorizar reposicion o sugerir acciones comerciales con trazabilidad.

7. Reglas obligatorias¶

Reglas cerradas para el dominio producto:

no usar descripcion como clave
no usar articulo como clave unica
no sobrescribir SKU sin trazabilidad
preservar valor fuente y valor normalizado cuando haya ambiguedad
preservar raw + normalized en marca, proveedor, categoria, rubro o grupo cuando exista variacion textual o necesidad analitica
separar costo de origen de metricas calculadas de margen
separar precio de origen de metricas calculadas de rentabilidad
no mezclar costo, precio, impuesto, margen y descuento como una unica verdad sin vigencia
no analizar proveedor o marca desde textos sueltos si existe relacion con SKU
no tratar SOURCE-002C ni SOURCE-002D como reemplazo del maestro SOURCE-002
no convertir este blueprint en mapping de campos ni DDL

8. Preguntas de negocio que debe responder¶

Este blueprint debe permitir responder:

que productos vende APV
que SKU existen como catalogo comercial
que marca domina la venta
que proveedor domina la venta
que productos generan margen
que productos activan clientes
que productos o SKU ayudan a recuperar cuentas
que productos sostienen crecimiento de una cartera
que mix compra un cliente
que mix trabaja realmente un vendedor
que productos explican territorio perdido o recuperable
que categorias, rubros o grupos conviene observar para accion comercial

9. Analytics / IA / ML que habilita¶

El dominio producto habilita:

analytics de margen por SKU
analytics de contribucion por marca y proveedor
lectura de mix por cliente, vendedor y territorio
deteccion de productos activadores de compra
deteccion de productos recuperadores de cuentas
oportunidades de cross-sell y up-sell
explicacion de crecimiento por marca, proveedor, categoria o rubro
priorizacion de acciones comerciales por margen y recuperacion
recomendaciones de surtido
modelos de afinidad cliente-producto
alertas de deterioro de mix
lectura de proveedores dominantes o vulnerables

Regla:

toda recomendacion debe poder volver a tenant_id + sku y a la evidencia de venta, precio, costo o clasificacion que la sostiene

10. Diseno futuro relacionado¶

Referencias conceptuales futuras ya documentadas en design:

source_002_products_core
source_002_products_commercial
source_002_products_supplier
source_002_products_costing
historiales futuros de precios, costos, impuestos, margenes y descuentos
analytics_sales_by_product_daily
analytics_sales_by_brand_daily
analytics_sales_by_supplier_daily
analytics_cmv_margin_daily

Estas referencias no son tablas creadas, no son DDL, no son migraciones y no autorizan implementacion.

Regla:

todas las capas futuras derivadas de producto deben permanecer ancladas a tenant_id + sku

11. Que NO es este blueprint¶

Este documento no es:

una query
un mapping campo por campo de SOURCE-002
un contrato de datos
una fuente de autoridad
un inventario de resultados
un SQL
un DDL
una migracion
una tabla de productos
una tabla de precios
una tabla de costos
una implementacion
una autorizacion para tocar runtime
un reemplazo de SOURCE-002
un reemplazo de SOURCE-002-FUTURE-LAYER-MAPPING
un reemplazo de SOURCE-002-ECONOMIC-LAYER

12. Pendientes¶

Quedan pendientes:

diseno fisico final de historiales de precios, costos, impuestos y margenes
reglas finales de vigencia para precio, costo y politica comercial
normalizacion definitiva de categorias, rubros y grupos si negocio lo requiere
definicion final de productos estrategicos como dato gobernado
externalizacion operativa de exclusiones SOURCE-002
integracion fisica con ventas itemizadas
permisos de consumo para informacion economica sensible
validaciones futuras de cambios intradiarios de precio y costo
modelos de IA / ML de recomendacion con trazabilidad completa

13. 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