@fullqueso/mcp-bc-gastos 1.14.2 → 1.19.0

package/CHANGELOG.md

@@ -1,5 +1,142 @@
 # CHANGELOG
 
+## [1.19.0] - 2026-04-13
+
+### Added
+- **`get_customer_list` tool (cobranzas)** — Lists customers with number, name, and RIF (taxRegistrationNumber) per store. Supports optional filter by customer number.
+- **`config/bank-gl-map.json`** — Reference config documenting the full bank account suffix → GL account mapping per store (FQ01, FQ28, FQ88), including GL structure for Caja y Bancos (181xx–189xx).
+
+### Changed
+- **POS reconciliation: per-store bank GL mapping** — `BANK_GL_MAP` in `reconcile-pos-sales.js` now keyed by store (FQ01, FQ28) instead of flat suffix lookup. Adds cash register accounts (MN0030, ME0030) and full FQ28 bank set. `getBankGLAccount()` now accepts store parameter for correct GL resolution.
+- Tool count: 44 → 45
+
+---
+
+## [1.18.2] - 2026-04-13
+
+### Fixed
+- **Inventory tools: exclude FQ-\* sale/combo categories** — `get_inventory_levels`, `get_inventory_change`, and `get_inventory_by_location` now filter out items with `itemCategoryCode` starting with `FQ-`, `FQ_`, or equal to `FQVENTA`. These are sales/combo products, not real inventory, and their BC `unitCost` can be contaminated (zero-inventory edge cases), producing inflated inventory valuations. Real inventory items (TERMINADO, INSUMO, etc.) keep BC's FIFO-based `unitCost` which is accurate.
+
+### Changed
+- **Extracted `getCalculatedCosts` to shared module** — Moved from `item-card.js` to `tools/inventario/shared/cost-calculator.js` along with `isInventoryCategory()`. Avoids duplication across inventory tools.
+- **Updated `calculated_unit_cost_method.md`** — Documented category filtering logic and clarified that calculated cost is for FQ-* items only; real inventory uses BC FIFO cost.
+
+---
+
+## [1.18.1] - 2026-04-13
+
+### Changed
+- `get_inventory_by_location` — Added `as_of_date` parameter for historical inventory reconstruction by location. Filters OData V4 item ledger entries with `Posting_Date <= as_of_date`. Also added `isInventoryCategory` filter to exclude FQ-* sale/combo items (aligns with `get_inventory_levels` behavior).
+
+---
+
+## [1.18.0] - 2026-03-19
+
+### Added
+
+**Inventario domain — 2 new tools (inventory levels & change tracking):**
+- `get_inventory_levels` — Inventory snapshot grouped by itemCategoryCode and inventoryPostingGroupCode (congelados/imported/local). Supports historical reconstruction via `as_of_date` (e.g., 1st of month post-EOM adjustment). Returns classification matrix with qty, cost value, and top items per group.
+- `get_inventory_change` — WoW and MoM inventory change analysis. Reconstructs opening/closing inventory per period walking backwards from current balance. Movement breakdown by type (purchases, sales, adjustments, assembly). Trend summary per category and classification.
+
+### Changed
+- Tool count: 42 → 44
+- Inventario domain: 4 → 6 tools
+
+---
+
+## [1.17.0] - 2026-03-18
+
+### Highlights
+- **Ventas domain consolidated** from `mcp-bc-analisis-ventas` — 3 new sales analysis tools
+- Full Queso now has one unified BC MCP with **42 tools** across 8 domains
+
+### Added
+
+**New domain: Ventas (tools/ventas/) — 3 tools:**
+- `get_sales_analysis` — Multi-dimensional sales analysis by product, category, customer, store, time period. Revenue from GL entries (USD), trend comparison vs previous period, actionable insights
+- `get_product_performance` — Top/bottom product performers with growth trends, per-store breakdown, margin analysis, and promotion opportunities
+- `compare_sales_by_store` — Sales comparison across FQ01/FQ28/FQ88: revenue, transactions, avg ticket, top products, daily patterns, cross-store insights
+
+**bc-client.js — Sales API methods:**
+- `getSalesInvoicesExpanded()` — Sales invoices with `$expand=salesInvoiceLines`
+- `getSalesInvoicesWithLines()` — Flattened invoices + enriched lines
+- `getItemsCatalog()` — Items master data for product enrichment
+- `getSalesStoreData()` — Per-store sales orchestration (invoices + items + GL revenue + exchange rate enrichment)
+- `getAllSalesStoreData()` — Multi-store sequential fetch with shared exchange rates
+
+**Utilities:**
+- `utils/sales-aggregation.js` — Sales-specific aggregation: by field, by date, summary calculation, growth, top/bottom N
+- `utils/sales-insights.js` — Business insight generation: revenue trends, margin alerts, store gap analysis, product opportunities
+
+### Notes
+- `compare_sales_by_store` (sales) is separate from `compare_stores` (expenses) to avoid naming conflict
+- Revenue uses GL entries (accounts 40000-49999) as authoritative USD source
+- Line-level amounts used only for relative product/category breakdowns
+- This consolidation deprecates the standalone `@fullqueso/mcp-bc-analisis-ventas` package
+
+## [1.16.0] - 2026-03-16
+
+### Highlights
+- **Dynamic CLI reports** for pending invoice auditing — both Purchase and Sales
+- Parametric scripts: any store (FQ01/FQ28/FQ88/all), any month range, auto-generated Excel
+- 3-tab Excel output: Sin Draft, Con Draft, Pago Parcial — with subtotals by month and invoice numbers for audit
+
+### Added
+
+**Scripts — Posted Purchase Invoices Pendientes:**
+- `scripts/report-pending-invoices.js` — Node.js CLI that fetches open vendor ledger entries + purchMultiPaymentHeaders/Lines, classifies invoices by payment status, and generates Excel via Python
+- `scripts/generate-pending-invoices-xlsx.py` — Python (openpyxl) Excel generator with 3 tabs, month subtotals, color-coded tiers, and grand totals
+
+**Scripts — Posted Sales Invoices Pendientes:**
+- `scripts/report-pending-sales-invoices.js` — Same pattern for customer side: customerLedgerEntries + multiPaymentHeaders/Lines
+- `scripts/generate-pending-sales-invoices-xlsx.py` — Sales-specific Excel generator (Cliente instead of Proveedor, Posted SI instead of Posted PI)
+
+### Usage
+```bash
+# Purchase invoices
+node scripts/report-pending-invoices.js --store FQ28 --from 2025-05 --to 2025-07
+
+# Sales invoices
+node scripts/report-pending-sales-invoices.js --store FQ01 --from 2025-12 --to 2026-01
+
+# All stores, custom output path
+node scripts/report-pending-invoices.js --store all --from 2026-03 --to 2026-03 --out ~/Desktop/report.xlsx
+```
+
+### Technical
+- CLI args via `node:util/parseArgs`: `--store`, `--from`, `--to`, `--out`
+- Parallel API calls: ledger + MP headers + exchange rates fetched concurrently
+- Bulk MP line fetching with server-side $filter for ≤50 headers
+- USD conversion via BCV exchange rate for VES payment lines
+- JSON intermediate file (auto-cleaned) passed to Python for Excel generation
+- Output defaults to `~/Downloads/{STORE}_{Type}_{period}_{date}.xlsx`
+
+---
+
+## [1.15.0] - 2026-03-15
+
+### Highlights
+- **36 tools** across 7 domains — new `get_item_cost_trend` tool for inventory cost trending
+- 2W vs 4W rolling average comparison to detect rising/falling ingredient costs
+- Documented `calculated_unit_cost` methodology for cross-project use (MCP + Dashboard)
+
+### Added
+
+**Inventario — 1 new tool:**
+- `get_item_cost_trend` — compares weighted avg inbound cost of last 2 weeks vs last 4 weeks. Detects if cost is trending up (>+5%), down (<-5%), or stable. Supports single item or bulk analysis by category. Includes stale cost detection (no inbound > 30 days).
+
+**Documentation:**
+- `docs/calculated_unit_cost_method.md` — complete methodology for calculated unit cost (Last 3 Inbound) and cost trending (2W vs 4W). Shared reference for mcp-fullqueso-bc-gastos and mcp-fullqueso-dashboard COGS table implementation.
+
+### Technical
+- New file: `tools/inventario/item-cost-trend.js`
+- Configurable `period_days` parameter (default 28, recent = half)
+- Results sorted by severity: cost spikes first, then stable items
+- Batch API calls (5 concurrent) to avoid BC rate limiting
+- Category filtering via cross-reference with items endpoint
+
+---
+
 ## [1.14.0] - 2026-03-15
 
 ### Highlights

package/config/bank-gl-map.json

@@ -0,0 +1,93 @@
+{
+  "version": "1.0",
+  "last_updated": "2026-03-23",
+  "description": "Mapeo banco_code (BC Bank Account suffix) → cuenta GL (Chart of Accounts). Usado por POS reconciliation y journal entry suggestions. Cada tienda tiene su propio CoA con bancos distintos.",
+  "stores": {
+    "FQ01": {
+      "store_name": "FQ01 - Chacao Sambil",
+      "accounts": {
+        "MN0001": { "gl": "18210", "name": "Banesco 4421 Bs.", "currency": "VES", "category": "bancos_nacionales" },
+        "MN0002": { "gl": "18220", "name": "BDV 1925 Bs.", "currency": "VES", "category": "bancos_nacionales" },
+        "MN0003": { "gl": "18230", "name": "Bancamiga 7015 Bs.", "currency": "VES", "category": "bancos_nacionales" },
+        "MN0004": { "gl": "18240", "name": "BDV 5550 Bs.", "currency": "VES", "category": "bancos_nacionales" },
+        "MN0005": { "gl": "18250", "name": "Bancamiga 4523 Bs.", "currency": "VES", "category": "bancos_nacionales" },
+        "MN0006": { "gl": "18260", "name": "Bancrecer 2450 Bs.", "currency": "VES", "category": "bancos_nacionales" },
+        "MN0007": { "gl": "18270", "name": "Bancrecer 2467 Bs.", "currency": "VES", "category": "bancos_nacionales" },
+        "MN0008": { "gl": "18280", "name": "BDV 5187 Bs. (Pago Móvil)", "currency": "VES", "category": "bancos_nacionales" },
+        "MN0012": { "gl": "18290", "name": "UBII", "currency": "VES", "category": "bancos_nacionales" },
+        "MN0030": { "gl": "18130", "name": "Caja tienda ventas Bs.", "currency": "VES", "category": "caja" },
+        "ME0030": { "gl": "18140", "name": "Caja tienda ventas $", "currency": "USD", "category": "caja" },
+        "ME0006": { "gl": null, "name": "Zelle USD (Wells Fargo)", "currency": "USD", "category": "bancos_extranjeros", "_nota": "GL pendiente de confirmar" }
+      }
+    },
+    "FQ28": {
+      "store_name": "FQ28 - Marqués El Unicentro",
+      "accounts": {
+        "MN0001": { "gl": "18210", "name": "BDV 8139 Bs.", "currency": "VES", "category": "bancos_nacionales" },
+        "MN0002": { "gl": "18220", "name": "Bancrecer 5474 Bs.", "currency": "VES", "category": "bancos_nacionales" },
+        "MN0028": { "gl": "18290", "name": "UBII 6249 Bs", "currency": "VES", "category": "bancos_nacionales" },
+        "MN0029": { "gl": "18291", "name": "UBII 6442 * Bs", "currency": "VES", "category": "bancos_nacionales" },
+        "MN0030": { "gl": "18130", "name": "Caja tienda ventas Bs.", "currency": "VES", "category": "caja" },
+        "MN0031": { "gl": "18160", "name": "Caja transitoria tienda ventas Bs.", "currency": "VES", "category": "caja" },
+        "MN0032": { "gl": "18292", "name": "UBII 4 FQ-28", "currency": "VES", "category": "bancos_nacionales" },
+        "MN0033": { "gl": "18295", "name": "UBII 7 FQ-28", "currency": "VES", "category": "bancos_nacionales" },
+        "MN0098": { "gl": "18298", "name": "Operaciones en Tránsito", "currency": "VES", "category": "bancos_nacionales" },
+        "ME0002": { "gl": "18310", "name": "Bancrecer $", "currency": "USD", "category": "bancos_nacionales_divisas" },
+        "ME0005": { "gl": "18410", "name": "Zelle Bofa $ *", "currency": "USD", "category": "bancos_extranjeros" },
+        "ME0030": { "gl": "18140", "name": "Caja tienda ventas $", "currency": "USD", "category": "caja" },
+        "ME0031": { "gl": "18170", "name": "Caja transitoria tienda ventas $", "currency": "USD", "category": "caja" },
+        "ME0035": { "gl": "18150", "name": "Banco Bóveda $", "currency": "USD", "category": "caja" }
+      }
+    },
+    "FQ88": {
+      "store_name": "FQ88 - La Candelaria",
+      "_nota": "GL accounts pendientes de confirmar con CoA de FQ88",
+      "accounts": {
+        "MN0001": { "gl": null, "name": "Bancamiga 0240 Bs.", "currency": "VES", "category": "bancos_nacionales" },
+        "MN0002": { "gl": null, "name": "Bancamiga 9379 Bs. *", "currency": "VES", "category": "bancos_nacionales" },
+        "MN0003": { "gl": null, "name": "BDV 9127 Bs.", "currency": "VES", "category": "bancos_nacionales" },
+        "MN0004": { "gl": null, "name": "BDV 7191 Bs. *", "currency": "VES", "category": "bancos_nacionales" },
+        "MN0005": { "gl": null, "name": "Bancrecer 2558 Bs.", "currency": "VES", "category": "bancos_nacionales" },
+        "MN0007": { "gl": null, "name": "BDV Pago Movil 5145", "currency": "VES", "category": "bancos_nacionales" },
+        "MN0028": { "gl": null, "name": "Ubii Bank", "currency": "VES", "category": "bancos_nacionales" },
+        "MN0030": { "gl": "18130", "name": "Caja tienda ventas Bs.", "currency": "VES", "category": "caja" },
+        "ME0030": { "gl": "18140", "name": "Caja tienda ventas $", "currency": "USD", "category": "caja" },
+        "ME0005": { "gl": null, "name": "Zelle USD", "currency": "USD", "category": "bancos_extranjeros" }
+      }
+    }
+  },
+  "gl_structure": {
+    "18100": "Caja (header)",
+    "18110": "Caja chica VEB",
+    "18120": "Caja chica $",
+    "18130": "Caja tienda ventas VEB",
+    "18140": "Caja tienda ventas $",
+    "18150": "Bóveda $",
+    "18160": "Caja tránsito tienda ventas VEB",
+    "18170": "Caja tránsito tienda ventas $",
+    "18199": "Total Caja",
+    "18200": "Bancos Nacionales Bolívares (header)",
+    "18210": "Banco principal Bs.",
+    "18220": "Banco secundario Bs.",
+    "18230": "Banco terciario Bs.",
+    "18240": "Banco cuarto Bs.",
+    "18250": "Banco quinto Bs.",
+    "18260": "Banco sexto Bs.",
+    "18270": "Banco séptimo Bs.",
+    "18280": "Banco octavo Bs.",
+    "18290": "UBII principal",
+    "18291": "UBII secundario",
+    "18292": "UBII terciario",
+    "18295": "UBII cuarto",
+    "18298": "Operaciones en Tránsito",
+    "18299": "Total Bancos Nacionales",
+    "18300": "Bancos Nacionales Divisas (header)",
+    "18310": "Banco divisas principal",
+    "18399": "Total Bancos Nacionales Divisas",
+    "18400": "Bancos Extranjeros Divisas (header)",
+    "18410": "Banco extranjero principal",
+    "18499": "Total Bancos Extranjeros Divisas",
+    "18998": "Total Bancos",
+    "18999": "Total Caja y Bancos"
+  }
+}

package/lib/bc-client.js

@@ -530,6 +530,149 @@ export class BCClient {
     return filters.top ? this.apiCall(url) : this.apiCallAllPages(url);
   }
 
+  // ── Sales Analysis Methods ──────────────────────────────────────
+
+  async getSalesInvoicesExpanded(companyId, startDate, endDate) {
+    const url = this.buildApiUrl(companyId, 'salesInvoices', {
+      $filter: `postingDate ge ${startDate} and postingDate le ${endDate}`,
+      $orderby: 'postingDate desc',
+      $expand: 'salesInvoiceLines',
+    });
+    return this.apiCallAllPages(url);
+  }
+
+  async getSalesInvoicesWithLines(companyId, startDate, endDate) {
+    const expandedInvoices = await this.getSalesInvoicesExpanded(companyId, startDate, endDate);
+    const invoices = [];
+    const lines = [];
+
+    for (const inv of expandedInvoices) {
+      const { salesInvoiceLines, ...invoiceData } = inv;
+      invoices.push(invoiceData);
+
+      for (const line of (salesInvoiceLines || [])) {
+        lines.push({
+          ...line,
+          postingDate: inv.postingDate,
+          invoiceDate: inv.invoiceDate,
+          documentNo: inv.number,
+          customerName: inv.customerName,
+          amount: line.amountExcludingTax || line.netAmount || 0,
+        });
+      }
+    }
+
+    return { invoices, lines };
+  }
+
+  async getItemsCatalog(companyId) {
+    const url = this.buildApiUrl(companyId, 'items', {
+      $select: 'id,number,displayName,type,unitPrice,unitCost,itemCategoryCode',
+    });
+    return this.apiCallAllPages(url);
+  }
+
+  async getSalesStoreData(storeCode, startDate, endDate, exchangeRates = null) {
+    const stores = resolveStores([storeCode]);
+    const store = stores[0];
+
+    logger.info(`Fetching sales data for ${store.name}: ${startDate} to ${endDate}`);
+
+    const salesData = await this.getSalesInvoicesWithLines(store.companyId, startDate, endDate);
+    const items = await this.getItemsCatalog(store.companyId);
+
+    // Revenue from GL (40000-49999) for authoritative USD amounts
+    const revenueEntries = await this.getRevenueEntries(store.companyId, startDate, endDate);
+    const glRevenue = { total_usd: 0, breakdown: {} };
+    for (const e of revenueEntries) {
+      const amount = (e.creditAmount || 0) - (e.debitAmount || 0);
+      glRevenue.total_usd += amount;
+      const acct = e.accountNumber;
+      glRevenue.breakdown[acct] = (glRevenue.breakdown[acct] || 0) + amount;
+    }
+    for (const acct of Object.keys(glRevenue.breakdown)) {
+      glRevenue.breakdown[acct] = Math.round(glRevenue.breakdown[acct] * 100) / 100;
+    }
+    glRevenue.total_usd = Math.round(glRevenue.total_usd * 100) / 100;
+
+    // Exchange rates
+    if (!exchangeRates) {
+      try {
+        exchangeRates = await this.getExchangeRates(storeCode);
+      } catch (err) {
+        logger.warn('Could not fetch exchange rates:', err.message);
+        exchangeRates = [];
+      }
+    }
+
+    const periodRate = this.getExchangeRateForDate(exchangeRates, endDate);
+
+    // Build items lookup
+    const itemsMap = {};
+    for (const item of items) {
+      itemsMap[item.number] = item;
+    }
+
+    // Enrich lines with item data and converted costs
+    for (const line of salesData.lines) {
+      const itemNo = line.lineObjectNumber || line.itemId;
+      const item = itemsMap[itemNo];
+      if (item) {
+        line.itemCategoryCode = item.itemCategoryCode;
+        line.unitCostUSD = item.unitCost || 0;
+        line.displayName = item.displayName || line.description;
+      }
+      if (!line.displayName) {
+        line.displayName = line.description || 'Sin nombre';
+      }
+      line.itemNumber = line.lineObjectNumber || '';
+      line.unitCostUSD = line.unitCostUSD || 0;
+
+      if (exchangeRates.length > 0 && line.unitCostUSD) {
+        const rateForDate = this.getExchangeRateForDate(exchangeRates, line.postingDate || endDate);
+        const rate = rateForDate ? rateForDate.rate : (periodRate ? periodRate.rate : 0);
+        line.unitCostVES = line.unitCostUSD * rate;
+        line.exchangeRate = rate;
+      } else {
+        line.unitCostVES = 0;
+        line.exchangeRate = periodRate ? periodRate.rate : null;
+      }
+    }
+
+    return {
+      invoices: salesData.invoices,
+      lines: salesData.lines,
+      items,
+      itemsMap,
+      exchangeRate: periodRate,
+      glRevenue,
+      storeName: store.name,
+      storeCode: store.code,
+    };
+  }
+
+  async getAllSalesStoreData(storeCodes, startDate, endDate) {
+    const stores = resolveStores(storeCodes);
+    const results = {};
+
+    // Fetch exchange rates once (shared across all companies in same tenant)
+    let exchangeRates = [];
+    try {
+      exchangeRates = await this.getExchangeRates(stores[0].code);
+      logger.info(`Exchange rates loaded: ${exchangeRates.length} entries`);
+    } catch (err) {
+      logger.warn('Could not fetch exchange rates:', err.message);
+    }
+
+    // Fetch stores sequentially to avoid BC API rate limiting
+    for (const store of stores) {
+      const data = await this.getSalesStoreData(store.code, startDate, endDate, exchangeRates);
+      results[store.code] = data;
+    }
+
+    return results;
+  }
+
   async getCompanies() {
     const url = `${this.baseUrl}/${this.tenantId}/${this.environment}/api/v2.0/companies`;
     return this.apiCall(url);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fullqueso/mcp-bc-gastos",
-  "version": "1.14.2",
+  "version": "1.19.0",
   "description": "MCP server for Business Central operational expense analysis, bank reconciliation, POS reconciliation, accounts receivable/payable, multi-payment draft visibility, payroll, inventory cost analysis, and manager reports - Full Queso franchise stores",
   "main": "server.js",
   "bin": {