@fullqueso/mcp-bc-gastos 1.14.2 → 1.19.0

package/tools/inventario/item-cost-trend.js

@@ -0,0 +1,185 @@
+import { resolveStores } from '../../config/company-config.js';
+import { logger } from '../../utils/logger.js';
+
+export const itemCostTrendTool = {
+  name: 'get_item_cost_trend',
+  description:
+    'Tendencia de costo de ítems: compara weighted avg inbound cost de últimas 2 semanas vs últimas 4 semanas. Detecta si el costo está subiendo, bajando, o estable. Usa entradas de Assembly Output, Purchase, y Positive Adjustment — excluye fechas futuras.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      store: {
+        type: 'string',
+        enum: ['FQ01', 'FQ28', 'FQ88'],
+        description: 'Tienda a consultar.',
+      },
+      item_number: {
+        type: 'string',
+        description: 'Número de ítem exacto (e.g. FQ0850). Si se omite, analiza todos los ítems con movimiento reciente.',
+      },
+      item_category: {
+        type: 'string',
+        description: 'Filtrar por itemCategoryCode (e.g. TERMINADO, INSUMO).',
+      },
+      period_days: {
+        type: 'number',
+        description: 'Período base en días (default 28). El período reciente es la mitad.',
+      },
+    },
+    required: ['store'],
+  },
+};
+
+export async function handleItemCostTrend(bcClient, args) {
+  const storeParam = args.store;
+  if (!storeParam) throw new Error('Parámetro requerido: store');
+
+  const stores = resolveStores([storeParam]);
+  const store = stores[0];
+  const companyId = store.companyId;
+
+  const periodDays = args.period_days || 28;
+  const recentDays = Math.floor(periodDays / 2);
+
+  const today = new Date();
+  const todayStr = today.toISOString().split('T')[0];
+  const baseStart = new Date(today);
+  baseStart.setDate(baseStart.getDate() - periodDays);
+  const baseStartStr = baseStart.toISOString().split('T')[0];
+  const recentStart = new Date(today);
+  recentStart.setDate(recentStart.getDate() - recentDays);
+  const recentStartStr = recentStart.toISOString().split('T')[0];
+
+  const typeFilter = `(entryType eq 'Purchase' or entryType eq 'Assembly_x0020_Output' or entryType eq 'Positive_x0020_Adjmt_x002E_')`;
+
+  // Build filter for ledger entries
+  const filters = [
+    typeFilter,
+    `postingDate ge ${baseStartStr}`,
+    `postingDate le ${todayStr}`,
+  ];
+  if (args.item_number) {
+    filters.push(`itemNumber eq '${args.item_number}'`);
+  }
+
+  const url = bcClient.buildApiUrl(companyId, 'itemLedgerEntries', {
+    $filter: filters.join(' and '),
+    $select: 'itemNumber,quantity,costAmountActual,postingDate,entryType,documentNumber',
+    $orderby: 'postingDate desc',
+  });
+
+  let entries = await bcClient.apiCallAllPages(url);
+  logger.info(`${store.code}: ${entries.length} inbound entries in ${periodDays}-day window`);
+
+  // Filter by category if requested (need to fetch items first)
+  if (args.item_category) {
+    const itemUrl = bcClient.buildApiUrl(companyId, 'items', {
+      $filter: `itemCategoryCode eq '${args.item_category}'`,
+      $select: 'number',
+    });
+    const categoryItems = await bcClient.apiCallAllPages(itemUrl);
+    const categorySet = new Set(categoryItems.map((i) => i.number));
+    entries = entries.filter((e) => categorySet.has(e.itemNumber));
+    logger.info(`Filtered to ${entries.length} entries for category ${args.item_category}`);
+  }
+
+  // Group entries by item
+  const byItem = {};
+  for (const entry of entries) {
+    if (!byItem[entry.itemNumber]) byItem[entry.itemNumber] = [];
+    byItem[entry.itemNumber].push(entry);
+  }
+
+  // Calculate trend per item
+  const trends = [];
+  for (const [itemNo, itemEntries] of Object.entries(byItem)) {
+    const base = itemEntries.filter((e) => e.quantity > 0);
+    const recent = base.filter((e) => e.postingDate >= recentStartStr);
+    const older = base.filter((e) => e.postingDate < recentStartStr);
+
+    const avg4w = weightedAvg(base);
+    const avg2w = weightedAvg(recent);
+    const avgOlder = weightedAvg(older);
+
+    if (avg4w === null) continue;
+
+    let trendPct = 0;
+    let direction = 'stable';
+    if (avg2w !== null && avg4w > 0) {
+      trendPct = round2(((avg2w - avg4w) / avg4w) * 100);
+      if (trendPct > 5) direction = 'up';
+      else if (trendPct < -5) direction = 'down';
+      else direction = 'stable';
+    }
+
+    // Stale cost detection
+    const latestDate = base.length > 0 ? base[0].postingDate : null;
+    const daysSinceLastInbound = latestDate
+      ? Math.floor((today - new Date(latestDate)) / (1000 * 60 * 60 * 24))
+      : null;
+    const staleCost = daysSinceLastInbound !== null && daysSinceLastInbound > 30;
+
+    trends.push({
+      item_number: itemNo,
+      avg_cost_4w: avg4w !== null ? round5(avg4w) : null,
+      avg_cost_2w: avg2w !== null ? round5(avg2w) : null,
+      trend_pct: trendPct,
+      direction,
+      inbound_count_4w: base.length,
+      inbound_count_2w: recent.length,
+      latest_inbound_date: latestDate,
+      days_since_last_inbound: daysSinceLastInbound,
+      stale_cost: staleCost,
+      entries_detail: base.slice(0, 5).map((e) => ({
+        date: e.postingDate,
+        type: e.entryType,
+        qty: e.quantity,
+        cost: round5(e.costAmountActual),
+        unit_cost: e.quantity > 0 ? round5(e.costAmountActual / e.quantity) : 0,
+        document: e.documentNumber,
+      })),
+    });
+  }
+
+  // Sort: red flags first (up/down), then stable
+  trends.sort((a, b) => {
+    const severity = (t) => (t.direction === 'up' ? 0 : t.direction === 'down' ? 1 : 2);
+    return severity(a) - severity(b) || Math.abs(b.trend_pct) - Math.abs(a.trend_pct);
+  });
+
+  const summary = {
+    up: trends.filter((t) => t.direction === 'up').length,
+    down: trends.filter((t) => t.direction === 'down').length,
+    stable: trends.filter((t) => t.direction === 'stable').length,
+    stale: trends.filter((t) => t.stale_cost).length,
+  };
+
+  return {
+    store: store.code,
+    store_name: store.name,
+    period: {
+      base: `${baseStartStr} to ${todayStr}`,
+      recent: `${recentStartStr} to ${todayStr}`,
+      base_days: periodDays,
+      recent_days: recentDays,
+    },
+    summary,
+    note: 'trend_pct = (avg_2w - avg_4w) / avg_4w * 100. direction: up (>+5%), down (<-5%), stable (±5%). stale_cost = no inbound entries in 30+ days.',
+    items: trends,
+  };
+}
+
+function weightedAvg(entries) {
+  const totalQty = entries.reduce((s, e) => s + (e.quantity || 0), 0);
+  const totalCost = entries.reduce((s, e) => s + (e.costAmountActual || 0), 0);
+  if (totalQty <= 0) return null;
+  return totalCost / totalQty;
+}
+
+function round2(n) {
+  return Math.round(n * 100) / 100;
+}
+
+function round5(n) {
+  return Math.round(n * 100000) / 100000;
+}

package/tools/inventario/shared/cost-calculator.js

@@ -0,0 +1,64 @@
+import { logger } from '../../../utils/logger.js';
+
+/**
+ * Returns true if the category represents real inventory (not sales/combo items).
+ * Excludes FQ-*, FQ_* and FQVENTA categories.
+ */
+export function isInventoryCategory(cat) {
+  const upper = (cat || '').toUpperCase();
+  return !upper.startsWith('FQ-') && !upper.startsWith('FQ_') && upper !== 'FQVENTA';
+}
+
+/**
+ * Fetch the most recent inbound entries per item and compute current unit cost.
+ * Uses the last 3 Assembly Output / Purchase / Positive Adjustment entries.
+ * Excludes future-dated entries and Sales Returns.
+ *
+ * @returns {Object} Map of itemNumber → { unit_cost, source, sample_size, latest_date }
+ */
+export async function getCalculatedCosts(bcClient, companyId, itemNumbers) {
+  if (itemNumbers.length === 0) return {};
+
+  const results = {};
+  const todayStr = new Date().toISOString().split('T')[0];
+  const typeFilter = `(entryType eq 'Purchase' or entryType eq 'Assembly_x0020_Output' or entryType eq 'Positive_x0020_Adjmt_x002E_')`;
+
+  const fetches = itemNumbers.map(async (itemNo) => {
+    const filter = `itemNumber eq '${itemNo}' and ${typeFilter} and postingDate le ${todayStr}`;
+    const url = bcClient.buildApiUrl(companyId, 'itemLedgerEntries', {
+      $filter: filter,
+      $select: 'itemNumber,quantity,costAmountActual,postingDate',
+      $orderby: 'postingDate desc',
+      $top: '10',
+    });
+    try {
+      const entries = await bcClient.apiCall(url);
+      if (entries.length === 0) return;
+
+      const recent = entries.slice(0, 3);
+      const totalQty = recent.reduce((s, e) => s + (e.quantity || 0), 0);
+      const totalCost = recent.reduce((s, e) => s + (e.costAmountActual || 0), 0);
+      if (totalQty > 0) {
+        results[itemNo] = {
+          unit_cost: round5(totalCost / totalQty),
+          source: 'last_3_inbound',
+          sample_size: recent.length,
+          latest_date: recent[0].postingDate,
+        };
+      }
+    } catch (err) {
+      logger.info(`Cost calc failed for ${itemNo}: ${err.message}`);
+    }
+  });
+
+  // Run in batches of 5 to avoid rate limiting
+  for (let i = 0; i < fetches.length; i += 5) {
+    await Promise.all(fetches.slice(i, i + 5));
+  }
+
+  return results;
+}
+
+function round5(n) {
+  return Math.round(n * 100000) / 100000;
+}

package/tools/ventas/index.js

@@ -0,0 +1,3 @@
+export { salesAnalysisTool, handleSalesAnalysis } from './sales-analysis.js';
+export { productPerformanceTool, handleProductPerformance } from './product-performance.js';
+export { salesStoreComparisonTool, handleSalesStoreComparison } from './sales-store-comparison.js';

package/tools/ventas/product-performance.js

@@ -0,0 +1,182 @@
+import { getDateRange, getPreviousPeriodRange, formatPercent } from '../../utils/date-helper.js';
+import { aggregateByField, calculateGrowth } from '../../utils/sales-aggregation.js';
+import { generateProductInsights } from '../../utils/sales-insights.js';
+import { logger } from '../../utils/logger.js';
+
+export const productPerformanceTool = {
+  name: 'get_product_performance',
+  description:
+    'Análisis detallado de rendimiento de productos de Full Queso. Identifica top performers, underperformers y oportunidades. Incluye desglose por tienda, crecimiento vs periodo anterior y margen de utilidad. Montos en USD.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      period: {
+        type: 'string',
+        enum: ['last_7_days', 'last_30_days', 'this_month', 'last_month', 'specific_month', 'custom'],
+        description: 'Periodo de análisis. 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',
+      },
+      stores: {
+        type: 'array',
+        items: { type: 'string', enum: ['FQ01', 'FQ28', 'FQ88', 'all'] },
+        description: 'Tiendas a analizar',
+        default: ['all'],
+      },
+      sort_by: {
+        type: 'string',
+        enum: ['revenue', 'margin', 'quantity', 'growth'],
+        description: 'Criterio de ordenamiento',
+        default: 'revenue',
+      },
+      top_n: {
+        type: 'number',
+        description: 'Cantidad de productos a retornar',
+        default: 20,
+      },
+    },
+  },
+};
+
+export async function handleProductPerformance(bcClient, args) {
+  const period = args.period || 'last_30_days';
+  const stores = args.stores || ['all'];
+  const sortBy = args.sort_by || 'revenue';
+  const topNCount = args.top_n || 20;
+
+  const dateRange = getDateRange(period, args.start_date, args.end_date, args.month);
+  const prevRange = getPreviousPeriodRange(dateRange.start, dateRange.end);
+
+  logger.info(`Product performance: ${dateRange.start} to ${dateRange.end}`);
+
+  const allStoresData = await bcClient.getAllSalesStoreData(stores, dateRange.start, dateRange.end);
+
+  let prevStoresData = null;
+  try {
+    prevStoresData = await bcClient.getAllSalesStoreData(stores, prevRange.start, prevRange.end);
+  } catch (err) {
+    logger.warn('Could not fetch previous period for growth:', err.message);
+  }
+
+  // Aggregate current period by product across all stores
+  let allLines = [];
+  const linesByStore = {};
+
+  for (const [code, data] of Object.entries(allStoresData)) {
+    linesByStore[code] = data.lines;
+    allLines = allLines.concat(
+      data.lines.map((l) => ({ ...l, storeCode: code }))
+    );
+  }
+
+  const byProduct = aggregateByField(allLines, 'displayName');
+
+  // Aggregate previous period by product for growth
+  const prevByProduct = {};
+  if (prevStoresData) {
+    let prevLines = [];
+    for (const data of Object.values(prevStoresData)) {
+      prevLines = prevLines.concat(data.lines);
+    }
+    const prevAgg = aggregateByField(prevLines, 'displayName');
+    for (const p of prevAgg) {
+      prevByProduct[p.key] = p;
+    }
+  }
+
+  // Enrich products with growth and per-store breakdown
+  const enrichedProducts = byProduct.map((product) => {
+    const prev = prevByProduct[product.key];
+    const growth = prev ? calculateGrowth(product.revenue, prev.revenue) : null;
+
+    const storeBreakdown = {};
+    for (const [code, lines] of Object.entries(linesByStore)) {
+      const storeLines = lines.filter((l) => l.displayName === product.key);
+      const storeRevenue = storeLines.reduce((s, l) => s + (l.amount || 0), 0);
+      const storeQty = storeLines.reduce((s, l) => s + (l.quantity || 0), 0);
+      if (storeRevenue > 0 || storeQty > 0) {
+        storeBreakdown[code] = {
+          revenue: Math.round(storeRevenue * 100) / 100,
+          quantity: storeQty,
+        };
+      }
+    }
+
+    return { ...product, growth, stores: storeBreakdown };
+  });
+
+  // Sort
+  const sortField = sortBy === 'growth' ? 'growth' : sortBy === 'margin' ? 'margin_pct' : sortBy;
+  const sorted = [...enrichedProducts].sort((a, b) => {
+    const aVal = a[sortField] ?? -Infinity;
+    const bVal = b[sortField] ?? -Infinity;
+    return bVal - aVal;
+  });
+
+  // Top performers
+  const totalRevenue = enrichedProducts.reduce((s, p) => s + p.revenue, 0) || 1;
+  const topPerformers = sorted.slice(0, topNCount).map((p) => ({
+    product: p.key,
+    item_number: p.lines[0]?.itemNumber || '',
+    revenue: Math.round(p.revenue * 100) / 100,
+    revenue_pct: Math.round((p.revenue / totalRevenue) * 1000) / 10,
+    quantity: p.quantity,
+    cost_usd: Math.round(p.cost_usd * 100) / 100,
+    margin_pct: Math.round(p.margin_pct * 10) / 10,
+    growth_vs_previous: p.growth !== null ? Math.round(p.growth * 10) / 10 : null,
+    growth_label: p.growth !== null ? formatPercent(p.growth) : 'Sin datos previos',
+    stores: p.stores,
+    insights: generateProductInsights(p, enrichedProducts),
+  }));
+
+  // Underperformers
+  const underperformers = enrichedProducts
+    .filter((p) => p.revenue > 0 && ((p.growth !== null && p.growth < -10) || p.margin_pct < 15))
+    .sort((a, b) => (a.growth ?? 0) - (b.growth ?? 0))
+    .slice(0, 10)
+    .map((p) => ({
+      product: p.key,
+      item_number: p.lines[0]?.itemNumber || '',
+      revenue: Math.round(p.revenue * 100) / 100,
+      quantity: p.quantity,
+      margin_pct: Math.round(p.margin_pct * 10) / 10,
+      growth_vs_previous: p.growth !== null ? Math.round(p.growth * 10) / 10 : null,
+      issue: p.growth !== null && p.growth < -10
+        ? `Caída de ${formatPercent(p.growth)} en ventas`
+        : `Margen bajo: ${p.margin_pct.toFixed(1)}%`,
+    }));
+
+  // Opportunities
+  const opportunities = enrichedProducts
+    .filter((p) => p.margin_pct > 40 && p.revenue > 0)
+    .sort((a, b) => b.margin_pct - a.margin_pct)
+    .slice(0, 10)
+    .map((p) => ({
+      product: p.key,
+      item_number: p.lines[0]?.itemNumber || '',
+      current_revenue: Math.round(p.revenue * 100) / 100,
+      margin_pct: Math.round(p.margin_pct * 10) / 10,
+      recommendation: `Promover más agresivamente. Margen de ${p.margin_pct.toFixed(1)}% permite promociones.`,
+      potential_additional_revenue: Math.round(p.revenue * 0.2 * 100) / 100,
+    }));
+
+  return {
+    period: { start: dateRange.start, end: dateRange.end, label: period },
+    sorted_by: sortBy,
+    total_products: enrichedProducts.length,
+    top_performers: topPerformers,
+    underperformers,
+    opportunities,
+  };
+}

package/tools/ventas/sales-analysis.js

@@ -0,0 +1,211 @@
+import { getDateRange, getPreviousPeriodRange, formatPercent } from '../../utils/date-helper.js';
+import { aggregateByField, aggregateByDate, calculateSummary, calculateGrowth, topN } from '../../utils/sales-aggregation.js';
+import { generateSalesInsights } from '../../utils/sales-insights.js';
+import { logger } from '../../utils/logger.js';
+
+export const salesAnalysisTool = {
+  name: 'get_sales_analysis',
+  description:
+    'Análisis multidimensional de ventas de Full Queso. Permite analizar ventas por producto, categoría, tienda y periodo de tiempo. Retorna métricas clave (ingresos, transacciones, ticket promedio, margen) e insights accionables con recomendaciones específicas. Montos en USD.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      period: {
+        type: 'string',
+        enum: ['last_7_days', 'last_30_days', 'this_month', 'last_month', 'specific_month', 'custom'],
+        description: 'Periodo de análisis. 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',
+      },
+      stores: {
+        type: 'array',
+        items: { type: 'string', enum: ['FQ01', 'FQ28', 'FQ88', 'all'] },
+        description: 'Tiendas a analizar. Use ["all"] para todas.',
+        default: ['all'],
+      },
+      dimensions: {
+        type: 'array',
+        items: { type: 'string', enum: ['product', 'category', 'customer', 'time'] },
+        description: 'Dimensiones de agrupación',
+        default: ['product'],
+      },
+      metrics: {
+        type: 'array',
+        items: { type: 'string', enum: ['revenue', 'quantity', 'margin', 'avg_ticket'] },
+        description: 'Métricas a calcular',
+        default: ['revenue', 'quantity'],
+      },
+    },
+  },
+};
+
+export async function handleSalesAnalysis(bcClient, args) {
+  const period = args.period || 'last_30_days';
+  const stores = args.stores || ['all'];
+  const dimensions = args.dimensions || ['product'];
+
+  const dateRange = getDateRange(period, args.start_date, args.end_date, args.month);
+  const prevRange = getPreviousPeriodRange(dateRange.start, dateRange.end);
+
+  logger.info(`Sales analysis: ${dateRange.start} to ${dateRange.end}, stores: ${stores.join(',')}`);
+
+  const allStoresData = await bcClient.getAllSalesStoreData(stores, dateRange.start, dateRange.end);
+
+  // Extract exchange rate and merge GL revenue across stores
+  const firstStoreData = Object.values(allStoresData)[0];
+  const exchangeRate = firstStoreData?.exchangeRate || null;
+
+  const mergedGLRevenue = { total_usd: 0, breakdown: {} };
+  for (const data of Object.values(allStoresData)) {
+    if (data.glRevenue) {
+      mergedGLRevenue.total_usd += data.glRevenue.total_usd;
+      for (const [acct, amt] of Object.entries(data.glRevenue.breakdown)) {
+        mergedGLRevenue.breakdown[acct] = (mergedGLRevenue.breakdown[acct] || 0) + amt;
+      }
+    }
+  }
+  for (const acct of Object.keys(mergedGLRevenue.breakdown)) {
+    mergedGLRevenue.breakdown[acct] = Math.round(mergedGLRevenue.breakdown[acct] * 100) / 100;
+  }
+  mergedGLRevenue.total_usd = Math.round(mergedGLRevenue.total_usd * 100) / 100;
+
+  // Fetch previous period data for trend comparison
+  let prevStoresData = null;
+  try {
+    prevStoresData = await bcClient.getAllSalesStoreData(stores, prevRange.start, prevRange.end);
+  } catch (err) {
+    logger.warn('Could not fetch previous period data for trends:', err.message);
+  }
+
+  // Combine all lines and invoices across stores
+  let allInvoices = [];
+  let allLines = [];
+  const byStoreResults = [];
+
+  for (const [code, data] of Object.entries(allStoresData)) {
+    allInvoices = allInvoices.concat(data.invoices);
+    allLines = allLines.concat(
+      data.lines.map((l) => ({ ...l, storeCode: code, storeName: data.storeName }))
+    );
+
+    const storeSummary = calculateSummary(data.invoices, data.lines, exchangeRate, data.glRevenue);
+    byStoreResults.push({
+      store_code: code,
+      store_name: data.storeName,
+      ...storeSummary,
+    });
+  }
+
+  // Global summary
+  const summary = calculateSummary(allInvoices, allLines, exchangeRate, mergedGLRevenue);
+
+  // Previous period summary for trends
+  let prevSummary = null;
+  if (prevStoresData) {
+    let prevInvoices = [];
+    let prevLines = [];
+    const prevMergedGL = { total_usd: 0, breakdown: {} };
+    for (const data of Object.values(prevStoresData)) {
+      prevInvoices = prevInvoices.concat(data.invoices);
+      prevLines = prevLines.concat(data.lines);
+      if (data.glRevenue) {
+        prevMergedGL.total_usd += data.glRevenue.total_usd;
+        for (const [acct, amt] of Object.entries(data.glRevenue.breakdown)) {
+          prevMergedGL.breakdown[acct] = (prevMergedGL.breakdown[acct] || 0) + amt;
+        }
+      }
+    }
+    prevMergedGL.total_usd = Math.round(prevMergedGL.total_usd * 100) / 100;
+    prevSummary = calculateSummary(prevInvoices, prevLines, exchangeRate, prevMergedGL);
+  }
+
+  // Trends
+  const trends = {
+    vs_previous_period: {
+      period: `${prevRange.start} a ${prevRange.end}`,
+      revenue_change: prevSummary ? formatPercent(calculateGrowth(summary.total_revenue_usd, prevSummary.total_revenue_usd) || 0) : 'N/A',
+      transactions_change: prevSummary ? formatPercent(calculateGrowth(summary.total_transactions, prevSummary.total_transactions) || 0) : 'N/A',
+      avg_ticket_change: prevSummary ? formatPercent(calculateGrowth(summary.avg_ticket_usd, prevSummary.avg_ticket_usd) || 0) : 'N/A',
+    },
+    revenuGrowth: prevSummary ? calculateGrowth(summary.total_revenue_usd, prevSummary.total_revenue_usd) : null,
+    ticketGrowth: prevSummary ? calculateGrowth(summary.avg_ticket_usd, prevSummary.avg_ticket_usd) : null,
+    transactionGrowth: prevSummary ? calculateGrowth(summary.total_transactions, prevSummary.total_transactions) : null,
+  };
+
+  // Build dimension breakdowns
+  const result = {
+    period: { start: dateRange.start, end: dateRange.end, label: period },
+    summary,
+    by_store: byStoreResults,
+  };
+
+  if (dimensions.includes('product')) {
+    const byProduct = aggregateByField(allLines, 'displayName');
+    const totalLineRevenue = byProduct.reduce((s, p) => s + p.revenue, 0) || 1;
+    result.by_product = topN(byProduct, 'revenue', 20).map((p) => ({
+      product: p.key,
+      item_number: p.lines[0]?.itemNumber || '',
+      revenue: Math.round(p.revenue * 100) / 100,
+      revenue_pct: Math.round((p.revenue / totalLineRevenue) * 1000) / 10,
+      quantity: p.quantity,
+      cost_usd: Math.round(p.cost_usd * 100) / 100,
+      margin_pct: Math.round(p.margin_pct * 10) / 10,
+    }));
+  }
+
+  if (dimensions.includes('category')) {
+    const byCategory = aggregateByField(allLines, 'itemCategoryCode');
+    result.by_category = byCategory
+      .sort((a, b) => b.revenue - a.revenue)
+      .map((c) => ({
+        category: c.key,
+        revenue: Math.round(c.revenue * 100) / 100,
+        quantity: c.quantity,
+        margin_pct: Math.round(c.margin_pct * 10) / 10,
+      }));
+  }
+
+  if (dimensions.includes('customer')) {
+    const byCustomer = {};
+    for (const inv of allInvoices) {
+      const name = inv.customerName || 'Desconocido';
+      if (!byCustomer[name]) {
+        byCustomer[name] = { customer: name, revenue: 0, transactions: 0 };
+      }
+      byCustomer[name].revenue += inv.totalAmountExcludingTax || 0;
+      byCustomer[name].transactions += 1;
+    }
+    result.by_customer = Object.values(byCustomer)
+      .sort((a, b) => b.revenue - a.revenue)
+      .slice(0, 20)
+      .map((c) => ({
+        ...c,
+        revenue: Math.round(c.revenue * 100) / 100,
+        avg_ticket: Math.round((c.revenue / c.transactions) * 100) / 100,
+      }));
+  }
+
+  if (dimensions.includes('time')) {
+    result.by_date = aggregateByDate(allLines);
+  }
+
+  result.trends = { vs_previous_period: trends.vs_previous_period };
+
+  const byProductForInsights = dimensions.includes('product')
+    ? aggregateByField(allLines, 'displayName')
+    : null;
+  result.insights = generateSalesInsights(summary, byProductForInsights, byStoreResults, trends);
+
+  return result;
+}