@fullqueso/mcp-bc-gastos 1.26.0 → 1.27.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # CHANGELOG
 
+## [1.27.0] — 2026-06-05
+
+### Changed
+- **`get_cash_flow` — efecto cambiario revaluado contra el SALDO REAL del banco + asiento sugerido (corrige v1.26.0).** FP detectó que el saldo VES del GL está inflado por **backlog de conciliación** (transacciones que el banco ya procesó pero BC no postea). Ej FQ88: GL cuenta 18250 = 12.44M VES vs saldo real del banco = 1.19M VES. Por eso el `fx_adjustment` de v1.26.0 (sobre GL, −$2,290) **sobrestimaba** la pérdida real. Ahora se revalúa el **saldo real** (`BankAccReconciliation.StatementEndingBalance`, en VES) y se aísla el backlog.
+  - **Matemática robusta:** por cuenta, `implied_rate = gl_ves/gl_usd` (tasa promedio histórica), `fx_real = stmt_ves × (1/rate_close − 1/implied_rate)` — escala por el saldo **real**, no el GL inflado. `recon_gap = gl_ves − stmt_ves` se reporta aparte (backlog a postear, NO es FX).
+  - **3 buckets de cuentas VES:** (1) banco real con statement → entra al total y al **asiento sugerido**; (2) banco sin statement → provisional, flag, fuera del total; (3) ajuste/tránsito (lista explícita en config: 18275, 18297) → solo informativo. Flag de tasa implícita atípica.
+  - **Asiento sugerido de diferencial cambiario** (READ-ONLY texto, cuadra DR=CR): débito Diferencial Cambiario / crédito cada banco VES por su `fx_real`. Es la hoja de trabajo del cierre.
+  - Nuevo módulo compartido `tools/financials/fx-cash.js` (computeCashPosition, buildFxJournal, consolidateCashPositions) — reutilizable por get_cash_flow y, a futuro, por el paso de cierre-mensual (Fase 3B). Nuevo `bcClient.getBankStatementBalances` (OData V4 `BankAccReconciliation`, elige la statement ≤ fin de período). Completado el mapeo banco→GL de FQ88 en `config/bank-gl-map.json` (desde fq-239-audit) + lista `adjustment_accounts_ves`.
+  - El bloque `cash_position` cambia de forma: `bank_accounts`/`pending_no_statement`/`informational` + `totals` (solo bucket 1) + `fx_journal` + `gl_basis` (referencia v1.26.0). Insight separa "brecha de conciliación" de "efecto cambiario sobre caja real". **El FCF sigue intacto** (el FX es memo de balance).
+  - **Verificado contra BC real (FQ88, mayo 2026):** GL libro $34,880 / FX sobre GL −$2,290 (v1.26.0, sobrestimado) → **caja real $5,884 / FX real −$500.89** (correcto); brecha de conciliación 14.36M VES (~$25,897, backlog). Asiento cuadra ($500.89). FCF intacto.
+
+### Pendiente (Fase 3B)
+- `generate_fx_revaluation` en cierre-mensual: emitir el asiento de diferencial cambiario integrado al journal de cierre (reusa el módulo `fx-cash.js`).
+
+---
+
 ## [1.26.0] — 2026-06-05
 
 ### Added

package/config/bank-gl-map.json

@@ -41,18 +41,18 @@
     },
     "FQ88": {
       "store_name": "FQ88 - La Candelaria",
-      "_nota": "GL accounts pendientes de confirmar con CoA de FQ88",
+      "_nota": "GL confirmados 2026-06-05 desde fq-239-audit/data/fq_bancos_all.json (consolidacion_por_banco).",
       "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" },
+        "MN0001": { "gl": "18210", "name": "Bancamiga 0240 Bs.", "currency": "VES", "category": "bancos_nacionales" },
+        "MN0002": { "gl": "18220", "name": "Bancamiga 9379 Bs. *", "currency": "VES", "category": "bancos_nacionales" },
+        "MN0003": { "gl": "18230", "name": "BDV 9127 Bs.", "currency": "VES", "category": "bancos_nacionales" },
+        "MN0004": { "gl": "18240", "name": "BDV 7191 Bs. *", "currency": "VES", "category": "bancos_nacionales" },
+        "MN0005": { "gl": "18250", "name": "Bancrecer 2558 Bs.", "currency": "VES", "category": "bancos_nacionales" },
+        "MN0007": { "gl": "18270", "name": "BDV Pago Movil 5145", "currency": "VES", "category": "bancos_nacionales" },
+        "MN0028": { "gl": "18290", "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" }
+        "ME0005": { "gl": "18410", "name": "Zelle USD", "currency": "USD", "category": "bancos_extranjeros" }
       }
     }
   },
@@ -89,5 +89,7 @@
     "18499": "Total Bancos Extranjeros Divisas",
     "18998": "Total Bancos",
     "18999": "Total Caja y Bancos"
-  }
+  },
+  "_adjustment_accounts_nota": "Cuentas VES de ajuste/tránsito (NO son bancos reales, no tienen statement). Se tratan como informativas en la revaluación cambiaria (fuera del total de pérdida y del asiento sugerido). FP 2026-06-05.",
+  "adjustment_accounts_ves": ["18275", "18297"]
 }

package/lib/bc-client.js

@@ -329,6 +329,38 @@ export class BCClient {
     return this.apiCallAllPages(url, maxPages);
   }
 
+  // Saldos REALES de banco (statement) por cuenta, vía BankAccReconciliation (OData V4).
+  // Por cada BankAccountNo elige la statement más reciente con StatementDate ≤ asOfDate
+  // (los bancos tienen varias statements semanales + cierre de mes). Devuelve un mapa
+  // { 'FQ88-MN0005': { ending: 1190029.52, statementDate, statementNo, stale } }.
+  async getBankStatementBalances(storeCode, asOfDate) {
+    const url = this.buildODataUrl(storeCode, 'BankAccReconciliation', {
+      $select: 'BankAccountNo,StatementNo,StatementDate,StatementEndingBalance',
+    });
+    const rows = await this.odataCallAllPages(url);
+    const list = rows.value || rows || [];
+    const ad = String(asOfDate);
+    const byAcct = {};
+    for (const r of list) {
+      const acct = r.BankAccountNo;
+      if (!acct) continue;
+      const date = r.StatementDate ? String(r.StatementDate) : '';
+      // Preferir statements ≤ asOfDate (la más reciente). Si no hay, usar la más antigua futura (stale).
+      const cur = byAcct[acct];
+      const within = date && date <= ad;
+      if (!cur) {
+        byAcct[acct] = { ending: r.StatementEndingBalance || 0, statementDate: date, statementNo: r.StatementNo, stale: !within };
+      } else if (within) {
+        // entre las ≤ asOfDate, quedarse con la fecha mayor
+        if (cur.stale || date > cur.statementDate) byAcct[acct] = { ending: r.StatementEndingBalance || 0, statementDate: date, statementNo: r.StatementNo, stale: false };
+      } else if (cur.stale && date < cur.statementDate) {
+        // todas futuras: quedarse con la más cercana (menor fecha futura)
+        byAcct[acct] = { ending: r.StatementEndingBalance || 0, statementDate: date, statementNo: r.StatementNo, stale: true };
+      }
+    }
+    return byAcct;
+  }
+
   // 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.26.0",
+  "version": "1.27.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

@@ -271,24 +271,52 @@ function renderCapexCard(s) {
 </div>`;
 }
 
-// Posición de caja + efecto cambiario sobre la caja VES (no afecta el FCF).
+// Posición de caja · conciliación · efecto cambiario (base saldo REAL del banco). 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;
+  if (!cp || !cp.bank_accounts) return '';
+  const t = cp.totals;
   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('');
+  const st = (store) => (store ? ` <span class="pnl-acct">${esc(store)}</span>` : '');
+
+  // Bucket 1 — bancos con statement: GL vs real, brecha, tasa implícita, fx_real
+  const bankRows = cp.bank_accounts.map((b) => {
+    const flag = b.flags && b.flags.length ? ` <span class="pnl-acct">⚠ ${esc(b.flags.join(','))}</span>` : '';
+    return `<div class="pnl-row sub">
+      <span class="pnl-label">${esc(b.account)} ${esc(b.name || '')}${st(b.store)}${flag}<br>
+        <span class="kpi-cell-sub">GL ${fmt(b.gl_ves)} → real ${fmt(b.stmt_ves)} VES · impl ${b.implied_rate || '—'} vs ${cp.rate_end}</span></span>
+      <span class="pnl-amt ${b.fx_real < 0 ? 'val-red' : 'val-green'}">${signed(b.fx_real)}</span>
+    </div>`;
+  }).join('');
+
+  // Bucket 3 — ajuste/tránsito (informativo)
+  const infoRows = (cp.informational || []).map((b) =>
+    `<div class="pnl-row sub"><span class="pnl-label">${esc(b.account)} ${esc(b.name || '')}${st(b.store)} <span class="pnl-acct">informativo</span></span><span class="pnl-amt">${signed(b.fx_theoretical)}</span></div>`
+  ).join('');
+  // Bucket 2 — sin statement (provisional)
+  const pendRows = (cp.pending_no_statement || []).map((b) =>
+    `<div class="pnl-row sub"><span class="pnl-label">${esc(b.account)} ${esc(b.name || '')}${st(b.store)} <span class="pnl-acct">sin statement</span></span><span class="pnl-amt">${signed(b.fx_provisional)}</span></div>`
+  ).join('');
+
+  // Asiento sugerido (solo bucket 1)
+  const j = cp.fx_journal;
+  const jRows = (j && j.rows || []).map((r) =>
+    `<div class="pnl-row sub"><span class="pnl-label">${esc(String(r.account))} <span class="pnl-acct">${esc(r.account_type)}</span></span><span class="pnl-amt">${r.debit_usd ? 'DR ' + signed(r.debit_usd) : 'CR ' + signed(r.credit_usd)}</span></div>`
+  ).join('');
+
+  const reconUsd = cp.rate_end ? t.recon_gap_ves / cp.rate_end : 0;
   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-hd"><span class="card-icon">&#x1F4B1;</span><span class="card-title">Posición de Caja · Conciliación · 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 class="pnl-row"><span class="pnl-label">Caja VES real (statement, a ${cp.rate_end} VES/USD)</span><span class="pnl-amt">${signed(t.ves_real_usd)}</span></div>
+    <div class="pnl-row"><span class="pnl-label">Brecha de conciliación (backlog a postear, NO es FX)</span><span class="pnl-amt">${fmt(t.recon_gap_ves)} VES (~${signed(reconUsd)})</span></div>
+    <div class="pnl-row gross"><span class="pnl-label">= Efecto cambiario sobre caja real${dev}</span><span class="pnl-amt ${t.fx_real < 0 ? 'val-red' : 'val-green'}">${signed(t.fx_real)}</span></div>
+    <div class="pnl-row sub"><span class="pnl-label">(ref. libro GL: ${signed(cp.gl_basis.ves_book_usd)} · FX s/GL ${signed(cp.gl_basis.fx_on_gl)})</span><span class="pnl-amt"></span></div>
+    <div class="pnl-section-hd">Bancos VES (saldo real vs libro)</div>
+    ${bankRows}
+    ${pendRows ? `<div class="pnl-section-hd">Sin statement (provisional)</div>${pendRows}` : ''}
+    ${infoRows ? `<div class="pnl-section-hd">Ajustes / Tránsito (informativo, fuera del total)</div>${infoRows}` : ''}
+    ${jRows ? `<div class="pnl-section-hd">Asiento sugerido — Diferencial Cambiario ${j.balanced ? '✓ cuadra' : '✗'}</div>${jRows}` : ''}
   </div></div>
 </div>`;
 }

package/tools/financials/cash-flow.js

@@ -39,6 +39,7 @@ import { round2 } from '../../utils/currency-converter.js';
 import { logger } from '../../utils/logger.js';
 import { fetchStoreFinancials, periodLabel, previousMonthRange } from './statements.js';
 import { buildCashFlowHTML } from './cash-flow-html.js';
+import { computeCashPosition, consolidateCashPositions } from './fx-cash.js';
 
 const TAX_RATE = 0.34; // ISLR Venezuela estándar (estimado)
 
@@ -216,7 +217,7 @@ async function buildStoreCashFlow(bcClient, store, start, end, opts = {}) {
     fetchStoreFinancials(bcClient, store, start, end),
     fetchWorkingCapitalAndCapex(bcClient, store.companyId, start, end),
     opts.includeCashPosition && opts.rates
-      ? fetchCashPosition(bcClient, store.companyId, start, end, opts.rates)
+      ? computeCashPosition(bcClient, store, start, end, opts.rates).catch((e) => { logger.warn(`[cash-flow] cash position failed: ${e.message}`); return null; })
       : Promise.resolve(null),
   ]);
 
@@ -244,80 +245,8 @@ async function buildStoreCashFlow(bcClient, store, start, end, opts = {}) {
   );
 }
 
-// ─────────────────────────────────────────────────────────────────────────────
-// 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,
-  };
-}
+// La posición de caja + efecto cambiario (revaluación del saldo VES contra el saldo REAL del
+// banco, aislando el backlog de conciliación) vive en ./fx-cash.js (módulo compartido).
 
 // 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.
@@ -497,18 +426,28 @@ 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, 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) {
+  // Posición de caja: separar la BRECHA DE CONCILIACIÓN (backlog en VES, a postear) del
+  // EFECTO CAMBIARIO sobre la caja real (asiento de diferencial cambiario). El FX se mide
+  // sobre el saldo real del banco (statement), no sobre el GL inflado por el backlog.
+  if (cash_position && cash_position.totals) {
+    const t = cash_position.totals;
+    if (Math.abs(t.recon_gap_ves) >= 1000) {
+      const gapUsd = cash_position.rate_end ? t.recon_gap_ves / cash_position.rate_end : 0;
+      insights.push(
+        `Brecha de conciliación: el GL excede al saldo real del banco en ${fmtAbs(t.recon_gap_ves)} VES ` +
+        `(~$${fmtAbs(gapUsd)}) — transacciones por postear; no es efecto cambiario.`
+      );
+    }
+    if (t.fx_real < 0 && Math.abs(t.fx_real) >= 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}.`
+        `Efecto cambiario sobre caja VES real: −$${fmtAbs(t.fx_real)}${dev} — postear asiento de ` +
+        `diferencial cambiario. Caja VES real $${fmtAbs(t.ves_real_usd)} (vs $${fmtAbs(cash_position.gl_basis.ves_book_usd)} en libros GL).`
       );
     }
+    if (cash_position.pending_no_statement && cash_position.pending_no_statement.length) {
+      insights.push(`${cash_position.pending_no_statement.length} cuenta(s) VES sin statement — revaluación provisional, conciliar antes de postear.`);
+    }
   }
 
   // Mayor driver negativo entre los usos de capital de trabajo (7 líneas)
@@ -597,39 +536,12 @@ 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),
+      cash_position: consolidateCashPositions(storeObjs.map((o) => (o.cash_position ? { ...o.cash_position, _store: o.store_code } : null))),
       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)
 // ─────────────────────────────────────────────────────────────────────────────

package/tools/financials/fx-cash.js

@@ -0,0 +1,227 @@
+// tools/financials/fx-cash.js
+//
+// Módulo compartido: posición de caja + efecto cambiario sobre la caja VES, revaluando
+// contra el SALDO REAL del banco (StatementEndingBalance), no el saldo GL (que puede estar
+// inflado por backlog de conciliación). Usado por get_cash_flow (vista) y, a futuro, por el
+// paso de cierre-mensual (asiento). READ-ONLY. NO afecta el FCF.
+//
+// MATEMÁTICA (por cuenta VES, robusta al backlog):
+//   gl_usd       = Σ(debit−credit)                 USD libro
+//   gl_ves       = Σ(additionalCurrency d−c)        VES libro (puede estar inflado)
+//   implied_rate = gl_ves / gl_usd                  tasa promedio histórica de posteo
+//   stmt_ves     = StatementEndingBalance           VES real (del banco)
+//   recon_gap    = gl_ves − stmt_ves                backlog pendiente de postear (NO es FX)
+//   real_usd     = stmt_ves / rate_end              valor USD real de la caja
+//   fx_real      = stmt_ves × (1/rate_end − 1/implied_rate)   ← pérdida cambiaria sobre lo REAL
+//
+// 3 buckets de cuentas VES:
+//   1) banco real con statement → fx_real, ENTRA al total y al asiento.
+//   2) banco real sin statement → provisional sobre GL, flag, NO entra al total.
+//   3) ajuste/tránsito (lista en config) → solo informativo, NO entra al total.
+
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { round2 } from '../../utils/currency-converter.js';
+import { logger } from '../../utils/logger.js';
+
+// ── Config bank-gl-map (cargado una vez) ───────────────────────────────────────
+let _bankMap = null;
+function bankMap() {
+  if (_bankMap) return _bankMap;
+  const path = fileURLToPath(new URL('../../config/bank-gl-map.json', import.meta.url));
+  _bankMap = JSON.parse(readFileSync(path, 'utf-8'));
+  return _bankMap;
+}
+
+// Cuentas VES de ajuste/tránsito (bucket 3) — informativas, fuera del total/asiento.
+function adjustmentAccounts() {
+  return new Set(bankMap().adjustment_accounts_ves || []);
+}
+
+// Mapa GL→banco para una tienda: { '18250': { bankCode: 'FQ88-MN0005', name: 'Bancrecer 2558 Bs.' } }
+// Solo cuentas VES (el statement está en VES).
+function glToBankForStore(storeCode) {
+  const store = (bankMap().stores || {})[storeCode];
+  const out = {};
+  if (!store) return out;
+  for (const [suffix, info] of Object.entries(store.accounts || {})) {
+    if (!info.gl || info.currency !== 'VES') continue;
+    out[String(info.gl)] = { bankCode: `${storeCode}-${suffix}`, name: info.name || '' };
+  }
+  return out;
+}
+
+// Regla VES (confirmada por FP): bancos VES = 18200–18299 ; caja VEB = 18110/18130/18160.
+const VES_CASH_ACCOUNTS = new Set(['18110', '18130', '18160']);
+export function isVesCashAccount(accountNumber) {
+  const n = parseInt(accountNumber, 10);
+  return (n >= 18200 && n <= 18299) || VES_CASH_ACCOUNTS.has(String(accountNumber));
+}
+
+const RATE_MIN = 350, RATE_MAX = 750; // banda sana para la tasa implícita (flag si está fuera)
+
+// ── Cálculo principal ──────────────────────────────────────────────────────────
+// store = { code, name, companyId, companyName }
+export async function computeCashPosition(bcClient, store, start, end, rates) {
+  const [entries, statements] = await Promise.all([
+    bcClient.getCashGLBalances(store.companyId, end).catch((e) => { logger.warn(`[fx-cash] GL balances failed: ${e.message}`); return null; }),
+    bcClient.getBankStatementBalances(store.code, end).catch((e) => { logger.warn(`[fx-cash] statement balances 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.');
+  if (statements == null) warnings.push('Reconciliaciones bancarias no disponibles — sin saldo real; revaluación provisional sobre GL.');
+
+  const glToBank = glToBankForStore(store.code);
+  const adjustment = adjustmentAccounts();
+  const stmts = statements || {};
+
+  // Acumular saldos GL por cuenta (USD libro + VES additionalCurrency)
+  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 bank_accounts = [];        // bucket 1
+  const pending_no_statement = []; // bucket 2
+  const informational = [];        // bucket 3
+  let usdTotal = 0;
+  let glVesBookSum = 0, glVesAtRateSum = 0; // referencia estilo v1.26.0 (todas las VES sobre GL)
+
+  for (const [a, v] of Object.entries(acc)) {
+    const glUsd = round2(v.usd);
+    const glVes = round2(v.ves);
+    if (Math.abs(glUsd) < 0.005 && Math.abs(glVes) < 0.5) continue; // saldo cero
+
+    if (!isVesCashAccount(a)) { usdTotal += glUsd; continue; } // cuentas USD: sin ajuste
+
+    // Referencia GL (v1.26.0): revaluar el saldo GL completo
+    glVesBookSum += glUsd;
+    glVesAtRateSum += glVes / rateEnd;
+
+    const impliedRate = glVes !== 0 && glUsd > 0 ? round2(glVes / glUsd) : null;
+    const flags = [];
+    if (impliedRate != null && (impliedRate < RATE_MIN || impliedRate > RATE_MAX)) flags.push('tasa_implicita_atipica');
+    const info = glToBank[a];
+    const stmt = info ? stmts[info.bankCode] : null;
+
+    // fx sobre un saldo VES dado, a la tasa implícita de la cuenta
+    const fxOn = (vesBalance) => (impliedRate ? round2(vesBalance * (1 / rateEnd - 1 / impliedRate)) : 0);
+
+    if (adjustment.has(String(a))) {
+      // Bucket 3 — ajuste/tránsito: informativo
+      informational.push({ account: a, name: info ? info.name : 'Ajuste/Tránsito VES', gl_usd: glUsd, gl_ves: glVes, implied_rate: impliedRate, fx_theoretical: fxOn(glVes), flags: [...flags, 'ajuste_transito'] });
+    } else if (info && stmt) {
+      // Bucket 1 — banco real con statement: revaluar saldo REAL
+      const stmtVes = round2(stmt.ending || 0);
+      const realUsd = round2(stmtVes / rateEnd);
+      const fxReal = fxOn(stmtVes);
+      if (stmt.stale) flags.push('statement_desactualizado');
+      bank_accounts.push({
+        account: a, bank_code: info.bankCode, name: info.name,
+        gl_usd: glUsd, gl_ves: glVes, implied_rate: impliedRate,
+        stmt_ves: stmtVes, statement_date: stmt.statementDate || null,
+        recon_gap_ves: round2(glVes - stmtVes), real_usd: realUsd, fx_real: fxReal, flags,
+      });
+    } else {
+      // Bucket 2 — banco/caja sin statement: provisional sobre GL
+      pending_no_statement.push({ account: a, name: info ? info.name : 'VES sin statement', gl_usd: glUsd, gl_ves: glVes, implied_rate: impliedRate, fx_provisional: fxOn(glVes), flags: [...flags, 'sin_statement'] });
+    }
+  }
+
+  bank_accounts.sort((x, y) => x.fx_real - y.fx_real);
+  pending_no_statement.sort((x, y) => x.fx_provisional - y.fx_provisional);
+  informational.sort((x, y) => x.fx_theoretical - y.fx_theoretical);
+
+  const sum = (arr, fn) => round2(arr.reduce((s, o) => s + fn(o), 0));
+  const totals = {
+    ves_real_usd: sum(bank_accounts, (o) => o.real_usd),
+    fx_real: sum(bank_accounts, (o) => o.fx_real),
+    recon_gap_ves: sum(bank_accounts, (o) => o.recon_gap_ves),
+    bank_book_usd: sum(bank_accounts, (o) => o.gl_usd),
+    pending_book_usd: sum(pending_no_statement, (o) => o.gl_usd),
+    informational_book_usd: sum(informational, (o) => o.gl_usd),
+    usd_accounts_usd: round2(usdTotal),
+  };
+  totals.total_cash_real_usd = round2(totals.ves_real_usd + usdTotal);
+
+  const fx_journal = buildFxJournal(bank_accounts);
+
+  return {
+    rate_end: round2(rateEnd),
+    rate_start: rateStart ? round2(rateStart) : null,
+    month_devaluation_pct: rateStart && rateStart > 0 ? round2((rateEnd / rateStart - 1) * 100) : null,
+    bank_accounts,
+    pending_no_statement,
+    informational,
+    usd: { total_usd: round2(usdTotal) },
+    totals,
+    gl_basis: { ves_book_usd: round2(glVesBookSum), ves_at_rate_usd: round2(glVesAtRateSum), fx_on_gl: round2(glVesAtRateSum - glVesBookSum) },
+    fx_journal,
+    warnings,
+  };
+}
+
+// ── Asiento sugerido de diferencial cambiario (READ-ONLY texto) — solo bucket 1 ──
+// DR Pérdida Diferencial Cambiario / CR cada banco VES (en USD) por su fx_real.
+export function buildFxJournal(bankAccounts) {
+  const PNL_ACCOUNT = { account: 'Diferencial Cambiario', note: 'Pérdida/Ganancia por diferencial cambiario (P&L)' };
+  const rows = [];
+  let bankDebit = 0, bankCredit = 0;
+  for (const b of bankAccounts) {
+    if (Math.abs(b.fx_real) < 0.005) continue;
+    // pérdida (fx_real<0) → CR banco ; ganancia (fx_real>0) → DR banco
+    const debit = b.fx_real > 0 ? round2(b.fx_real) : 0;
+    const credit = b.fx_real < 0 ? round2(-b.fx_real) : 0;
+    bankDebit += debit; bankCredit += credit;
+    rows.push({ account: b.account, name: b.name, account_type: 'Banco (G/L)', debit_usd: debit, credit_usd: credit });
+  }
+  const net = round2(bankCredit - bankDebit); // >0 = pérdida neta
+  // Contrapartida P&L
+  rows.push({
+    account: PNL_ACCOUNT.account, name: PNL_ACCOUNT.note, account_type: 'G/L (P&L)',
+    debit_usd: net > 0 ? net : 0, credit_usd: net < 0 ? round2(-net) : 0,
+  });
+  const debitTotal = round2(rows.reduce((s, r) => s + r.debit_usd, 0));
+  const creditTotal = round2(rows.reduce((s, r) => s + r.credit_usd, 0));
+  return { rows, debit_total: debitTotal, credit_total: creditTotal, balanced: Math.abs(debitTotal - creditTotal) < 0.01, net_fx: net };
+}
+
+// Consolida posiciones de varias tiendas (suma bucket 1/2/3 y rehace totales/asiento).
+export function consolidateCashPositions(positions) {
+  const ps = positions.filter(Boolean);
+  if (!ps.length) return null;
+  const ref = ps[0];
+  const tag = (arr, code) => arr.map((o) => ({ ...o, store: code }));
+  const bank_accounts = ps.flatMap((p) => tag(p.bank_accounts, p._store)).sort((a, b) => a.fx_real - b.fx_real);
+  const pending_no_statement = ps.flatMap((p) => tag(p.pending_no_statement, p._store));
+  const informational = ps.flatMap((p) => tag(p.informational, p._store));
+  const sum = (fn) => round2(ps.reduce((s, p) => s + fn(p), 0));
+  const usdTotal = sum((p) => p.usd.total_usd);
+  const totals = {
+    ves_real_usd: sum((p) => p.totals.ves_real_usd),
+    fx_real: sum((p) => p.totals.fx_real),
+    recon_gap_ves: sum((p) => p.totals.recon_gap_ves),
+    bank_book_usd: sum((p) => p.totals.bank_book_usd),
+    pending_book_usd: sum((p) => p.totals.pending_book_usd),
+    informational_book_usd: sum((p) => p.totals.informational_book_usd),
+    usd_accounts_usd: round2(usdTotal),
+  };
+  totals.total_cash_real_usd = round2(totals.ves_real_usd + usdTotal);
+  return {
+    rate_end: ref.rate_end, rate_start: ref.rate_start, month_devaluation_pct: ref.month_devaluation_pct,
+    bank_accounts, pending_no_statement, informational,
+    usd: { total_usd: round2(usdTotal) }, totals,
+    gl_basis: { ves_book_usd: sum((p) => p.gl_basis.ves_book_usd), ves_at_rate_usd: sum((p) => p.gl_basis.ves_at_rate_usd), fx_on_gl: sum((p) => p.gl_basis.fx_on_gl) },
+    fx_journal: buildFxJournal(bank_accounts),
+    warnings: [...new Set(ps.flatMap((p) => p.warnings))],
+  };
+}