@fullqueso/mcp-bc-gastos 1.14.2 → 1.19.0

package/tools/ventas/sales-store-comparison.js

@@ -0,0 +1,192 @@
+import { getDateRange, formatCurrency, formatPercent } from '../../utils/date-helper.js';
+import { aggregateByField, calculateSummary, topN } from '../../utils/sales-aggregation.js';
+import { generateStoreInsights } from '../../utils/sales-insights.js';
+import { logger } from '../../utils/logger.js';
+
+export const salesStoreComparisonTool = {
+  name: 'compare_sales_by_store',
+  description:
+    'Comparación de rendimiento de VENTAS entre las tiendas de Full Queso (FQ01 Chacao, FQ28 Marqués, FQ88 Candelaria). Identifica fortalezas, oportunidades y diferencias en ventas entre tiendas. Montos en USD. (Para comparar GASTOS, usar compare_stores.)',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      period: {
+        type: 'string',
+        enum: ['last_7_days', 'last_30_days', 'this_month', 'last_month', 'specific_month', 'custom'],
+        description: 'Periodo de comparación. Usar "specific_month" con el parámetro month para un mes específico.',
+        default: 'last_30_days',
+      },
+      month: {
+        type: 'string',
+        description: 'Mes específico en formato YYYY-MM (ej: "2026-01" para enero 2026). Usar con period="specific_month".',
+      },
+      start_date: {
+        type: 'string',
+        description: 'Fecha inicio (YYYY-MM-DD). Requerido si period=custom',
+      },
+      end_date: {
+        type: 'string',
+        description: 'Fecha fin (YYYY-MM-DD). Requerido si period=custom',
+      },
+      metrics: {
+        type: 'array',
+        items: {
+          type: 'string',
+          enum: ['revenue', 'transactions', 'avg_ticket', 'top_products', 'all'],
+        },
+        description: 'Métricas a comparar',
+        default: ['all'],
+      },
+    },
+  },
+};
+
+export async function handleSalesStoreComparison(bcClient, args) {
+  const period = args.period || 'last_30_days';
+  const requestedMetrics = args.metrics || ['all'];
+  const showAll = requestedMetrics.includes('all');
+
+  const dateRange = getDateRange(period, args.start_date, args.end_date, args.month);
+
+  logger.info(`Sales store comparison: ${dateRange.start} to ${dateRange.end}`);
+
+  const allStoresData = await bcClient.getAllSalesStoreData(['all'], dateRange.start, dateRange.end);
+
+  const firstStoreData = Object.values(allStoresData)[0];
+  const exchangeRate = firstStoreData?.exchangeRate || null;
+
+  const comparison = {};
+  const storesSummaries = {};
+
+  for (const [code, data] of Object.entries(allStoresData)) {
+    const summary = calculateSummary(data.invoices, data.lines, exchangeRate, data.glRevenue);
+    storesSummaries[data.storeName] = { summary };
+
+    const storeResult = {
+      store_code: code,
+      store_name: data.storeName,
+    };
+
+    if (showAll || requestedMetrics.includes('revenue')) {
+      storeResult.revenue_usd = summary.total_revenue_usd;
+      storeResult.revenue_breakdown = summary.revenue_breakdown;
+      storeResult.margin_usd = summary.total_margin_usd;
+      storeResult.margin_pct = summary.margin_pct;
+      storeResult.cost_usd = summary.total_cost_usd;
+    }
+
+    if (showAll || requestedMetrics.includes('transactions')) {
+      storeResult.transactions = summary.total_transactions;
+      storeResult.total_quantity = summary.total_quantity;
+    }
+
+    if (showAll || requestedMetrics.includes('avg_ticket')) {
+      storeResult.avg_ticket_usd = summary.avg_ticket_usd;
+    }
+
+    if (showAll || requestedMetrics.includes('top_products')) {
+      const byProduct = aggregateByField(data.lines, 'displayName');
+      const storeLineRevTotal = byProduct.reduce((s, p) => s + p.revenue, 0) || 1;
+      storeResult.top_products = topN(byProduct, 'revenue', 10).map((p) => ({
+        product: p.key,
+        item_number: p.lines[0]?.itemNumber || '',
+        revenue: Math.round(p.revenue * 100) / 100,
+        revenue_pct: Math.round((p.revenue / storeLineRevTotal) * 1000) / 10,
+        quantity: p.quantity,
+        margin_pct: Math.round(p.margin_pct * 10) / 10,
+      }));
+
+      const byCategory = aggregateByField(data.lines, 'itemCategoryCode');
+      storeResult.top_categories = topN(byCategory, 'revenue', 5).map((c) => ({
+        category: c.key,
+        revenue: Math.round(c.revenue * 100) / 100,
+        quantity: c.quantity,
+      }));
+    }
+
+    if (showAll) {
+      const byDay = {};
+      for (const inv of data.invoices) {
+        const day = inv.postingDate;
+        if (!byDay[day]) byDay[day] = { date: day, transactions: 0 };
+        byDay[day].transactions += 1;
+      }
+      const dailyData = Object.values(byDay).sort((a, b) => a.date.localeCompare(b.date));
+
+      if (dailyData.length > 0) {
+        const bestDay = dailyData.reduce((best, d) => d.transactions > best.transactions ? d : best);
+        const worstDay = dailyData.reduce((worst, d) => d.transactions < worst.transactions ? d : worst);
+        storeResult.best_day = { date: bestDay.date, transactions: bestDay.transactions };
+        storeResult.worst_day = { date: worstDay.date, transactions: worstDay.transactions };
+        storeResult.avg_daily_transactions = Math.round(
+          (dailyData.reduce((s, d) => s + d.transactions, 0) / dailyData.length) * 10
+        ) / 10;
+      }
+    }
+
+    comparison[code] = storeResult;
+  }
+
+  const storeInsights = generateStoreInsights(storesSummaries, storesSummaries);
+
+  // Cross-store analysis
+  const crossInsights = [];
+  const storeEntries = Object.values(comparison);
+
+  if (storeEntries.length > 1) {
+    const revenueLeader = storeEntries.reduce((a, b) => (a.revenue_usd || 0) > (b.revenue_usd || 0) ? a : b);
+    const ticketLeader = storeEntries.reduce((a, b) => (a.avg_ticket_usd || 0) > (b.avg_ticket_usd || 0) ? a : b);
+    const transactionLeader = storeEntries.reduce((a, b) => (a.transactions || 0) > (b.transactions || 0) ? a : b);
+
+    crossInsights.push({
+      finding: `${revenueLeader.store_name} lidera en ingresos con ${formatCurrency(revenueLeader.revenue_usd, 'USD')}`,
+      reason: revenueLeader.transactions > transactionLeader.transactions * 0.9
+        ? 'Mayor volumen de transacciones'
+        : 'Ticket promedio más alto',
+      recommendation: `Las otras tiendas pueden estudiar el mix de productos de ${revenueLeader.store_name} para mejorar.`,
+    });
+
+    if (ticketLeader.store_code !== revenueLeader.store_code) {
+      crossInsights.push({
+        finding: `${ticketLeader.store_name} tiene el mejor ticket promedio (${formatCurrency(ticketLeader.avg_ticket_usd, 'USD')})`,
+        reason: 'Estrategia de upselling más efectiva o mix de productos de mayor valor',
+        recommendation: `Replicar estrategias de venta de ${ticketLeader.store_name} en las demás tiendas.`,
+      });
+    }
+
+    if (showAll || requestedMetrics.includes('top_products')) {
+      const topProductSets = {};
+      for (const [code, store] of Object.entries(comparison)) {
+        if (store.top_products) {
+          topProductSets[code] = new Set(store.top_products.slice(0, 5).map((p) => p.product));
+        }
+      }
+
+      const codes = Object.keys(topProductSets);
+      for (let i = 0; i < codes.length; i++) {
+        for (let j = i + 1; j < codes.length; j++) {
+          const set1 = topProductSets[codes[i]];
+          const set2 = topProductSets[codes[j]];
+          if (set1 && set2) {
+            const unique1 = [...set1].filter((p) => !set2.has(p));
+            const unique2 = [...set2].filter((p) => !set1.has(p));
+            if (unique1.length > 0 || unique2.length > 0) {
+              crossInsights.push({
+                finding: `Productos top diferentes entre ${comparison[codes[i]].store_name} y ${comparison[codes[j]].store_name}`,
+                reason: `${comparison[codes[i]].store_name} vende más: ${unique1.join(', ') || 'N/A'}. ${comparison[codes[j]].store_name} vende más: ${unique2.join(', ') || 'N/A'}`,
+                recommendation: 'Evaluar si productos exitosos en una tienda pueden promoverse en las otras.',
+              });
+            }
+          }
+        }
+      }
+    }
+  }
+
+  return {
+    period: { start: dateRange.start, end: dateRange.end, label: period },
+    comparison,
+    store_insights: storeInsights,
+    cross_store_insights: crossInsights,
+  };
+}

package/utils/sales-aggregation.js

@@ -0,0 +1,82 @@
+export function aggregateByField(lines, field) {
+  const map = {};
+  for (const line of lines) {
+    const key = line[field] || 'Sin categoría';
+    if (!map[key]) {
+      map[key] = { key, revenue: 0, quantity: 0, cost_ves: 0, cost_usd: 0, count: 0, lines: [] };
+    }
+    map[key].revenue += line.amount || 0;
+    map[key].quantity += line.quantity || 0;
+    map[key].cost_ves += (line.unitCostVES || 0) * (line.quantity || 0);
+    map[key].cost_usd += (line.unitCostUSD || 0) * (line.quantity || 0);
+    map[key].count += 1;
+    map[key].lines.push(line);
+  }
+
+  return Object.values(map).map((item) => ({
+    ...item,
+    cost: item.cost_ves,
+    margin: item.revenue - item.cost_ves,
+    margin_pct: item.revenue > 0 ? ((item.revenue - item.cost_ves) / item.revenue) * 100 : 0,
+  }));
+}
+
+export function aggregateByDate(lines) {
+  const map = {};
+  for (const line of lines) {
+    const date = line.postingDate || line.invoiceDate || 'unknown';
+    if (!map[date]) {
+      map[date] = { date, revenue: 0, quantity: 0, transactions: new Set() };
+    }
+    map[date].revenue += line.amount || 0;
+    map[date].quantity += line.quantity || 0;
+    if (line.documentNo) map[date].transactions.add(line.documentNo);
+  }
+
+  return Object.values(map)
+    .map((item) => ({
+      date: item.date,
+      revenue: item.revenue,
+      quantity: item.quantity,
+      transactions: item.transactions.size,
+    }))
+    .sort((a, b) => a.date.localeCompare(b.date));
+}
+
+export function calculateSummary(invoices, lines, exchangeRate = null, glRevenue = null) {
+  const totalTransactions = invoices.length;
+  const totalQuantity = lines.reduce((sum, l) => sum + (l.quantity || 0), 0);
+  const totalCostUSD = lines.reduce((sum, l) => sum + (l.unitCostUSD || 0) * (l.quantity || 0), 0);
+
+  const totalRevenueUSD = glRevenue ? glRevenue.total_usd : null;
+  const avgTicketUSD = totalRevenueUSD !== null && totalTransactions > 0
+    ? totalRevenueUSD / totalTransactions : null;
+  const totalMarginUSD = totalRevenueUSD !== null ? totalRevenueUSD - totalCostUSD : null;
+  const marginPct = totalRevenueUSD && totalRevenueUSD !== 0
+    ? (totalMarginUSD / totalRevenueUSD) * 100 : 0;
+
+  return {
+    total_revenue_usd: totalRevenueUSD !== null ? Math.round(totalRevenueUSD * 100) / 100 : null,
+    total_transactions: totalTransactions,
+    total_quantity: totalQuantity,
+    avg_ticket_usd: avgTicketUSD !== null ? Math.round(avgTicketUSD * 100) / 100 : null,
+    total_cost_usd: Math.round(totalCostUSD * 100) / 100,
+    total_margin_usd: totalMarginUSD !== null ? Math.round(totalMarginUSD * 100) / 100 : null,
+    margin_pct: Math.round(marginPct * 10) / 10,
+    revenue_breakdown: glRevenue ? glRevenue.breakdown : null,
+    currency: 'USD',
+  };
+}
+
+export function calculateGrowth(current, previous) {
+  if (!previous || previous === 0) return null;
+  return ((current - previous) / Math.abs(previous)) * 100;
+}
+
+export function topN(arr, field, n = 10) {
+  return [...arr].sort((a, b) => (b[field] || 0) - (a[field] || 0)).slice(0, n);
+}
+
+export function bottomN(arr, field, n = 10) {
+  return [...arr].sort((a, b) => (a[field] || 0) - (b[field] || 0)).slice(0, n);
+}

package/utils/sales-insights.js

@@ -0,0 +1,167 @@
+import { formatCurrency, formatPercent } from './date-helper.js';
+
+function fmtUSD(amount) {
+  if (amount === null || amount === undefined) return 'N/A';
+  return formatCurrency(amount, 'USD');
+}
+
+export function generateSalesInsights(summary, byProduct, byStore, trends) {
+  const insights = [];
+
+  if (trends.revenuGrowth !== null) {
+    if (trends.revenuGrowth > 10) {
+      insights.push({
+        type: 'success',
+        description: `Ingresos crecieron ${formatPercent(trends.revenuGrowth)} vs periodo anterior`,
+        recommendation: 'Mantener la estrategia actual. Identificar qué productos impulsan el crecimiento para reforzar.',
+        potential_impact: `Si se mantiene esta tendencia, ingresos podrían alcanzar ${fmtUSD(summary.total_revenue_usd * (1 + trends.revenuGrowth / 100))} el próximo periodo.`,
+      });
+    } else if (trends.revenuGrowth < -10) {
+      insights.push({
+        type: 'warning',
+        description: `Ingresos cayeron ${formatPercent(trends.revenuGrowth)} vs periodo anterior`,
+        recommendation: 'Revisar cambios en menú, precios o factores externos. Considerar promociones para recuperar volumen.',
+        potential_impact: `Pérdida potencial de ${fmtUSD(Math.abs(summary.total_revenue_usd * trends.revenuGrowth / 100))} si la tendencia continúa.`,
+      });
+    }
+  }
+
+  if (trends.ticketGrowth !== null && Math.abs(trends.ticketGrowth) > 5) {
+    insights.push({
+      type: trends.ticketGrowth > 0 ? 'success' : 'warning',
+      description: `Ticket promedio ${trends.ticketGrowth > 0 ? 'aumentó' : 'disminuyó'} ${formatPercent(trends.ticketGrowth)}`,
+      recommendation: trends.ticketGrowth > 0
+        ? 'Buen trabajo en upselling. Identificar qué combos o productos contribuyen.'
+        : 'Considerar estrategias de upselling: combos, sugerencias de acompañamientos, promociones por monto mínimo.',
+      potential_impact: `Ticket actual: ${fmtUSD(summary.avg_ticket_usd)}`,
+    });
+  }
+
+  if (byProduct && byProduct.length > 0) {
+    const highMargin = byProduct.filter((p) => p.margin_pct > 50).slice(0, 3);
+    if (highMargin.length > 0) {
+      insights.push({
+        type: 'opportunity',
+        description: `${highMargin.length} productos con margen >50%: ${highMargin.map((p) => p.key).join(', ')}`,
+        recommendation: 'Promover estos productos con mayor visibilidad en menú y sugerencias del personal.',
+        potential_impact: `Un aumento del 20% en ventas de estos productos podría generar ${fmtUSD(highMargin.reduce((s, p) => s + p.margin * 0.2, 0))} adicionales en margen.`,
+      });
+    }
+
+    const lowMargin = byProduct.filter((p) => p.margin_pct < 20 && p.revenue > 0);
+    if (lowMargin.length > 0) {
+      insights.push({
+        type: 'warning',
+        description: `${lowMargin.length} productos con margen <20%`,
+        recommendation: 'Revisar costos de estos productos. Considerar ajustar precios o renegociar con proveedores.',
+        potential_impact: `Mejorar margen de estos productos al 30% generaría ${fmtUSD(lowMargin.reduce((s, p) => s + p.revenue * 0.1, 0))} adicionales.`,
+      });
+    }
+  }
+
+  if (byStore && byStore.length > 1) {
+    const sorted = [...byStore].sort((a, b) => (b.total_revenue_usd || 0) - (a.total_revenue_usd || 0));
+    const best = sorted[0];
+    const worst = sorted[sorted.length - 1];
+    const bestRev = best.total_revenue_usd || 0;
+    const worstRev = worst.total_revenue_usd || 0;
+    const gap = bestRev - worstRev;
+
+    if (gap > 0 && worstRev > 0) {
+      const gapPct = (gap / worstRev) * 100;
+      if (gapPct > 30) {
+        insights.push({
+          type: 'opportunity',
+          description: `${best.store_name} supera a ${worst.store_name} por ${formatPercent(gapPct)} en ingresos`,
+          recommendation: `Analizar qué hace diferente ${best.store_name}: productos estrella, horarios pico, flujo de clientes. Replicar estrategias exitosas.`,
+          potential_impact: `Si ${worst.store_name} alcanza el 80% del nivel de ${best.store_name}, ingresos adicionales de ${fmtUSD(gap * 0.5)}.`,
+        });
+      }
+    }
+  }
+
+  if (trends.transactionGrowth !== null && trends.transactionGrowth < -15) {
+    insights.push({
+      type: 'warning',
+      description: `Número de transacciones cayó ${formatPercent(trends.transactionGrowth)}`,
+      recommendation: 'Posible problema de tráfico. Revisar horarios, promociones de atracción, delivery, redes sociales.',
+      potential_impact: `Recuperar el volumen anterior representaría ${fmtUSD(Math.abs(summary.total_transactions * trends.transactionGrowth / 100) * (summary.avg_ticket_usd || 0))} en ingresos.`,
+    });
+  }
+
+  if (insights.length === 0) {
+    insights.push({
+      type: 'success',
+      description: 'Rendimiento estable en el periodo analizado',
+      recommendation: 'Continuar monitoreando métricas clave. Buscar oportunidades de crecimiento incremental.',
+      potential_impact: 'N/A',
+    });
+  }
+
+  return insights;
+}
+
+export function generateProductInsights(product, allProducts) {
+  const insights = [];
+
+  if (product.margin_pct > 60) {
+    insights.push(`Alto margen (${product.margin_pct.toFixed(1)}%) - Priorizar en promociones`);
+  }
+  if (product.margin_pct < 15 && product.revenue > 0) {
+    insights.push(`Margen bajo (${product.margin_pct.toFixed(1)}%) - Revisar precios o costos`);
+  }
+  if (product.growth !== null && product.growth > 20) {
+    insights.push(`Crecimiento fuerte (${formatPercent(product.growth)}) - Producto en tendencia`);
+  }
+  if (product.growth !== null && product.growth < -20) {
+    insights.push(`Caída significativa (${formatPercent(product.growth)}) - Investigar causas`);
+  }
+
+  const revenueRank = allProducts.filter((p) => p.revenue > product.revenue).length + 1;
+  if (revenueRank <= 5) {
+    insights.push(`Top ${revenueRank} en ingresos`);
+  }
+
+  return insights;
+}
+
+export function generateStoreInsights(storeData, allStoresData) {
+  const insights = [];
+  const storeNames = Object.keys(allStoresData);
+
+  for (const storeName of storeNames) {
+    const store = allStoresData[storeName];
+    const others = storeNames.filter((s) => s !== storeName).map((s) => allStoresData[s]);
+
+    const avgRevenue = others.reduce((s, o) => s + (o.summary.total_revenue_usd || 0), 0) / others.length;
+    const avgTicket = others.reduce((s, o) => s + (o.summary.avg_ticket_usd || 0), 0) / others.length;
+
+    const strengths = [];
+    const opportunities = [];
+
+    const storeRev = store.summary.total_revenue_usd || 0;
+    const storeTicket = store.summary.avg_ticket_usd || 0;
+
+    if (storeRev > avgRevenue * 1.15) {
+      strengths.push(`Ingresos ${formatPercent(((storeRev - avgRevenue) / avgRevenue) * 100)} por encima del promedio`);
+    } else if (storeRev < avgRevenue * 0.85) {
+      opportunities.push(`Ingresos ${formatPercent(((storeRev - avgRevenue) / avgRevenue) * 100)} por debajo del promedio`);
+    }
+
+    if (storeTicket > avgTicket * 1.1) {
+      strengths.push(`Ticket promedio superior: ${formatCurrency(storeTicket, 'USD')} vs ${formatCurrency(avgTicket, 'USD')} promedio`);
+    } else if (storeTicket < avgTicket * 0.9) {
+      opportunities.push(`Ticket promedio bajo: ${formatCurrency(storeTicket, 'USD')} vs ${formatCurrency(avgTicket, 'USD')} promedio. Implementar estrategias de upselling.`);
+    }
+
+    if (store.summary.margin_pct > 40) {
+      strengths.push(`Margen saludable: ${store.summary.margin_pct.toFixed(1)}%`);
+    } else if (store.summary.margin_pct < 25) {
+      opportunities.push(`Margen bajo: ${store.summary.margin_pct.toFixed(1)}%. Revisar mix de productos y costos.`);
+    }
+
+    insights.push({ store: storeName, strengths, opportunities });
+  }
+
+  return insights;
+}