@fullqueso/mcp-bc-gastos 1.14.2 → 1.19.0

package/tools/auditoria/pm-receipts.js

@@ -0,0 +1,182 @@
+import { resolveStores } from '../../config/company-config.js';
+
+export const pmReceiptsTool = {
+  name: 'get_pm_receipts',
+  description:
+    'Recibos de Pago Móvil (PM) registrados en BC para una cuenta bancaria. Muestra cada recibo MPCR con su cliente, factura, y monto VES. Filtra customer ledger entries por la cuenta bancaria de balanceo (ej: FQ01-MN0008 = GL 18280). Útil para auditar qué días tienen registro de PM y cuáles faltan.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      store: {
+        type: 'string',
+        enum: ['FQ01', 'FQ28', 'FQ88'],
+        description: 'Tienda a consultar.',
+      },
+      bank_account: {
+        type: 'string',
+        description: 'Cuenta bancaria BC (ej: "FQ01-MN0008").',
+      },
+      date_from: {
+        type: 'string',
+        description: 'Fecha inicio (YYYY-MM-DD).',
+      },
+      date_to: {
+        type: 'string',
+        description: 'Fecha fin (YYYY-MM-DD).',
+      },
+    },
+    required: ['store', 'bank_account', 'date_from', 'date_to'],
+  },
+};
+
+export async function handlePmReceipts(bcClient, args) {
+  const { store, bank_account, date_from, date_to } = args;
+  if (!store) throw new Error('Parámetro requerido: store');
+  if (!bank_account) throw new Error('Parámetro requerido: bank_account');
+  if (!date_from || !date_to) throw new Error('Parámetros requeridos: date_from, date_to');
+
+  const stores = resolveStores([store]);
+  const storeInfo = stores[0];
+
+  // Query customer ledger entries for the 3 PM customers
+  const pmCustomers = ['FQ01-CN0006-1', 'FQ01-CN0006-2', 'FQ01-CN0007'];
+
+  const allEntries = [];
+
+  for (const customer of pmCustomers) {
+    // Use Beta API — query Payment entries for this customer
+    const url = bcClient.buildBetaApiUrl(storeInfo.companyId, 'customerLedgerEntries', {
+      $filter: [
+        `postingDate ge ${date_from}`,
+        `postingDate le ${date_to}`,
+        `customerNumber eq '${customer}'`,
+        `documentType eq 'Payment'`,
+      ].join(' and '),
+      $select: 'entryNumber,documentType,description,postingDate,documentNumber,externalDocumentNumber,customerNumber,open,amount,debitAmount,creditAmount,amountLocalCurrency,currencyCode,balancingAccountNumber,balancingAccountType',
+    });
+
+    const rawEntries = await bcClient.apiCallAllPages(url);
+
+    // Filter to only entries that balance against our bank account
+    const pmEntries = rawEntries.filter(
+      (e) => e.balancingAccountNumber === bank_account
+    );
+
+    allEntries.push(...pmEntries);
+  }
+
+  // Also query Invoice entries for cross-reference (to link receipt → invoice)
+  const invoiceEntries = [];
+  for (const customer of pmCustomers) {
+    const url = bcClient.buildBetaApiUrl(storeInfo.companyId, 'customerLedgerEntries', {
+      $filter: [
+        `postingDate ge ${date_from}`,
+        `postingDate le ${date_to}`,
+        `customerNumber eq '${customer}'`,
+        `documentType eq 'Invoice'`,
+      ].join(' and '),
+      $select: 'entryNumber,documentType,description,postingDate,documentNumber,externalDocumentNumber,customerNumber,open,amount,amountLocalCurrency,currencyCode',
+    });
+
+    const rawInvoices = await bcClient.apiCallAllPages(url);
+    invoiceEntries.push(...rawInvoices);
+  }
+
+  // Sort payment entries by date
+  allEntries.sort((a, b) => (a.postingDate || '').localeCompare(b.postingDate || ''));
+
+  // Build invoice lookup by (customer, date) for cross-reference
+  const invoiceByCustomerDate = {};
+  for (const inv of invoiceEntries) {
+    const key = `${inv.customerNumber}|${inv.postingDate}`;
+    if (!invoiceByCustomerDate[key]) {
+      invoiceByCustomerDate[key] = [];
+    }
+    invoiceByCustomerDate[key].push({
+      document_number: inv.documentNumber,
+      description: inv.description,
+      amount_ves: Math.round((inv.amount || 0) * 100) / 100,
+      amount_usd: Math.round((inv.amountLocalCurrency || 0) * 100) / 100,
+      external_document_number: inv.externalDocumentNumber || '',
+    });
+  }
+
+  // Format entries with invoice cross-reference
+  const receipts = allEntries.map((e) => {
+    const key = `${e.customerNumber}|${e.postingDate}`;
+    const linkedInvoices = invoiceByCustomerDate[key] || [];
+
+    return {
+      posting_date: e.postingDate,
+      receipt_no: e.documentNumber,
+      customer: e.customerNumber,
+      customer_name: e.description || '',
+      amount_ves: Math.round(Math.abs(e.amount || 0) * 100) / 100,
+      amount_usd: Math.round(Math.abs(e.amountLocalCurrency || 0) * 100) / 100,
+      external_document_no: e.externalDocumentNumber || '',
+      bank_account: e.balancingAccountNumber || '',
+      linked_invoices: linkedInvoices,
+    };
+  });
+
+  // Daily summary
+  const dailySummary = {};
+  for (const r of receipts) {
+    const date = r.posting_date;
+    if (!dailySummary[date]) {
+      dailySummary[date] = { total_ves: 0, count: 0, customers: new Set() };
+    }
+    dailySummary[date].total_ves += r.amount_ves;
+    dailySummary[date].count += 1;
+    dailySummary[date].customers.add(r.customer);
+  }
+
+  // Find missing days
+  const startDate = new Date(date_from);
+  const endDate = new Date(date_to);
+  const allDays = [];
+  for (let d = new Date(startDate); d <= endDate; d.setDate(d.getDate() + 1)) {
+    allDays.push(d.toISOString().split('T')[0]);
+  }
+  const receiptDates = new Set(Object.keys(dailySummary));
+  const missingDays = allDays.filter((d) => !receiptDates.has(d));
+
+  const dailyArray = allDays.map((date) => {
+    const day = dailySummary[date];
+    return {
+      date,
+      has_receipts: !!day,
+      total_ves: day ? Math.round(day.total_ves * 100) / 100 : 0,
+      receipt_count: day ? day.count : 0,
+      customers: day ? [...day.customers].sort() : [],
+    };
+  });
+
+  const totalVes = Math.round(receipts.reduce((s, r) => s + r.amount_ves, 0) * 100) / 100;
+  const totalUsd = Math.round(receipts.reduce((s, r) => s + r.amount_usd, 0) * 100) / 100;
+
+  return {
+    store,
+    store_name: storeInfo.name,
+    bank_account,
+    period: { from: date_from, to: date_to },
+    receipts,
+    daily_summary: dailyArray,
+    invoices_reference: invoiceEntries.map((inv) => ({
+      posting_date: inv.postingDate,
+      document_number: inv.documentNumber,
+      customer: inv.customerNumber,
+      description: inv.description,
+      amount_ves: Math.round((inv.amount || 0) * 100) / 100,
+    })),
+    summary: {
+      total_receipts: receipts.length,
+      total_ves: totalVes,
+      total_usd: totalUsd,
+      days_with_receipts: Object.keys(dailySummary).length,
+      days_without_receipts: missingDays.length,
+      missing_days: missingDays,
+      customers_found: [...new Set(receipts.map((r) => r.customer))].sort(),
+    },
+  };
+}

package/tools/auditoria/reconcile-pos-sales.js

@@ -4,17 +4,37 @@ import { logger } from '../../utils/logger.js';
 
 // ── Constants ────────────────────────────────────────────────────────────
 
-// Bank account suffix → GL account for journal entry suggestions
+// Bank account suffix → GL account for journal entry suggestions (per store)
 const BANK_GL_MAP = {
-  'MN0001': '18210', // Banesco
-  'MN0002': '18220', // BDV 1925
-  'MN0003': '18230', // Bancamiga 7015
-  'MN0004': '18240', // BDV 5550
-  'MN0005': '18250', // Bancamiga 4523
-  'MN0006': '18260', // Bancrecer 2450
-  'MN0007': '18270', // Bancrecer 2467
-  'MN0008': '18280', // BDV 5187 (Pago Móvil)
-  'MN0012': '18290', // UBII
+  FQ01: {
+    'MN0001': '18210', // Banesco 4421 Bs.
+    'MN0002': '18220', // BDV 1925 Bs.
+    'MN0003': '18230', // Bancamiga 7015 Bs.
+    'MN0004': '18240', // BDV 5550 Bs.
+    'MN0005': '18250', // Bancamiga 4523 Bs.
+    'MN0006': '18260', // Bancrecer 2450 Bs.
+    'MN0007': '18270', // Bancrecer 2467 Bs.
+    'MN0008': '18280', // BDV 5187 Bs. (Pago Móvil)
+    'MN0012': '18290', // UBII
+    'MN0030': '18130', // Caja tienda ventas Bs.
+    'ME0030': '18140', // Caja tienda ventas $
+  },
+  FQ28: {
+    'MN0001': '18210', // BDV 8139 Bs.
+    'MN0002': '18220', // Bancrecer 5474 Bs.
+    'MN0028': '18290', // UBII 6249 Bs
+    'MN0029': '18291', // UBII 6442 * Bs
+    'MN0030': '18130', // Caja tienda ventas Bs.
+    'MN0031': '18160', // Caja transitoria tienda ventas Bs.
+    'MN0032': '18292', // UBII 4 FQ-28
+    'MN0033': '18295', // UBII 7 FQ-28
+    'MN0098': '18298', // Operaciones en Tránsito
+    'ME0002': '18310', // Bancrecer $
+    'ME0005': '18410', // Zelle Bofa $ *
+    'ME0030': '18140', // Caja tienda ventas $
+    'ME0031': '18170', // Caja transitoria tienda ventas $
+    'ME0035': '18150', // Banco Bóveda $
+  },
 };
 
 const COMMISSION_ACCOUNT = '67100'; // Comisiones Bancarias
@@ -140,12 +160,15 @@ function parseBankStatementLot(description) {
  * Get GL account for a bank account number.
  * "FQ01-MN0001" → "18210"
  */
-function getBankGLAccount(bankAccountNo) {
+function getBankGLAccount(bankAccountNo, store) {
   if (!bankAccountNo) return null;
-  // Extract suffix: "FQ01-MN0001" → "MN0001"
+  // Extract store and suffix: "FQ01-MN0001" → store "FQ01", suffix "MN0001"
   const parts = bankAccountNo.split('-');
   const suffix = parts[parts.length - 1];
-  return BANK_GL_MAP[suffix] || null;
+  const storeKey = store || parts[0];
+  const storeMap = BANK_GL_MAP[storeKey];
+  if (!storeMap) return null;
+  return storeMap[suffix] || null;
 }
 
 // ── Union-Find for Compound Lots ─────────────────────────────────────────
@@ -818,7 +841,7 @@ export async function handleReconcilePOSSales(bcClient, args) {
     }
 
     // ── Journal entry suggestions for commissions ──
-    const glAccount = getBankGLAccount(bankAccount);
+    const glAccount = getBankGLAccount(bankAccount, store);
     const journalEntries = [];
 
     if (isBDVAggregate && bdvAggregate.commission_total > 0) {
@@ -1211,7 +1234,7 @@ export async function handleReconcilePOSSales(bcClient, args) {
       const ubiiAvgFee = ubiiTotalBC > 0 ? round2((ubiiTotalFee / ubiiTotalBC) * 100) : 0;
 
       // Journal entries: fee + transfer per matched day
-      const ubiiGL = getBankGLAccount(ubiiFullAccount); // 18290
+      const ubiiGL = getBankGLAccount(ubiiFullAccount, store); // 18290
       const ubiiJournalEntries = [];
       for (const m of ubiiMatchedDays) {
         if (m.fee_ves > 0) {
@@ -1225,7 +1248,7 @@ export async function handleReconcilePOSSales(bcClient, args) {
           });
         }
         // Transfer entry: debit receiving bank, credit UBII
-        const receivingGL = getBankGLAccount(m.bank_deposit_bank);
+        const receivingGL = getBankGLAccount(m.bank_deposit_bank, store);
         if (receivingGL) {
           ubiiJournalEntries.push({
             posting_date: m.bank_deposit_date,

package/tools/cobranzas/customer-list.js

@@ -0,0 +1,63 @@
+import { resolveStores } from '../../config/company-config.js';
+
+export const customerListTool = {
+  name: 'get_customer_list',
+  description:
+    'Lista de clientes con número, nombre y RIF (taxRegistrationNumber). Útil para identificar clientes por RIF o exportar directorio de clientes.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      store: {
+        type: 'string',
+        enum: ['FQ01', 'FQ28', 'FQ88'],
+        description: 'Tienda a consultar.',
+      },
+      customer_number: {
+        type: 'string',
+        description: 'Filtrar por número de cliente específico.',
+      },
+    },
+    required: ['store'],
+  },
+};
+
+export async function handleCustomerList(bcClient, args) {
+  const store = args.store;
+  if (!store) throw new Error('Parámetro requerido: store');
+
+  const stores = resolveStores([store]);
+  const storeInfo = stores[0];
+
+  const selectFields = 'number,displayName,taxRegistrationNumber';
+  const params = { $select: selectFields, $orderby: 'number' };
+
+  if (args.customer_number) {
+    params.$filter = `number eq '${args.customer_number}'`;
+  }
+
+  const url = bcClient.buildApiUrl(storeInfo.companyId, 'customers', params);
+  const allCustomers = await bcClient.apiCallAllPages(url);
+
+  const customers = allCustomers.map((c) => ({
+    number: c.number,
+    name: c.displayName,
+    rif: c.taxRegistrationNumber || '',
+  }));
+
+  return {
+    content: [
+      {
+        type: 'text',
+        text: JSON.stringify(
+          {
+            store,
+            total_customers: customers.length,
+            customers,
+          },
+          null,
+          2
+        ),
+      },
+    ],
+  };
+}

package/tools/inventario/index.js

@@ -1,3 +1,7 @@
 export { itemCardTool, handleItemCard } from './item-card.js';
 export { itemLedgerEntriesTool, handleItemLedgerEntries } from './item-ledger-entries.js';
 export { itemValueEntriesTool, handleItemValueEntries } from './item-value-entries.js';
+export { itemCostTrendTool, handleItemCostTrend } from './item-cost-trend.js';
+export { inventoryLevelsTool, handleInventoryLevels } from './inventory-levels.js';
+export { inventoryChangeTool, handleInventoryChange } from './inventory-change.js';
+export { inventoryByLocationTool, handleInventoryByLocation } from './inventory-by-location.js';

package/tools/inventario/inventory-by-location.js

@@ -0,0 +1,212 @@
+import { resolveStores } from '../../config/company-config.js';
+import { logger } from '../../utils/logger.js';
+import { isInventoryCategory } from './shared/cost-calculator.js';
+
+export const inventoryByLocationTool = {
+  name: 'get_inventory_by_location',
+  description:
+    'Inventario desglosado por ubicación (Location Code) dentro de una tienda. Muestra qty y valor por location, con detalle de ítems por cada una. Útil para ver distribución entre depósitos/almacenes internos. Usa OData V4 para acceder a Location_Code.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      store: {
+        type: 'string',
+        enum: ['FQ01', 'FQ28', 'FQ88'],
+        description: 'Tienda a consultar.',
+      },
+      location_code: {
+        type: 'string',
+        description: 'Filtrar por un Location Code específico (e.g. PRINCIPAL, DEPOSITO). Si se omite, muestra todas las ubicaciones.',
+      },
+      item_category: {
+        type: 'string',
+        description: 'Filtrar por itemCategoryCode (e.g. TERMINADO, INSUMO).',
+      },
+      classification: {
+        type: 'string',
+        description: 'Filtrar por inventoryPostingGroupCode (e.g. CONGELADOS, IMPORTADO, LOCAL).',
+      },
+      as_of_date: {
+        type: 'string',
+        description:
+          'Fecha de corte YYYY-MM-DD. Default: hoy (todas las entries). Si es fecha pasada, solo suma ledger entries con Posting_Date <= as_of_date.',
+      },
+    },
+    required: ['store'],
+  },
+};
+
+export async function handleInventoryByLocation(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;
+
+  // 1. Fetch items via standard API (has itemCategoryCode, inventoryPostingGroupCode, unitCost)
+  const itemFilters = [];
+  if (args.item_category) {
+    itemFilters.push(`itemCategoryCode eq '${args.item_category}'`);
+  }
+  if (args.classification) {
+    itemFilters.push(`inventoryPostingGroupCode eq '${args.classification}'`);
+  }
+
+  const itemParams = {
+    $select: 'number,displayName,itemCategoryCode,inventoryPostingGroupCode,unitCost,inventory',
+  };
+  if (itemFilters.length > 0) {
+    itemParams.$filter = itemFilters.join(' and ');
+  }
+
+  const itemUrl = bcClient.buildApiUrl(companyId, 'items', itemParams);
+  const items = await bcClient.apiCallAllPages(itemUrl);
+  logger.info(`${store.code}: ${items.length} items fetched`);
+
+  // Build item metadata map — exclude items without inventoryPostingGroupCode and FQ-* categories
+  const itemMeta = {};
+  let excludedCount = 0;
+  for (const item of items) {
+    if (!item.inventoryPostingGroupCode || !isInventoryCategory(item.itemCategoryCode)) {
+      excludedCount++;
+      continue;
+    }
+    itemMeta[item.number] = {
+      name: item.displayName,
+      category: item.itemCategoryCode || 'SIN_CATEGORIA',
+      classification: item.inventoryPostingGroupCode,
+      unit_cost: item.unitCost || 0,
+      total_inventory: item.inventory || 0,
+    };
+  }
+  if (excludedCount > 0) {
+    logger.info(`${store.code}: excluded ${excludedCount} items without inventoryPostingGroupCode`);
+  }
+
+  // 2. Fetch item ledger entries via OData V4 (has Location_Code field)
+  const today = new Date();
+  const todayStr = today.toISOString().split('T')[0];
+  const asOfDate = args.as_of_date || todayStr;
+  const isHistorical = asOfDate < todayStr;
+
+  const odataFilters = [];
+  if (args.location_code) {
+    odataFilters.push(`Location_Code eq '${args.location_code}'`);
+  }
+  if (isHistorical) {
+    odataFilters.push(`Posting_Date le ${asOfDate}`);
+  }
+
+  const odataParams = {
+    $select: 'Item_No,Location_Code,Quantity',
+  };
+  if (odataFilters.length > 0) {
+    odataParams.$filter = odataFilters.join(' and ');
+  }
+
+  const ledgerUrl = bcClient.buildODataUrl(storeParam, 'ItemLedgerEntries', odataParams);
+  const entries = await bcClient.odataCallAllPages(ledgerUrl);
+  logger.info(`${store.code}: ${entries.length} item ledger entries fetched via OData V4 for location breakdown`);
+
+  // 3. Aggregate: { Location_Code → { Item_No → net_qty } }
+  const locationItems = {};
+
+  for (const e of entries) {
+    const loc = e.Location_Code || 'SIN_UBICACION';
+    const itemNo = e.Item_No;
+    const qty = e.Quantity || 0;
+
+    // Skip items not in our metadata (filtered out or no posting group)
+    if (!itemMeta[itemNo]) continue;
+
+    if (!locationItems[loc]) locationItems[loc] = {};
+    if (!locationItems[loc][itemNo]) locationItems[loc][itemNo] = 0;
+    locationItems[loc][itemNo] += qty;
+  }
+
+  // 4. Build response per location
+  const byLocation = {};
+  const locationSummaries = [];
+
+  for (const [loc, itemQtys] of Object.entries(locationItems)) {
+    let itemCount = 0;
+    let totalQty = 0;
+    let totalCostValue = 0;
+    const itemDetails = [];
+
+    for (const [itemNo, netQty] of Object.entries(itemQtys)) {
+      const roundedQty = round5(netQty);
+      if (roundedQty === 0) continue;
+
+      const meta = itemMeta[itemNo];
+      const costValue = round2(roundedQty * meta.unit_cost);
+
+      itemCount++;
+      totalQty = round5(totalQty + roundedQty);
+      totalCostValue = round2(totalCostValue + costValue);
+
+      itemDetails.push({
+        number: itemNo,
+        name: meta.name,
+        category: meta.category,
+        classification: meta.classification,
+        qty: roundedQty,
+        unit_cost: meta.unit_cost,
+        cost_value: costValue,
+      });
+    }
+
+    if (itemCount === 0) continue;
+
+    // Sort by absolute qty descending, keep top 10
+    itemDetails.sort((a, b) => Math.abs(b.qty) - Math.abs(a.qty));
+    const topItems = itemDetails.slice(0, 10);
+
+    byLocation[loc] = {
+      item_count: itemCount,
+      total_qty: round5(totalQty),
+      total_cost_value: round2(totalCostValue),
+      top_items: topItems,
+    };
+
+    locationSummaries.push({
+      location: loc,
+      item_count: itemCount,
+      total_qty: round5(totalQty),
+      total_cost_value: round2(totalCostValue),
+    });
+  }
+
+  // Sort summaries by cost value descending
+  locationSummaries.sort((a, b) => b.total_cost_value - a.total_cost_value);
+
+  // Grand totals
+  const grandTotal = {
+    locations: locationSummaries.length,
+    item_count: locationSummaries.reduce((s, l) => s + l.item_count, 0),
+    total_qty: round5(locationSummaries.reduce((s, l) => s + l.total_qty, 0)),
+    total_cost_value: round2(locationSummaries.reduce((s, l) => s + l.total_cost_value, 0)),
+  };
+
+  return {
+    store: store.code,
+    store_name: store.name,
+    as_of_date: asOfDate,
+    is_historical: isHistorical,
+    note: isHistorical
+      ? `Inventario histórico al ${asOfDate} reconstruido desde item ledger entries (OData V4) con Posting_Date <= ${asOfDate}, agrupado por Location_Code. unitCost es el actual de BC (no histórico).`
+      : 'Inventario reconstruido desde item ledger entries (OData V4) agrupado por Location_Code. Cada location muestra top 10 ítems por qty. unitCost es el actual de BC.',
+    summary: locationSummaries,
+    by_location: byLocation,
+    grand_total: grandTotal,
+  };
+}
+
+function round2(n) {
+  return Math.round(n * 100) / 100;
+}
+
+function round5(n) {
+  return Math.round(n * 100000) / 100000;
+}