@fullqueso/mcp-bc-gastos 1.25.0 → 1.26.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # CHANGELOG
 
+## [1.26.0] — 2026-06-05
+
+### Added
+- **`get_cash_flow` — posición de caja + efecto cambiario sobre la caja VES (Fase 2 FX).** Los bancos/caja en bolívares reciben depósitos que se dolarizan a la tasa del día, pero el VES se devalúa ~0.75–1%/día y BC **no postea revaluación** → el USD en libros sobrestima la caja real. Nuevo bloque `cash_position` que revalúa el saldo VES a la tasa de fin de período. **No afecta el FCF** (queda 100% operativo; el efecto cambiario es un memo de balance).
+  - **Fuente:** `generalLedgerEntries` trae ambas monedas por cuenta — `debitAmount/creditAmount` = USD (libro) y `additionalCurrencyDebitAmount/additionalCurrencyCreditAmount` = VES (saldo físico). Nuevo método `bcClient.getCashGLBalances(companyId, asOfDate)` (acumulado a fecha, cuentas 18xxx, ambas monedas).
+  - **Métrica:** por cada cuenta VES, `usd_real = ves_balance / rate_end`; `fx_adjustment = usd_real − usd_book` (< 0 cuando el VES se devaluó). `cash_position` expone `ves {book_usd, real_usd, fx_adjustment, accounts[]}`, `usd {total_usd}`, `total_cash_book_usd`, `total_cash_real_usd`, `rate_end`, `month_devaluation_pct`. Insight automático cuantificando la sobrestimación.
+  - **Regla VES (estructural, confirmada por FP):** bancos VES = `18200–18299`; caja VEB = `18110/18130/18160`; resto de 18xxx = USD (sin ajuste, tenencia física en USD). Captura todas las cuentas VES sin mapear banco→GL por cuenta.
+  - Nuevo param `include_cash_position` (default `true`). Card HTML "Posición de Caja · Efecto Cambiario (VES)" en single/multi/consolidado. Solo se calcula para el período actual (es saldo a fin de período).
+  - **Verificado contra BC real (FQ88, 31-may-2026):** caja VES libro **$34,873** → real **$32,583** (a 554.43 VES/USD) → ajuste **−$2,290** (6.57%); caja total libro $35,310 → real $33,020; devaluación del mes **13.25%**. La regla estructural capturó las 10 cuentas VES (2 más que el sondeo manual: 18275, 18297). FCF intacto en $30,165.08.
+
+---
+
 ## [1.25.0] — 2026-06-05
 
 ### Added

package/lib/bc-client.js

@@ -316,6 +316,19 @@ export class BCClient {
     return this.apiCallAllPages(url);
   }
 
+  // Saldos acumulados (a fecha) de cuentas con AMBAS monedas: debit/creditAmount = USD (LCY)
+  // y additionalCurrency*Amount = VES (moneda adicional). Para revaluación de caja VES.
+  // postingDate le asOfDate (acumulado desde el inicio = saldo a la fecha).
+  async getCashGLBalances(companyId, asOfDate, accountMin = '18000', accountMax = '18999', maxPages = 60) {
+    const ed = this._sanitizeOData(asOfDate);
+    const url = this.buildApiUrl(companyId, 'generalLedgerEntries', {
+      $filter: `postingDate le ${ed} and accountNumber ge '${accountMin}' and accountNumber le '${accountMax}'`,
+      $select: 'accountNumber,description,debitAmount,creditAmount,additionalCurrencyDebitAmount,additionalCurrencyCreditAmount',
+      $orderby: 'postingDate desc',
+    });
+    return this.apiCallAllPages(url, maxPages);
+  }
+
   // Fetch revenue entries (40000-49999) - credit balance = income
   async getRevenueEntries(companyId, startDate, endDate) {
     return this.getGLEntries(companyId, startDate, endDate, '40000', '49999');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fullqueso/mcp-bc-gastos",
-  "version": "1.25.0",
+  "version": "1.26.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": {

package/tools/financials/cash-flow-html.js

@@ -38,6 +38,7 @@ ${renderWaterfall(s.fcf_bridge)}
 ${renderKpis(s)}
 ${renderWorkingCapital(s)}
 ${renderCapexCard(s)}
+${renderCashPositionCard(s)}
 ${comparison ? renderComparisonCard({ [code]: comparison }, result) : ''}
 `;
   return renderShell(`${s.store_code} · Cash Flow · ${result.period.label}`, header, body, result);
@@ -67,6 +68,7 @@ function renderMulti(result) {
     ${renderWaterfall(s.fcf_bridge)}
     ${renderKpis(s)}
     ${renderWorkingCapital(s)}
+    ${renderCashPositionCard(s)}
   </div>
 </details>`;
     })
@@ -78,6 +80,7 @@ ${renderStoresComparison(result)}
 ${con ? renderWaterfall(con.fcf_bridge) : ''}
 ${con ? renderKpis(con) : ''}
 ${con ? renderWorkingCapital(con) : ''}
+${con ? renderCashPositionCard(con) : ''}
 ${result.comparison ? renderComparisonCard(result.comparison, result) : ''}
 <div class="section-label">Detalle por tienda</div>
 ${blocks}
@@ -268,6 +271,28 @@ function renderCapexCard(s) {
 </div>`;
 }
 
+// Posición de caja + efecto cambiario sobre la caja VES (no afecta el FCF).
+function renderCashPositionCard(s) {
+  const cp = s.cash_position;
+  if (!cp || !cp.ves || !cp.ves.accounts.length) return '';
+  const adj = cp.ves.fx_adjustment;
+  const dev = cp.month_devaluation_pct != null ? ` · devaluación mes ${cp.month_devaluation_pct}%` : '';
+  const acctRows = cp.ves.accounts
+    .map((a) => `<div class="pnl-row sub"><span class="pnl-label">${esc(a.account)} ${esc(a.name || '')}${a.store ? ` <span class="pnl-acct">${esc(a.store)}</span>` : ''}</span><span class="pnl-amt ${a.fx_adjustment < 0 ? 'val-red' : ''}">${signed(a.fx_adjustment)}</span></div>`)
+    .join('');
+  return `<div class="card">
+  <div class="card-hd"><span class="card-icon">&#x1F4B1;</span><span class="card-title">Posición de Caja · Efecto Cambiario (VES)</span></div>
+  <div class="card-bd"><div class="pnl">
+    <div class="pnl-row"><span class="pnl-label">Caja VES — libro (USD)</span><span class="pnl-amt">${signed(cp.ves.book_usd)}</span></div>
+    <div class="pnl-row"><span class="pnl-label">Caja VES — real (a ${cp.rate_end} VES/USD)</span><span class="pnl-amt">${signed(cp.ves.real_usd)}</span></div>
+    <div class="pnl-row gross"><span class="pnl-label">= Ajuste cambiario no contabilizado${dev}</span><span class="pnl-amt ${adj < 0 ? 'val-red' : 'val-green'}">${signed(adj)}</span></div>
+    <div class="pnl-section-hd">Por cuenta VES</div>
+    ${acctRows}
+    <div class="pnl-row total"><span class="pnl-label">Caja total — libro ${signed(cp.total_cash_book_usd)} → real</span><span class="pnl-amt">${signed(cp.total_cash_real_usd)}</span></div>
+  </div></div>
+</div>`;
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Comparativo de tiendas (multi)
 // ─────────────────────────────────────────────────────────────────────────────

package/tools/financials/cash-flow.js

@@ -53,7 +53,9 @@ export const cashFlowTool = {
     'Parte del EBIT (igual que get_financial_statements), resta impuesto estimado (ISLR 34%), ajusta por capital de trabajo ' +
     '(7 líneas desde net-change G/L: Δ cuentas por cobrar, Δ impuestos corrientes, Δ prepagados, Δ inventario, Δ cuentas por pagar, ' +
     'Δ impuestos por pagar, Δ pasivos laborales) para obtener el flujo de caja operativo (CFO), y resta CapEx (PP&E 11110-12240) ' +
-    'para el FCF. Reporta también D&A y EBITDA (EBIT + D&A). Incluye NOPAT, margen FCF, status ' +
+    'para el FCF. Reporta también D&A y EBITDA (EBIT + D&A). Incluye además la posición de caja con efecto cambiario: revalúa ' +
+    'el saldo de las cuentas de banco/caja en bolívares (VES) a la tasa de fin de período y muestra cuánto sobrestiman los libros ' +
+    'la caja real por la devaluación no contabilizada (no afecta el FCF). Incluye NOPAT, margen FCF, status ' +
     '(healthy/positive_low/negative_watch/' +
     'negative_critical), bridge tipo waterfall e insights automáticos. Multi-tienda calcula consolidado. Con render_html=true ' +
     'genera un dashboard HTML (lo guarda en ~/Downloads y retorna la ruta). Úsalo cuando el usuario pida flujo de caja, ' +
@@ -81,6 +83,11 @@ export const cashFlowTool = {
         description: 'Si true, incluye comparación con el mes anterior (MoM). Default: false.',
         default: false,
       },
+      include_cash_position: {
+        type: 'boolean',
+        description: 'Si true (default), calcula la posición de caja y el efecto cambiario sobre la caja VES (revaluación del saldo en bolívares a la tasa de fin de período). No afecta el FCF.',
+        default: true,
+      },
       render_html: {
         type: 'boolean',
         description: 'Si true, genera el dashboard HTML, lo guarda en ~/Downloads y retorna la ruta. Default: false.',
@@ -112,12 +119,22 @@ export async function getCashFlow(bcClient, params = {}) {
 
   const compare = !!params.compare_previous;
   const prevRange = compare ? previousMonthRange(start, end) : null;
-
-  // ── Fetch en paralelo: cash flow actual + previo por tienda + exchange rate ──
+  const includeCashPosition = params.include_cash_position !== false; // default true
+
+  // Tipo de cambio VES: serie completa (compartida); se obtiene una vez y se pasa a las
+  // tiendas (la posición de caja la usa para revaluar el saldo VES a la tasa de fin de mes).
+  const rates = await bcClient.getExchangeRates(stores[0].code).catch((err) => {
+    logger.warn(`[cash-flow] exchange rate fetch failed: ${err.message}`);
+    return null;
+  });
+  const fx = rates ? bcClient.getExchangeRateForDate(rates, end) : null;
+
+  // ── Fetch en paralelo: cash flow actual + previo por tienda ──
+  // La posición de caja (FX) solo se calcula para el período actual (es saldo a fin de período).
   const tasks = [];
   for (const s of stores) {
     tasks.push(
-      buildStoreCashFlow(bcClient, s, start, end)
+      buildStoreCashFlow(bcClient, s, start, end, { rates, includeCashPosition })
         .then((cf) => ({ kind: 'current', code: s.code, cf }))
         .catch((err) => ({ kind: 'current', code: s.code, error: err.message, store: s }))
     );
@@ -125,24 +142,14 @@ export async function getCashFlow(bcClient, params = {}) {
   if (compare) {
     for (const s of stores) {
       tasks.push(
-        buildStoreCashFlow(bcClient, s, prevRange.start, prevRange.end)
+        buildStoreCashFlow(bcClient, s, prevRange.start, prevRange.end, { rates, includeCashPosition: false })
           .then((cf) => ({ kind: 'previous', code: s.code, cf }))
           .catch((err) => ({ kind: 'previous', code: s.code, error: err.message }))
       );
     }
   }
 
-  const fxTask = bcClient
-    .getExchangeRates(stores[0].code)
-    .then((rates) => bcClient.getExchangeRateForDate(rates, end))
-    .catch((err) => {
-      logger.warn(`[cash-flow] exchange rate fetch failed: ${err.message}`);
-      return null;
-    });
-
-  const settled = await Promise.all([fxTask, ...tasks]);
-  const fx = settled[0];
-  const fetched = settled.slice(1);
+  const fetched = await Promise.all(tasks);
 
   // ── Partición current / previous ──
   const storesOut = {};
@@ -201,13 +208,16 @@ export async function getCashFlow(bcClient, params = {}) {
 // Cash flow de una tienda
 // ─────────────────────────────────────────────────────────────────────────────
 
-async function buildStoreCashFlow(bcClient, store, start, end) {
+async function buildStoreCashFlow(bcClient, store, start, end, opts = {}) {
   logger.info(`[cash-flow] ${store.code}: ${start} → ${end}`);
 
-  // P&L base (income/cogs/EBIT) en paralelo con working capital + capex
-  const [{ financials }, wc] = await Promise.all([
+  // P&L base (income/cogs/EBIT) en paralelo con working capital + capex + posición de caja (FX)
+  const [{ financials }, wc, cashPosition] = await Promise.all([
     fetchStoreFinancials(bcClient, store, start, end),
     fetchWorkingCapitalAndCapex(bcClient, store.companyId, start, end),
+    opts.includeCashPosition && opts.rates
+      ? fetchCashPosition(bcClient, store.companyId, start, end, opts.rates)
+      : Promise.resolve(null),
   ]);
 
   return assembleCashFlow(
@@ -228,11 +238,87 @@ async function buildStoreCashFlow(bcClient, store, start, end) {
       delta_labor: wc.delta_labor,
       capex: wc.capex,
       capex_accounts: wc.capex_accounts,
+      cash_position: cashPosition,
       warnings: wc.warnings,
     }
   );
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Posición de caja + efecto cambiario (devaluación VES) — READ-ONLY, NO afecta el FCF.
+// Regla VES (confirmada por FP, estructura compartida entre tiendas):
+//   bancos VES = 18200–18299 ; caja VEB = 18110/18130/18160. Resto de 18xxx = USD.
+// El saldo VES vive en additionalCurrency (VES); el USD libro (debit/credit) quedó "stale"
+// a tasas históricas. fx_adjustment = USD_real (VES/tasa_fin) − USD_libro (< 0 si VES se devaluó).
+// ─────────────────────────────────────────────────────────────────────────────
+
+const VES_CASH_ACCOUNTS = new Set(['18110', '18130', '18160']);
+function isVesCashAccount(accountNumber) {
+  const n = parseInt(accountNumber, 10);
+  return (n >= 18200 && n <= 18299) || VES_CASH_ACCOUNTS.has(String(accountNumber));
+}
+
+async function fetchCashPosition(bcClient, companyId, start, end, rates) {
+  const entries = await bcClient.getCashGLBalances(companyId, end).catch((e) => {
+    logger.warn(`[cash-flow] cash balances fetch failed: ${e.message}`);
+    return null;
+  });
+  if (entries == null) return null;
+
+  const rateEnd = (bcClient.getExchangeRateForDate(rates, end) || {}).rate || null;
+  const rateStart = (bcClient.getExchangeRateForDate(rates, start) || {}).rate || null;
+  if (!rateEnd) return null;
+
+  const warnings = [];
+  if (entries._truncated) warnings.push('G/L de caja/bancos truncado — saldos pueden estar incompletos.');
+
+  // Acumular por cuenta: USD libro (debit−credit) y VES (additionalCurrency debit−credit)
+  // (no se usa e.description como nombre: es la nota de la transacción, no el nombre de la cuenta)
+  const acc = {};
+  for (const e of entries) {
+    const a = e.accountNumber;
+    if (!acc[a]) acc[a] = { usd: 0, ves: 0 };
+    acc[a].usd += (e.debitAmount || 0) - (e.creditAmount || 0);
+    acc[a].ves += (e.additionalCurrencyDebitAmount || 0) - (e.additionalCurrencyCreditAmount || 0);
+  }
+
+  const vesAccounts = [];
+  let vesBook = 0, vesReal = 0, usdTotal = 0;
+  for (const [a, v] of Object.entries(acc)) {
+    const usdBook = round2(v.usd);
+    if (Math.abs(usdBook) < 0.005 && Math.abs(v.ves) < 0.5) continue; // saldo cero
+    if (isVesCashAccount(a)) {
+      const usdReal = round2(v.ves / rateEnd);
+      vesBook += usdBook;
+      vesReal += usdReal;
+      const n = parseInt(a, 10);
+      vesAccounts.push({
+        account: a, name: n >= 18200 && n <= 18299 ? 'Banco VES' : 'Caja VES',
+        usd_book: usdBook, ves_balance: round2(v.ves), usd_real: usdReal,
+        fx_adjustment: round2(usdReal - usdBook),
+      });
+    } else {
+      usdTotal += usdBook; // cuentas USD: tenencia física en USD → sin ajuste
+    }
+  }
+  vesAccounts.sort((x, y) => x.fx_adjustment - y.fx_adjustment); // mayor pérdida primero
+
+  vesBook = round2(vesBook);
+  vesReal = round2(vesReal);
+  usdTotal = round2(usdTotal);
+
+  return {
+    rate_end: round2(rateEnd),
+    rate_start: rateStart ? round2(rateStart) : null,
+    month_devaluation_pct: rateStart && rateStart > 0 ? round2((rateEnd / rateStart - 1) * 100) : null,
+    ves: { book_usd: vesBook, real_usd: vesReal, fx_adjustment: round2(vesReal - vesBook), accounts: vesAccounts },
+    usd: { total_usd: usdTotal },
+    total_cash_book_usd: round2(vesBook + usdTotal),
+    total_cash_real_usd: round2(vesReal + usdTotal),
+    warnings,
+  };
+}
+
 // Buckets del balance general (Chart of Accounts real de BC), por rango de cuenta.
 // REGLA UNIVERSAL de impacto en caja: delta = −Σ(debit − credit) sobre el rango.
 //   - Activo que sube (debit) → −Σ < 0 = uso de caja.
@@ -359,7 +445,8 @@ function assembleCashFlow(meta, c) {
   const status = fcfStatus(fcf, fcfPct, ebit);
   const wc = { delta_ar, delta_taxes, delta_prepaid, delta_inventory, delta_ap, delta_taxes_payable, delta_labor };
   const bridge = buildBridge({ ebit, tax, nopat, ...wc, cfo, capex, fcf });
-  const insights = buildInsights({ ebit, ...wc, da, capex, fcf, fcfPct, status, warnings: c.warnings || [] });
+  const cash_position = c.cash_position || null;
+  const insights = buildInsights({ ebit, ...wc, da, capex, fcf, fcfPct, status, cash_position, warnings: c.warnings || [] });
 
   return {
     store_code: meta.store_code,
@@ -376,6 +463,7 @@ function assembleCashFlow(meta, c) {
     cfo: { amount: cfo, pct: cfoPct },
     capex: { amount: capex, accounts: c.capex_accounts || {} },
     fcf: { amount: fcf, pct: fcfPct, status },
+    cash_position,
     fcf_bridge: bridge,
     insights,
   };
@@ -406,9 +494,23 @@ function buildBridge({ ebit, tax, nopat, delta_ar, delta_taxes, delta_prepaid, d
   ];
 }
 
-function buildInsights({ ebit, delta_ar, delta_taxes, delta_prepaid, delta_inventory, delta_ap, delta_taxes_payable, delta_labor, da, capex, fcf, fcfPct, status, warnings }) {
+function buildInsights({ ebit, delta_ar, delta_taxes, delta_prepaid, delta_inventory, delta_ap, delta_taxes_payable, delta_labor, da, capex, fcf, fcfPct, status, cash_position, warnings }) {
   const insights = [];
 
+  // Efecto cambiario sobre caja VES — el saldo en libros sobrestima la caja real porque
+  // los bolívares no se han revaluado a la tasa de cierre (devaluación no contabilizada).
+  if (cash_position && cash_position.ves.book_usd > 0) {
+    const adj = cash_position.ves.fx_adjustment;
+    const pct = round2((adj / cash_position.ves.book_usd) * 100);
+    if (adj < 0 && Math.abs(adj) >= 1) {
+      const dev = cash_position.month_devaluation_pct != null ? ` (devaluación del mes ${cash_position.month_devaluation_pct}%)` : '';
+      insights.push(
+        `Caja VES sobrestimada $${fmtAbs(adj)} (${Math.abs(pct)}%) por devaluación no contabilizada — ` +
+        `valor real $${fmtAbs(cash_position.total_cash_real_usd)} vs $${fmtAbs(cash_position.total_cash_book_usd)} en libros${dev}.`
+      );
+    }
+  }
+
   // Mayor driver negativo entre los usos de capital de trabajo (7 líneas)
   const uses = [
     { key: 'delta_inventory', label: 'Inventario', val: delta_inventory },
@@ -453,6 +555,7 @@ function buildInsights({ ebit, delta_ar, delta_taxes, delta_prepaid, delta_inven
   }
 
   insights.push(...warnings);
+  if (cash_position && cash_position.warnings) insights.push(...cash_position.warnings);
 
   if (insights.length === 0) {
     insights.push('Flujo de caja dentro de rangos normales.');
@@ -494,11 +597,39 @@ function consolidateCashFlow(storeObjs) {
       delta_labor: sum((o) => o.working_capital.delta_labor || 0),
       capex: sum((o) => o.capex.amount),
       capex_accounts,
+      cash_position: consolidateCashPosition(storeObjs),
       warnings: allWarnings,
     }
   );
 }
 
+// Consolida la posición de caja (FX) sumando escalares y concatenando cuentas VES.
+function consolidateCashPosition(storeObjs) {
+  const positions = storeObjs.map((o) => o.cash_position).filter(Boolean);
+  if (!positions.length) return null;
+  const sumP = (fn) => round2(positions.reduce((s, p) => s + fn(p), 0));
+  const accounts = [];
+  for (const o of storeObjs) {
+    if (!o.cash_position) continue;
+    for (const a of o.cash_position.ves.accounts) accounts.push({ ...a, store: o.store_code });
+  }
+  accounts.sort((x, y) => x.fx_adjustment - y.fx_adjustment);
+  const vesBook = sumP((p) => p.ves.book_usd);
+  const vesReal = sumP((p) => p.ves.real_usd);
+  const usdTotal = sumP((p) => p.usd.total_usd);
+  const ref = positions[0]; // tasa VES compartida entre tiendas
+  return {
+    rate_end: ref.rate_end,
+    rate_start: ref.rate_start,
+    month_devaluation_pct: ref.month_devaluation_pct,
+    ves: { book_usd: vesBook, real_usd: vesReal, fx_adjustment: round2(vesReal - vesBook), accounts },
+    usd: { total_usd: usdTotal },
+    total_cash_book_usd: round2(vesBook + usdTotal),
+    total_cash_real_usd: round2(vesReal + usdTotal),
+    warnings: [],
+  };
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Comparación MoM (compacta)
 // ─────────────────────────────────────────────────────────────────────────────