@fullqueso/mcp-bc-gastos 1.25.0 → 1.27.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # 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
+- **`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/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

@@ -316,6 +316,51 @@ 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);
+  }
+
+  // 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.25.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

@@ -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,56 @@ function renderCapexCard(s) {
 </div>`;
 }
 
+// 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.bank_accounts) return '';
+  const t = cp.totals;
+  const dev = cp.month_devaluation_pct != null ? ` · devaluación mes ${cp.month_devaluation_pct}%` : '';
+  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 · Conciliación · Efecto Cambiario (VES)</span></div>
+  <div class="card-bd"><div class="pnl">
+    <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>`;
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Comparativo de tiendas (multi)
 // ─────────────────────────────────────────────────────────────────────────────

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)
 
@@ -53,7 +54,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 +84,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 +120,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 +143,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 +209,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
+      ? computeCashPosition(bcClient, store, start, end, opts.rates).catch((e) => { logger.warn(`[cash-flow] cash position failed: ${e.message}`); return null; })
+      : Promise.resolve(null),
   ]);
 
   return assembleCashFlow(
@@ -228,11 +239,15 @@ 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,
     }
   );
 }
 
+// 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.
 //   - Activo que sube (debit) → −Σ < 0 = uso de caja.
@@ -359,7 +374,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 +392,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 +423,33 @@ 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 = [];
 
+  // 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(
+        `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)
   const uses = [
     { key: 'delta_inventory', label: 'Inventario', val: delta_inventory },
@@ -453,6 +494,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,6 +536,7 @@ function consolidateCashFlow(storeObjs) {
       delta_labor: sum((o) => o.working_capital.delta_labor || 0),
       capex: sum((o) => o.capex.amount),
       capex_accounts,
+      cash_position: consolidateCashPositions(storeObjs.map((o) => (o.cash_position ? { ...o.cash_position, _store: o.store_code } : null))),
       warnings: allWarnings,
     }
   );

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))],
+  };
+}