---
titulo: App de reportería comercial e inventario — especificación para agentes de código
fuente: https://www.puente.xyz/recursos/guia-reporteria-comercial
guia_texto: https://www.puente.xyz/recursos/guia-reporteria-comercial/guia.md
version: 1.0
actualizada: 2026-10-08
autor: Cris Ugarte, CEO de Puente OS
---

# Especificación: app de reportería comercial e inventario

## 0. Cómo usar este archivo

- Léelo completo antes de escribir código. Planifica primero.
- Entrevista al usuario con las 11 preguntas de §9, una por vez, antes de planificar. Guarda las respuestas.
- Construye en el orden de §5, una tarea a la vez. Al cerrar cada tarea, corre sus criterios (§6) con los datos de ejemplo (§7) y muestra la salida.
- Implementa la lógica general. Los datos de ejemplo sirven para probar; nunca fijes sus cifras en el código.
- Marcas: `[CONFIGURABLE]` = usa el valor por defecto de §8 salvo que el usuario elija otro. `[SUPUESTO]` = decisión del ejemplo; confírmala. `[PREGUNTAR]` = decisión del usuario; nunca la supongas. `[PLATAFORMA PUENTE OS]` = límite de Puente OS; en otro stack puedes ignorarlo.

## 1. Objetivo y alcance

Una app web que responde cinco preguntas: (1) venta contra presupuesto y año anterior; (2) margen y unidades; (3) cada mes, semana, día y tienda; (4) para cuántos meses alcanza el inventario; (5) cómo cierra el mes y a qué cliente visitar primero.

Incluye los 9 pasos de la guía: 17 tablas, una carga nocturna, 7 vistas (Ventas, Margen y unidades, Resumen, Cierre, Inventario, Seguimiento, Documentos) y la descarga CSV.

Guía → tareas: Paso 1 = T-01 y T-02; Paso N (2 a 9) = T-(N+1).

Fuera de alcance: agentes de IA; escribir en el ERP; emitir documentos tributarios.

## 2. Plataforma

**Ruta A · Puente OS.** Puente OS es la plataforma que construye los sistemas que operan tu negocio. La app se construye en Puente Studio (documentación: https://docs.puente.xyz/llms.txt). Si el entorno tiene la skill o el plugin `puente-os`, úsalo.

**Ruta B · cualquier stack**, con esta equivalencia:

| Bloque de Puente OS | Equivalente genérico |
|---|---|
| App | Frontend web (React + TypeScript) |
| Tabla | Tabla en una base de datos relacional |
| Workflow programado | Tarea programada |
| Workflow con ruta fija | Endpoint del servidor o función serverless |
| Integración | Cliente del sistema externo, del lado del servidor |

**Límites [PLATAFORMA PUENTE OS]:**
- Una consulta devuelve hasta 5.000 filas por página. Pagina ordenando por todas las columnas del agrupado más un desempate estable.
- Sin claves foráneas: los cruces son por texto exacto (R-32).
- Una tabla no se borra: agrega columnas a la existente en vez de crear una versión nueva.
- La consulta agregada solo suma y cuenta; no multiplica columnas. Guarda precalculado todo producto (`lista_total`, `margen`, `costo_stock`).
- Una tabla con clave no actualiza filas: guardar = borrar la fila anterior + insertar la nueva, en un workflow con ruta fija. Después invalida la caché de lectura de la app.

## 3. Modelo de datos — 17 tablas: 6 universales [U] y 11 opcionales [O]

Tipos: `texto`, `entero`, `número` (moneda local, sin decimales, sin impuesto salvo que se indique), `fecha` (AAAA-MM-DD). Los nombres (canal, tienda, vendedor, categoría, marca, familia, almacén, cliente) pasan por `equivalencias_nombres` (R-32). Toda tabla con período guarda `ano`, `mes` (y `dia`, `semana` si aplica) como enteros derivados de `fecha`.

### 3.1 ventas_diarias [U]
Grano: día × canal × tienda × vendedor × categoría × marca × familia. Clave: esas 7 columnas.

| campo | tipo | ejemplo | regla |
|---|---|---|---|
| fecha | fecha | 2026-10-14 | día de la venta |
| ano, mes, dia | entero | 2026, 10, 14 | de `fecha` |
| semana | entero | 42 | semana ISO de `fecha` |
| canal | texto | Tiendas propias | |
| tienda | texto | Tienda Norte | |
| vendedor | texto | V-07 | vacío permitido en e-commerce |
| categoria, marca, familia | texto | Calzado, Marca A, Running | |
| venta_neta | número | 125000 | sin impuesto, neta de anulaciones y notas de crédito; puede ser negativa |
| costo_total | número | 80000 | costo de lo vendido |
| unidades | entero | 3 | negativo en devoluciones |

### 3.2 ventas_producto [U]
Grano: producto × día (agrega `canal` y `tienda` si el usuario los necesita en Inventario). Campos: `sku` (texto, SKU-1003), `categoria`, `marca`, `familia`, `fecha`, `ano`, `mes`, `venta_neta`, `costo_total`, `unidades`. Alimenta los rankings (R-35) y la cobertura por producto.

### 3.3 presupuesto_mensual [U]
Grano: canal × tienda × categoría × marca × año × mes. Campos: `ano`, `mes`, `canal`, `tienda`, `categoria`, `marca` (texto), `venta_ppto`, `costo_ppto` (número), `unidades_ppto` (entero). Siempre con `ano`: sin año, el presupuesto sirve para un solo año. Se carga desde una hoja de cálculo.

### 3.4 stock_actual [U]
Grano: producto. Campos: `sku`, `categoria`, `marca`, `familia` (texto), `stock` (entero), `costo_stock` (número = stock × costo unitario, precalculado), `venta_90d` (entero, unidades vendidas en 90 días).

### 3.5 foto_cierre [U]
Grano: año × mes × producto × almacén × canal. Campos: `ano`, `mes`, `sku`, `almacen`, `canal` (texto; vacío = stock sin canal; un almacén compartido genera una fila por canal con su parte según R-20), `unidades` (entero), `valor_stock` (número, a costo). Se escribe el último día de cada mes y no se reescribe salvo que cambien movimientos de ese mes.

### 3.6 equivalencias_nombres [U]
Grano: campo × origen. Campos: `campo` (texto: canal, tienda, marca…), `origen` (texto como llega: "TDA NORTE"), `canonico` (texto oficial: "Tienda Norte"). Todas las cargas la leen.

### 3.7 presupuesto_producto [O]
Grano: producto × año × mes. Campos: `sku`, `ano`, `mes`, `venta_ppto`, `costo_ppto`, `unidades_ppto`.

### 3.8 presupuesto_diario [O]
Grano: canal × tienda × año × mes × día. Campos: `canal`, `tienda`, `ano`, `mes`, `dia`, `venta_ppto`, `costo_ppto`. Las unidades no existen por día: se prorratean (R-14).

### 3.9 tiendas_comparables [O]
Grano: tienda × año. Campos: `tienda`, `ano`, `m01` … `m12` (texto: "SSS" o vacío). Se carga desde una hoja de cálculo.

### 3.10 boletas_dia [O]
Grano: día × canal × tienda. Campos: `canal`, `tienda`, `fecha`, `ano`, `mes`, `dia`, `boletas` (entero, documentos de venta al consumidor).

### 3.11 trafico_mensual [O]
Grano: tienda × mes. Campos: `tienda`, `ano`, `mes`, `entradas` (entero, personas contadas). Solo tiendas con contador.

### 3.12 stock_almacen_canal [O]
Grano: producto × almacén × canal. Campos: `sku`, `almacen`, `canal`, `stock`, `costo_stock`. Solo para la cobertura (R-20): repite el almacén compartido en cada canal, así que nunca se suma para mostrar stock.

### 3.13 maestro_articulos [O]
Grano: producto. Campos: `sku`, `descripcion`, `categoria`, `marca`, `familia`, `precio_lista` (número, con impuesto), `costo_unitario` (número) y una columna entera por almacén (`alm_bodega_central`, `alm_tienda_norte`…). Alimenta el panel de stock por almacén y su descarga.

### 3.14 pedidos_abiertos [O]
Grano: línea de pedido. Campos: `doc_num` (texto), `cliente`, `canal`, `marca` (texto), `ano`, `mes` (entero, mes de entrega comprometido), `monto` (número, neto).

### 3.15 cliente_marca_mes [O]
Grano: cliente × marca × año × mes. Campos: `cliente`, `marca`, `ano`, `mes`, `venta_neta` (número), `meta` (número, meta anual del cliente y marca, repetida en cada mes).

### 3.16 documentos_venta [O]
Grano: línea de documento. Solo los canales de `canales_documentos` (§8). Campos: `folio` (entero), `fecha`, `canal`, `tienda`, `sku`, `descripcion`, `cantidad` (entero), `precio_lista` (número, unitario con impuesto), `lista_total` (= precio_lista × cantidad, precalculado), `venta_neta`, `costo`, `margen` (= venta_neta − costo, precalculado).

### 3.17 captura_manual [O]
Grano: vista × nombre × año × mes. Clave: esas 4 columnas. Campos: `vista` (texto: "seguimiento"), `nombre` (texto: canal o cliente), `ano`, `mes`, `valor` (número, el Empuje), `usuario` (texto), `actualizado` (fecha y hora).

## 4. Reglas de negocio

Redondeo: montos al peso; porcentajes y puntos a 1 decimal; MOI y MOS a 1 decimal. Se redondea solo al mostrar. "--" significa sin base.

**Período y comparaciones**
- R-01 Variación % = (actual ÷ base − 1) × 100. Base 0 o ausente → "--".
- R-02 Una sola función `periodo(filtro)` decide desde y hasta para venta, año anterior y presupuesto. Por qué: calculado aparte, un gráfico miraba un día y otro siete.
- R-03 Año en curso: la venta llega hasta ayer (`hoy − 1` en `zona_horaria`). El año anterior se corta en la misma fecha del año anterior (29-feb → 28-feb). Sin filtro de mes: 1-ene → ayer. Con filtro del mes en curso: día 1 → ayer, en los dos años. Por qué: contra el año completo, el 15-oct muestra una caída falsa.
- R-04 Presupuesto: sin filtro de mes = anual completo; con filtro de mes = mes completo. [CONFIGURABLE: `presupuesto_con_filtro_mes`]
- R-05 Año sin presupuesto, o vendedor o tienda sin presupuesto → comparaciones con presupuesto en "--".
- R-06 Tiendas comparables: con el filtro activo, venta, año anterior y presupuesto usan solo las filas (tienda, mes) marcadas "SSS" en `tiendas_comparables` del año actual. Si el filtro deja la vista en cero, se apaga y la pantalla lo avisa.
- R-07 Margen % = (Σ venta − Σ costo) ÷ Σ venta × 100. Contribución = Σ venta − Σ costo. Diferencia de margen = margen actual − margen base, en puntos ("pts").
- R-08 Todo porcentaje de un grupo se recalcula desde sus sumas. Nunca promediar porcentajes.

**Resumen por período**
- R-09 Ticket = venta ÷ boletas. UPT = unidades ÷ boletas. Solo filas de tiendas con boletas. Venta o unidades netas ≤ 0 → vacío.
- R-10 Conversión % = boletas ÷ entradas × 100, con boletas y entradas de las mismas tiendas y meses (solo tiendas con contador). Solo en grano mensual; en semana y día se oculta. Sin contador → "--".
- R-11 Filtro de categoría, marca o vendedor → ticket, UPT y conversión se ocultan.
- R-12 Vistas por semana y por día: año anterior = día equivalente (fecha − 364 días). Mes y tarjetas anuales: calendario (R-03). [CONFIGURABLE: `anio_anterior`]
- R-13 Períodos futuros: muestran presupuesto y año anterior; venta y variación vacías. Mes en curso contra presupuesto: "en curso".
- R-14 Presupuesto por día: usa `presupuesto_diario` si existe; si no, presupuesto del mes ÷ días del mes. Las unidades siempre se prorratean. [CONFIGURABLE: `presupuesto_diario`]

**Cierre y cobertura**
- R-15 Meta del cierre = presupuesto del mes completo. Variación contra meta con R-01.
- R-16 MOI del cierre = valor_stock de `foto_cierre` (año, mes) ÷ costo de venta del mes.
- R-17 MOS = valor del stock ÷ promedio mensual del costo presupuestado de los meses siguientes, hasta `ventana_cobertura_meses`, solo meses con presupuesto. Noviembre → solo diciembre. Sin meses → vacío.
- R-18 Semáforo de cobertura sobre el valor sin redondear: < 1 rojo; < 3 ámbar; ≥ 3 verde. Vacío → neutro.
- R-19 MOI de inventario (hoy) = costo_stock ÷ promedio mensual del costo de venta de los `ventana_cobertura_meses` meses cerrados anteriores.
- R-20 Almacén compartido: la pantalla muestra su stock completo. Para MOI y MOS por canal, parte del canal = costo de venta del canal ÷ costo de venta de todos los canales del almacén, en los últimos 12 meses [SUPUESTO]. [CONFIGURABLE: `base_reparto_almacen`]
- R-21 Stock sin canal: fuera de la tabla por canal, dentro del total de la empresa.

**Seguimiento**
- R-22 Cierre proyectado = venta real del mes + pedidos abiertos del mes + Empuje. Los totales suman sus filas.
- R-23 Cumplimiento del mes % = cierre proyectado ÷ meta del mes × 100.
- R-24 Por cliente y marca: meta mensual = meta anual ÷ 12 [CONFIGURABLE: `meta_mensual`]; meta acumulada = meta mensual × mes en curso; cuánto venderle = máx(0, meta acumulada − venta de los meses cerrados); cumplimiento % = venta de los meses cerrados ÷ (meta mensual × meses cerrados) × 100; prioridad = 1 + clientes de la misma marca con mayor cuánto venderle.
- R-25 Empuje: una fila por (vista, nombre, año, mes). Guardar reemplaza; vacío o 0 borra la fila. [CONFIGURABLE: `captura_manual`]

**Documentos y descarga**
- R-26 Búsqueda: solo dígitos → folio exacto; si no existe, tramo de código de producto; otro texto → contiene, en descripción o código. Hasta 100 líneas por página. Folio inexistente → "No existe el folio N. Revisa el número impreso en la boleta."
- R-27 Pagado = venta_neta × (1 + impuesto). Descuento = lista_total − pagado; descuento % = descuento ÷ lista_total × 100. Margen % = margen ÷ venta_neta × 100. Precio neto unitario = venta_neta ÷ cantidad.
- R-28 CSV: un registro por fila, sin subtotales ni porcentajes; fila 1 = encabezados, sin título ni notas; separador `;`; coma decimal; UTF-8 con BOM; un texto que empieza con `=`, `+`, `-` o `@` lleva un apóstrofo delante; tope de filas por descarga.
- R-29 Control de cuadre: antes de entregar el CSV, suma `venta_neta` del archivo y compárala con el total de la pantalla. |diferencia| > `tolerancia_cuadre` → no se entrega y se muestra "La descarga no cuadra con la pantalla y no se entregó." En el detalle por producto, un sku repetido también detiene la descarga.

**Carga nocturna**
- R-30 Ventana = (hoy − `ventana_carga_dias`) → ayer. Si hay documentos creados o anulados desde la última carga con fecha anterior a la ventana, la ventana se amplía hasta el más antiguo, sin pasar de `tope_dias_correccion`.
- R-31 Por cada tabla destino: lee lo existente en la ventana, compara por contenido, borra lo que sobra e inserta lo que falta. Filas iguales no se reescriben. Si la fuente devuelve 0 filas para una tabla, la tabla conserva sus filas. Cada tabla opcional se carga en un bloque propio: su falla no detiene las demás. Al final, un resumen con filas insertadas y borradas por tabla.
- R-32 Antes de escribir: aplica `exclusiones` y traduce nombres con `equivalencias_nombres`. Un nombre sin equivalencia se registra en el resumen. Presupuesto y venta se cruzan por canal, tienda y marca en texto exacto.
- R-33 El encabezado de la app muestra la última carga y el último día con venta: "Carga nocturna: 15-oct-2026 03:00 · venta hasta el 14-oct".
- R-35 Rankings: los 10 que más contribuyen y los 10 más vendidos salen de `ventas_producto`. Si ignoran filtros de canal, tienda, vendedor, semana o día, la pantalla lo dice.

## 5. Orden de construcción

- T-01 Las 17 tablas (o las que el usuario elija: siempre las 6 universales). Depende de: —. Listo cuando: CA-01.
- T-02 Carga nocturna (R-30 a R-33). Depende de: T-01. Listo cuando: CA-02, CA-03, CA-04.
- T-03 Vista Ventas: filtros (año, mes, canal, comparables), 4 tarjetas (ingreso neto, unidades, contribución, margen %) con variación contra año anterior y presupuesto, gráfico mensual (venta, año anterior, presupuesto), tablas por canal y por categoría. Depende de: T-02. Listo cuando: CA-05 a CA-08.
- T-04 Vista Margen y unidades: rankings de 10 con color de margen. Depende de: T-03. Listo cuando: CA-09, CA-10.
- T-05 Vista Resumen: selector de grano (mes, semana, día) y de filas (período o tienda); matriz con venta, año anterior, presupuesto, unidades, ticket, UPT y conversión. Depende de: T-03. Listo cuando: CA-11 a CA-13.
- T-06 Vista Cierre: selector de mes cerrado, filtro de marca, tabla por canal (meta, venta, variación, stock a costo, MOI, MOS). Depende de: T-02 (foto de cierre). Listo cuando: CA-14, CA-15.
- T-07 Vista Inventario: árbol categoría ▸ marca ▸ familia ▸ producto (los productos se piden al abrir la rama), buscador y panel de stock por almacén, descarga del maestro. Depende de: T-06. Listo cuando: CA-16 a CA-18.
- T-08 Vista Seguimiento: por canal (meta, real del mes, pedidos abiertos, Empuje editable, cierre proyectado, cumplimiento) y por cliente y marca (meta anual, real de meses cerrados, cumplimiento, cuánto venderle, prioridad). Workflow de guardado del Empuje. Depende de: T-03. Listo cuando: CA-19 a CA-21.
- T-09 Vista Documentos: búsqueda, vistas Documento, Detalle y Producto, totales de la selección, filtro de margen negativo, ventana con el documento completo. Depende de: T-02. Listo cuando: CA-22, CA-23.
- T-10 Descarga CSV en las vistas que la usen, con control de cuadre. Opcional sin probar: workflow semanal que envía el informe por correo (Gmail) [PREGUNTAR: destinatarios y día]. Depende de: T-03. Listo cuando: CA-24.

## 6. Criterios de aceptación

Dado / Cuando / Entonces. Cifras de §7. Hoy = 2026-10-15.

- CA-01 Dado T-01, entonces existen las tablas elegidas con todos sus campos de §3, y cada tabla de presupuesto tiene `ano`. Con todas: 17 tablas (6 [U] + 11 [O]).
- CA-02 Dado §7.2, cuando se carga septiembre de 2026, entonces Σ venta_neta = 63.360.715, exacto al peso. Invariante: para todo mes cerrado, Σ en la tabla = Σ en la fuente.
- CA-03 Dado hoy = 15-oct y `ventana_carga_dias` = 30 (15-sep → 14-oct), cuando ayer se anuló un documento del 2-sep, entonces la carga relee desde el 2-sep. Con una anulación anterior a `tope_dias_correccion`, la ventana se detiene en el tope.
- CA-04 Dado que la fuente devuelve 0 filas para una tabla, entonces la tabla conserva sus filas. Dado que falla `trafico_mensual`, entonces `ventas_diarias` igual queda escrita. Una segunda carga sin cambios en la fuente inserta y borra 0 filas.
- CA-05 Dado §7.2 sin filtros, entonces la tarjeta de ingreso muestra 606.245.052 ("$606,2 M"), +19,9 % contra el año anterior (base 505.606.582) y −24,2 % contra el presupuesto (799.359.064). Nunca −13,1 % (base 2025 completa = 697.889.229). Unidades 28.377, +20,0 %. Contribución 262.313.125. Margen 43,3 %, +0,3 pts.
- CA-06 Dado el año 2025 (sin presupuesto), entonces toda comparación con presupuesto muestra "--".
- CA-07 Dado filtro mes = octubre 2026, entonces ingreso 30.706.552, +8,6 % contra 28.273.215 (oct-2025 del 1 al 14), y −54,1 % contra el presupuesto del mes completo (66.889.165).
- CA-08 Dado filtro de tiendas comparables (sin Tienda Sur), entonces venta 531.290.679, +12,8 % contra 471.142.121. Invariante: venta, año anterior y presupuesto usan el mismo conjunto de tiendas.
- CA-09 Dado tienda A (venta 100, costo 50) y tienda B (venta 900, costo 720), entonces margen total 23,0 %, nunca 35,0 %. Dado Calzado (venta 272.128.995, contribución 105.135.755), entonces margen 38,6 %.
- CA-10 Invariante: Σ contribución por categoría = tarjeta de contribución (105.135.755 + 99.161.204 + 58.016.166 = 262.313.125). Lo mismo por canal. Cambiar un filtro dos veces seguidas muestra el resultado del último.
- CA-11 Dado Tienda Norte ene–oct 2026 (venta 137.298.688, boletas 4.273, unidades 6.426, entradas 20.197), entonces ticket 32.132, UPT 1,5, conversión 21,2 %.
- CA-12 Dado vista por día, 2026-10-14 (miércoles) se compara con 2025-10-15 (miércoles). Invariante: en la vista por tienda, Σ venta de las filas = total del tramo.
- CA-13 Dado una fila con venta neta ≤ 0, entonces ticket y UPT vacíos. Dado filtro de categoría, entonces ticket, UPT y conversión ocultos. Dado grano semana, conversión oculta. Dado noviembre 2026, venta vacía y presupuesto visible.
- CA-14 Dado cierre de septiembre 2026, Tiendas propias (meta 34.144.191, venta 34.797.980, valor_stock 90.278.808, costo de venta del mes 18.670.008, costo presupuestado oct–dic 68.918.389), entonces variación +1,9 %, MOI 4,8 y MOS 3,9. Dado cierre de noviembre, MOS usa solo diciembre; de diciembre, MOS vacío.
- CA-15 Dado MOI 0,9 / 2,9 / 2,99 / 3,0, entonces rojo / ámbar / ámbar / verde. Invariante: Σ stock por canal + stock sin canal = stock total de la empresa.
- CA-16 Dado Calzado (costo_stock 110.942.400; costo de venta jul–sep 56.956.192; costo presupuestado nov–dic 48.421.798), entonces MOI 5,8 y MOS 4,6.
- CA-17 Dado un almacén con stock 600.000 que atiende al Canal A (costo de venta 300.000) y al Canal B (100.000), entonces la parte de A es 450.000 y la de B 150.000; al filtrar por canal, la pantalla muestra 600.000. Invariante: Σ partes = stock del almacén.
- CA-18 Invariante: Σ costo_stock de las categorías = stock total (110.942.400 + 39.344.000 + 18.270.000 = 168.556.400). Dado SKU-1003, el panel muestra 426 / 32 / 29 / 19 = 506 unidades.
- CA-19 Dado Mayorista octubre (meta 19.312.047, real 8.696.894, pedidos abiertos 9.800.000), cuando se teclea Empuje 4.500.000, entonces cierre proyectado 22.996.894 y cumplimiento 119,1 %.
- CA-20 Dado Cliente B · Marca A (meta anual 51.774.000; venta ene–sep 32.703.024; mes en curso 10), entonces cuánto venderle 10.441.976, cumplimiento 84,2 % y prioridad 1 si ningún cliente de Marca A tiene un cuánto venderle mayor. Dado venta cerrada > meta acumulada, cuánto venderle = 0.
- CA-21 Cuando se guarda un Empuje y se recarga la página, el valor sigue y existe una sola fila en `captura_manual`. Cuando se borra, la fila desaparece.
- CA-22 Dado folio 4821 (cantidad 2, lista_total 23.800, venta_neta 17.000, costo 12.000, impuesto 0,19), entonces pagado 20.230, descuento 3.570 (15,0 %), margen 29,4 %, precio neto unitario 8.500.
- CA-23 Dado "4821", aparece el folio. Dado "9999", aparece el mensaje de R-26. Dado "Mochilas", aparecen líneas por descripción. Ninguna página trae más de 100 líneas.
- CA-24 Dado la descarga de Ventas 2026 sin filtros, entonces el CSV trae 1 fila de encabezados + las filas de detalle, y Σ venta_neta = 606.245.052. Dado un archivo que suma 606.235.052, no se entrega. Una celda "=SUMA(A1)" se escribe "'=SUMA(A1)". 1234,5 se escribe "1234,5".
- CA-final Recorrido completo con §7: cada vista coincide con §7.4.

## 7. Datos de ejemplo — Empresa Demo SpA (ficticios)

### 7.1 Estructura
- Hoy = 2026-10-15; la carga corrió a las 03:00 y hay venta hasta el 14-oct. Años: 2025 y 2026. Presupuesto solo para 2026. Moneda: pesos chilenos, IVA 19 %.
- Canales (3): Tiendas propias, E-commerce, Mayorista.
- Tiendas (5): Tienda Norte, Tienda Centro, Tienda Sur (Tiendas propias); Sitio web (E-commerce); Mayorista (Mayorista). Tienda Sur abrió en junio de 2025: no es comparable en 2026.
- Categorías (3) y familias: Calzado (Running, Urbano), Vestuario (Poleras, Chaquetas), Accesorios (Mochilas, Gorros). Marcas (3): Marca A, Marca B, Marca C.
- Productos: 36 (categoría × marca × familia × modelo Base o Pro), SKU-1001 a SKU-1036. Almacenes (4): Bodega central, Tienda Norte, Tienda Centro, Tienda Sur.
- Contador de personas: solo las tres tiendas físicas. Clientes mayoristas: Cliente A, B, C y D, con meta por marca.

### 7.2 Totales mensuales de la empresa

venta_neta | costo_total | unidades. Octubre 2026 cubre del 1 al 14. Presupuesto 2026: venta_ppto | costo_ppto | unidades_ppto.

| mes | 2025 | 2026 | presupuesto 2026 |
|---|---|---|---|
| 1 | 43.837.528 · 25.314.898 · 2.042 | 58.197.646 · 32.986.869 · 2.730 | 56.528.430 · 32.096.780 · 2.653 |
| 2 | 40.239.079 · 23.058.326 · 1.889 | 52.373.972 · 29.750.731 · 2.446 | 50.652.441 · 28.787.851 · 2.380 |
| 3 | 48.902.639 · 28.027.386 · 2.278 | 63.133.998 · 35.647.287 · 2.976 | 62.686.616 · 35.661.860 · 2.928 |
| 4 | 47.423.827 · 27.189.011 · 2.231 | 61.328.214 · 34.851.331 · 2.889 | 59.522.705 · 33.834.098 · 2.795 |
| 5 | 50.959.446 · 29.101.358 · 2.401 | 65.667.234 · 36.961.786 · 3.070 | 64.393.398 · 36.483.079 · 2.984 |
| 6 | 62.420.295 · 35.497.930 · 2.944 | 69.819.430 · 39.710.364 · 3.241 | 67.848.098 · 38.518.262 · 3.150 |
| 7 | 66.425.237 · 37.717.841 · 3.088 | 74.010.966 · 42.042.037 · 3.474 | 71.433.540 · 40.470.427 · 3.368 |
| 8 | 59.577.989 · 33.901.235 · 2.776 | 67.646.325 · 38.457.579 · 3.140 | 65.647.647 · 37.391.081 · 3.023 |
| 9 | 57.547.327 · 32.651.490 · 2.675 | 63.360.715 · 36.039.381 · 2.965 | 61.976.081 · 35.198.587 · 2.858 |
| 10 | 62.604.976 · 35.594.034 · 2.919 | 30.706.552 · 17.484.562 · 1.446 | 66.889.165 · 37.952.015 · 3.169 |
| 11 | 69.166.481 · 39.292.463 · 3.222 | — | 75.444.770 · 42.946.514 · 3.468 |
| 12 | 88.784.405 · 50.570.256 · 4.130 | — | 96.336.173 · 54.610.794 · 4.511 |

Octubre 2025 del 1 al 14: 28.273.215 · 16.074.725 · 1.318. Año anterior al 14-oct: 505.606.582 · 288.534.200 · 23.642.

### 7.3 Casos mínimos
- Dos tiendas: A venta 100, costo 50; B venta 900, costo 720.
- Almacén compartido: stock 600.000; Canal A costo de venta 300.000; Canal B 100.000.
- Folio 4821, 2026-10-14, Tienda Norte, SKU-1037 Mochilas A Base: cantidad 2, lista_total 23.800, venta_neta 17.000, costo 12.000.
- Seguimiento octubre por canal (meta · real al 14 · pedidos abiertos): Tiendas propias 35.580.947 · 16.595.661 · 0; E-commerce 11.996.171 · 5.413.997 · 2.150.000; Mayorista 19.312.047 · 8.696.894 · 9.800.000.
- Cliente B · Marca A: meta anual 51.774.000; venta ene–sep 32.703.024. Cliente A · Marca A: meta anual 44.508.000; venta ene–sep 28.060.858.

### 7.4 Esperado

```json
{
  "hoy": "2026-10-15",
  "ventas": {"venta": 606245052, "anio_anterior": 505606582, "variacion_pct": 19.9, "anio_anterior_completo": 697889229, "variacion_falsa_pct": -13.1, "presupuesto_anual": 799359064, "vs_presupuesto_pct": -24.2, "unidades": 28377, "contribucion": 262313125, "margen_pct": 43.3, "margen_vs_aa_pts": 0.3},
  "octubre": {"venta": 30706552, "anio_anterior": 28273215, "variacion_pct": 8.6, "vs_presupuesto_mes_pct": -54.1},
  "comparables": {"venta": 531290679, "anio_anterior": 471142121, "variacion_pct": 12.8},
  "margen": {"dos_tiendas_pct": 23.0, "calzado_pct": 38.6},
  "resumen": {"tienda_norte": {"ticket": 32132, "upt": 1.5, "conversion_pct": 21.2}},
  "cierre_sep_tiendas_propias": {"variacion_meta_pct": 1.9, "moi": 4.8, "mos": 3.9},
  "inventario": {"calzado": {"moi": 5.8, "mos": 4.6}, "stock_total": 168556400},
  "seguimiento": {"mayorista_cierre": 22996894, "mayorista_cumplimiento_pct": 119.1, "cliente_b_marca_a": {"cuanto_venderle": 10441976, "cumplimiento_pct": 84.2, "prioridad": 1}},
  "documento_4821": {"pagado": 20230, "descuento": 3570, "descuento_pct": 15.0, "margen_pct": 29.4},
  "csv_ventas_2026": {"suma_venta": 606245052}
}
```

## 8. Configuración

| clave | opciones | por defecto |
|---|---|---|
| ventana_carga_dias | 7, 30, 60 | 30 |
| tope_dias_correccion | días | 90 [SUPUESTO] |
| hora_carga | hora local | 03:00 [PREGUNTAR] |
| zona_horaria | zona IANA | America/Santiago [PREGUNTAR: país de la empresa] |
| exclusiones | arriendos, activos fijos, servicios, intercompañía | ninguna [PREGUNTAR] |
| anio_anterior (semana y día) | dia_equivalente, misma_fecha | dia_equivalente |
| presupuesto_con_filtro_mes | mes_completo, a_la_fecha | mes_completo |
| presupuesto_diario | curva, parejo | curva si existe la tabla; si no, parejo |
| ventana_cobertura_meses | 3, 6, 12 | 3 |
| cobertura_en | costo, unidades | costo |
| base_reparto_almacen | costo_venta, unidades, presupuesto | costo_venta, 12 meses |
| semaforo_cobertura | cortes | < 1 rojo, < 3 ámbar, ≥ 3 verde |
| semaforo_margen | cortes | < 35 rojo, < 45 ámbar, ≥ 45 verde |
| top_n | entero | 10 |
| captura_manual | reemplazo, historial | reemplazo |
| meta_mensual | anual_12, mes_a_mes | anual_12 |
| cierre_incluye_pedidos | sí, no | sí |
| trafico | con_contador, sin_contador | con_contador si existe la tabla |
| documento | boleta, factura, CFDI | boleta y factura [PREGUNTAR] |
| impuesto | 0,16; 0,18; 0,19 | 0,19 [PREGUNTAR: país] |
| canales_documentos | lista de canales | Tiendas propias |
| tolerancia_cuadre | pesos | 1 |
| max_filas_descarga | entero | 50.000 [SUPUESTO] |

## 9. Preguntas para el usuario

Las 11 de la guía, en el mismo orden. Hazlas una por vez, en lenguaje de negocio.

1. ¿Qué sistema guarda tus ventas, costos y stock (por ejemplo SAP Business One, Defontana, Odoo, Softland) y cómo se leen sus datos? Sin valor por defecto: pregunta siempre.
2. ¿Cuáles son tus canales y tiendas, y cómo aparecen escritos en el sistema? → `equivalencias_nombres`.
3. ¿Qué ventas dejas fuera del reporte? → `exclusiones` (por defecto: ninguna).
4. ¿Tu presupuesto es mensual o diario, y por tienda, categoría y marca? → `presupuesto_diario`.
5. ¿Comparas con la misma fecha o con el mismo día de la semana del año anterior? → `anio_anterior` (por defecto: día equivalente).
6. ¿Para cuántos meses de venta quieres tener stock, y lo mides en costo o en unidades? → `ventana_cobertura_meses`, `cobertura_en` (3, costo).
7. ¿Algún almacén abastece a varios canales? ¿Cómo repartes su stock? → `base_reparto_almacen` (costo de venta).
8. ¿Qué documento respalda tu venta y qué impuesto lleva? ¿En qué país operas? → `documento`, `impuesto`, `zona_horaria`.
9. ¿Qué cifra proyecta hoy alguien a mano? ¿Necesitas historial de cambios? → `captura_manual` (reemplazo).
10. ¿A qué hora nadie usa tu sistema de gestión? → `hora_carga` (03:00).
11. ¿Tienes contador de personas en tus tiendas? → `trafico`.

## 10. Requisitos de construcción sobre credenciales

- Las credenciales del sistema de gestión, del contador y del correo viven en la configuración del workflow o en variables de entorno del servidor; nunca en el código de la app ni en el repositorio.
- La app solo lee tablas. La única escritura desde la pantalla (el Empuje) pasa por un workflow con ruta fija.
- Pide al usuario un acceso de solo lectura al sistema de gestión; nunca su contraseña personal.
- Pregunta antes de crear, rotar o compartir cualquier credencial, y nunca la escribas en registros ni mensajes.

## 11. Glosario

- **ERP / sistema de gestión:** software donde la empresa registra ventas, compras y stock.
- **Venta neta:** sin impuesto, neta de anulaciones y notas de crédito. **Contribución:** venta neta − costo.
- **Día equivalente:** fecha − 364 días. **SSS:** tiendas comparables.
- **Ticket, UPT, conversión:** R-09 y R-10. **MOI, MOS:** R-16, R-17 y R-19.
- **Boleta:** comprobante al consumidor (Chile, Perú); en México, ticket o CFDI. **Folio:** número impreso del documento.
- **Foto de cierre:** stock al último día de cada mes. **Almacén compartido:** abastece a más de un canal (en Chile, bodega).
- **Empuje:** venta estimada que una persona suma al mes. **Cierre proyectado:** R-22.
- **Días con correcciones:** fechas anteriores a la ventana con documentos creados o anulados después (R-30).
- **YTD:** acumulado desde enero hasta la fecha.
