@fullqueso/mcp-bc-gastos 1.17.0 → 1.23.0

package/CHANGELOG.md

@@ -1,10 +1,105 @@
 # CHANGELOG
 
+## [1.23.0] — 2026-05-31
+
+### Added
+- **Dominio `financials/`: tool `get_cash_flow`** — Free Cash Flow (FCF) por método indirecto para una o más tiendas FQ.
+  - Parte del EBIT (reutiliza `fetchStoreFinancials` de `get_financial_statements`), resta impuesto estimado (ISLR 34%, solo si EBIT>0) → NOPAT, ajusta por capital de trabajo (ΔAR, ΔAP, Δinventario) → CFO, resta CapEx (activos fijos 15000-17999) → FCF.
+  - Fuentes BC: AR/AP vía Finance Beta (`customerLedgerEntries`/`vendorLedgerEntries`, USD = `amountLocalCurrency`), inventario vía `itemLedgerEntries` (`costAmountActual`), CapEx vía `getGLEntries`. Todas en paralelo (`Promise.all`) junto al P&L.
+  - Convención de signos: cada delta = impacto en caja (+ = fuente, − = uso); `net_wc_change = ΔAR+ΔAP+Δinv`; `cfo = nopat + net_wc_change`; `fcf = cfo − capex`. (Resuelve la inconsistencia del spec entre comentarios y fórmula a favor de la convención de impacto-en-caja, autoconsistente.)
+  - `fcf_status` (healthy/positive_low/negative_watch/negative_critical), `fcf_bridge` (waterfall) e `insights` automáticos. Consolidado multi-tienda + comparación MoM (con `no_previous_data` para tiendas sin mes anterior).
+  - `render_html=true`: dashboard HTML reutilizando el design system de financials + **waterfall CSS** del FCF bridge (sin librerías externas). Guarda en `~/Downloads/FQ_CashFlow_[STORE|Consolidado]_YYYYMM.html`.
+- **`tools/financials/cash-flow.js`** y **`tools/financials/cash-flow-html.js`**. Exportados helpers reutilizables (`CSS`, `fmt`, `esc`, `clamp`, `scoreColorName`, `periodLabel`, `previousMonthRange`) desde `html-template.js`/`statements.js`.
+
+### Notas
+- Si un endpoint BC (AR/AP/inventario/activos fijos) devuelve vacío o falla, ese delta se asume 0 y se agrega un warning a `insights` (no rompe el cálculo).
+- Si una tienda falla, las demás continúan; el error queda en el campo de esa tienda.
+- Tool count: 53 → 54.
+
+---
+
+## [1.22.0] — 2026-05-31
+
+### Added
+- **Dominio `financials/`: tool `get_financial_statements`** — Estado financiero completo (P&L) para una o más tiendas FQ en un período.
+  - P&L completo: ingresos por cuenta, COGS, margen bruto, gastos por categoría (con benchmarks), margen operativo.
+  - Queries BC en paralelo `Promise.all` (3 tiendas × 3 queries = 9 simultáneas) + exchange rate compartido.
+  - Consolidado multi-tienda re-agregando todas las GL entries crudas (consistencia exacta con la suma de tiendas).
+  - Template HTML estático (design system FQ: tokens Dark/Light, header rojo, ring de score, toggle, TL;DR, grid KPIs, tabla P&L, barras de gastos, comparativa multi-tienda, `@media print`). `render_html=true` guarda en `~/Downloads` y retorna la ruta.
+  - Comparación mes-a-mes con `compare_previous=true`. Si el período anterior no tiene datos (la tienda aún no operaba en BC, p.ej. FQ01 antes de Dic 2025), se marca `no_previous_data: true` en vez de comparar contra cero (evita score/varianzas fabricados).
+  - Score 0-100 ponderado por status de 7 ratios vs benchmarks del sector.
+- **`tools/financials/aggregator.js`** — `EXPENSE_CATEGORIES`, `getStatus`, `aggregateIncome`, `aggregateCOGS`, `aggregateExpenses`, `calcRatios`, `calcScore`, `generateInsights`. Reutiliza `config/expense-accounts.js` y `config/benchmarks.js`.
+
+### Notas
+- Reutiliza el `bcClient.getGLEntries()` existente (convención `debitAmount`/`creditAmount`, no el `amount` de Finance Beta). Paginación automática vía `apiCallAllPages`.
+- Bump desde 1.21.0 → 1.22.0 (el spec mencionaba "1.2.0" cuando la versión base era anterior; 1.2.0 sería un downgrade, por eso MINOR sobre la versión real publicada).
+- Tool count: 52 → 53.
+
+### Validado (FQ01 Diciembre 2025)
+- `income.total` = $157,693 · `cogs.total` = $100,158 · `gross_margin.pct` = 36.49% · `expenses.otros.amount` = $19,233 (mermas $16,933) · `operating_income.pct` = 10.6% · `score` ≈ 42.
+
+---
+
+## [1.20.0] - 2026-05-04
+
+### Added
+- **`get_item_sales_detail` tool (ventas)** — Detalle de ventas por SKU (1–50 ítems) con granularidad day/week/month/total y desglose por tienda. Pensado para análisis de promos, canibalización, lanzamientos y SKUs estacionales que caen fuera del top-20 de `get_sales_analysis`. Fuente: `itemLedgerEntries` con `entryType eq 'Sale'` (mismos signos que el screenshot del Item Application Worksheet — quantity y costAmountActual negativos en BC, invertidos a positivos en la salida). Soporta `include_zero_days` para detección de stockouts y series temporales limpias. Multi-company en paralelo (FQ01/FQ28/FQ88).
+- **`bcClient.getItemLedgerSaleEntries(companyId, { items, startDate, endDate })`** — Helper en `lib/bc-client.js` para fetch paginado de ILE Sale entries por lote de ítems.
+
+### Changed
+- Tool count: 45 → 46
+
+---
+
+## [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 41 tools across 8 domains
+- Full Queso now has one unified BC MCP with **42 tools** across 8 domains
 
 ### Added
 

package/config/bank-gl-map.json

@@ -0,0 +1,93 @@
+{
+  "version": "1.0",
+  "last_updated": "2026-05-17",
+  "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", "_nota": "Punto 2 + Punto 3." },
+        "MN0029": { "gl": "18291", "name": "UBII 6442 Bs", "currency": "VES", "category": "bancos_nacionales", "_nota": "Punto 4 + Punto 7." },
+        "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 y 7 (duplicada)", "currency": "VES", "category": "bancos_nacionales", "_nota": "Cuenta duplicada creada por error — NO usar. Punto 4 y Punto 7 van a MN0029. Confirmado 2026-05-17." },
+        "MN0033": { "gl": "18295", "name": "UBII 7 bloqueado (duplicada)", "currency": "VES", "category": "bancos_nacionales", "_nota": "Cuenta duplicada creada por error — NO usar. Punto 7 va a MN0029. Confirmado 2026-05-17." },
+        "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/config/bank-keywords.js

@@ -30,6 +30,41 @@ export const BANK_KEYWORDS = [
   // Transfers
   { keywords: ['TRANSF RECIBIDA', 'TRANSFERENCIA RECIBIDA'], account: '11000', name: 'Transferencia Recibida' },
   { keywords: ['TRANSF ENVIADA', 'TRANSFERENCIA ENVIADA'], account: '11000', name: 'Transferencia Enviada' },
+  { keywords: ['PAGO RECIBIDO OTROS BANCOS', 'ABONO RECIBIDO OTR BCOS'], account: '11000', name: 'Pago Recibido Otros Bancos' },
+  { keywords: ['PAGOMOVIL', 'PAGO MOVIL', 'PAGOMOVILBDV'], account: '11000', name: 'Pago Móvil' },
+  { keywords: ['TRANS.CTAS', 'TRASPASO OTRAS CTAS', 'TRF.MB', 'TRF CR INM', 'TRF DR INM'], account: '11000', name: 'Traspaso entre cuentas' },
+  { keywords: ['TRANSF EN LINEA OTR BCOS', 'TRANSF EN LINEA'], account: '11000', name: 'Transferencia en línea' },
+  { keywords: ['DOMICILIACION DE PAGOS', 'DOMICILIACION'], account: '11000', name: 'Domiciliación' },
+
+  // UBII / merchant clearing (INM.OB family) — see project memory project_ubii_clearing_account.md
+  { keywords: ['CREDITO INM.OB', 'INM.OB'], account: '18290', name: 'UBII Clearing (revisar emparejamiento cross-bank)' },
+
+  // Loans (líneas de crédito)
+  { keywords: ['DESEMBOLSO DE CREDITO'], account: '23100', name: 'Desembolso Crédito Bancario' },
+  { keywords: ['PAGO CREDITO', 'PAGO DE CREDITO', 'PAGO PRESTAMO'], account: '23100', name: 'Pago Crédito Bancario' },
+  { keywords: ['OP.INTERV', 'OPERACION INTERV', 'INTERV. CAMBIARIA', 'INTERVENCION CAMBIARIA'], account: '11500', name: 'Intervención cambiaria (USD compra/venta)' },
+
+  // Tax retentions
+  { keywords: ['N/D ISLR', 'RETENCION ISLR'], account: '21300', name: 'Retención ISLR' },
+  { keywords: ['SENIAT', 'IMPUESTO', 'IVA RETEN'], account: '21100', name: 'Retención IVA / SENIAT' },
+
+  // Statement fee
+  { keywords: ['EMISION DE ESTADO DE CUENTA', 'ESTADO DE CUENTA'], account: '67100', name: 'Comisión emisión estado de cuenta' },
+
+  // IVSS
+  { keywords: ['PAGO IVSS', 'IVSS'], account: '71300', name: 'Pago IVSS' },
+
+  // Checks
+  { keywords: ['CHEQUE PAGADO', 'CHQ', 'CHEQUE'], account: '11000', name: 'Cheque' },
+
+  // Outbound bank payments (PAGO A OTROS BANCOS / PAGO A TERCEROS)
+  { keywords: ['PAGO A OTROS BANCOS', 'PAGO A TERCEROS', 'PAGOS A OTROS BANCOS'], account: '11000', name: 'Pago a otros bancos' },
+
+  // INM.MB family (Internet/Mobile Banking credit movements, distinct from INM.OB)
+  { keywords: ['CREDITO INM.MB', 'INM.MB'], account: '11000', name: 'Movimiento Internet/Mobile Banking' },
+
+  // Loan opening fees
+  { keywords: ['GASTOS APERTURA CREDITOS', 'APERTURA CREDITO'], account: '67100', name: 'Gastos apertura crédito' },
 ];
 
 // Match a bank description against keywords

package/lib/bc-client.js

@@ -2,6 +2,7 @@ import { logger } from '../utils/logger.js';
 import { getExpenseCategory } from '../config/expense-accounts.js';
 import { INCOME_GROUP_LABELS } from '../config/income-accounts.js';
 import { resolveStores } from '../config/company-config.js';
+import { bcLimiter } from '../utils/rate-limiter.js';
 
 export class BCClient {
   constructor() {
@@ -19,6 +20,28 @@ export class BCClient {
     this.EXCHANGE_RATE_TTL = 15 * 60 * 1000;   // 15 minutes
   }
 
+  /**
+   * Sanitize a string value before embedding it in an OData $filter expression.
+   *
+   * OData string literals are delimited by single quotes. An attacker who
+   * controls a filter parameter (e.g. accountNo, vendorNo, postingDate) could
+   * inject arbitrary filter logic by inserting a single quote. Doubling every
+   * single quote is the standard OData escape sequence (identical to SQL).
+   *
+   * Usage inside a $filter template:
+   *   `accountNo eq '${this._sanitizeOData(args.accountNo)}'`
+   *
+   * DOES NOT protect numeric / date literals — those should be validated with
+   * Number.isFinite() or a date regex before use.
+   *
+   * @param {string} value
+   * @returns {string}
+   */
+  _sanitizeOData(value) {
+    if (value == null) return '';
+    return String(value).replace(/'/g, "''");
+  }
+
   _cacheKey(prefix, ...parts) {
     return `${prefix}:${parts.join(':')}`;
   }
@@ -93,6 +116,7 @@ export class BCClient {
   }
 
   async apiCall(url) {
+    bcLimiter.recordCall(); // throws if rate limit exceeded
     const token = await this.getToken();
     logger.debug(`API call: ${url}`);
 
@@ -130,13 +154,20 @@ export class BCClient {
     }
   }
 
-  async apiCallAllPages(url) {
+  async apiCallAllPages(url, maxPages = 20) {
     const token = await this.getToken();
     let allResults = [];
     let nextUrl = url;
+    let pageCount = 0;
 
     while (nextUrl) {
-      logger.debug(`API call (paged): ${nextUrl}`);
+      if (pageCount >= maxPages) {
+        logger.warn(`apiCallAllPages: maxPages (${maxPages}) reached — results may be truncated. Set maxPages higher if needed.`);
+        allResults._truncated = true;
+        break;
+      }
+      bcLimiter.recordCall();
+      logger.debug(`API call (paged ${pageCount + 1}/${maxPages}): ${nextUrl}`);
       const response = await this.fetchWithRetry(nextUrl, {
         headers: { Authorization: `Bearer ${token}` },
       });
@@ -149,6 +180,7 @@ export class BCClient {
       const data = await response.json();
       allResults = allResults.concat(data.value || []);
       nextUrl = data['@odata.nextLink'] || null;
+      pageCount++;
     }
 
     return allResults;
@@ -240,13 +272,20 @@ export class BCClient {
     return data.value || data;
   }
 
-  async odataCallAllPages(url) {
+  async odataCallAllPages(url, maxPages = 20) {
     const token = await this.getToken();
     let allResults = [];
     let nextUrl = url;
+    let pageCount = 0;
 
     while (nextUrl) {
-      logger.debug(`OData call (paged): ${nextUrl}`);
+      if (pageCount >= maxPages) {
+        logger.warn(`odataCallAllPages: maxPages (${maxPages}) reached — results may be truncated.`);
+        allResults._truncated = true;
+        break;
+      }
+      bcLimiter.recordCall();
+      logger.debug(`OData call (paged ${pageCount + 1}/${maxPages}): ${nextUrl}`);
       const response = await this.fetchWithRetry(nextUrl, {
         headers: { Authorization: `Bearer ${token}` },
       });
@@ -259,6 +298,7 @@ export class BCClient {
       const data = await response.json();
       allResults = allResults.concat(data.value || []);
       nextUrl = data['@odata.nextLink'] || null;
+      pageCount++;
     }
 
     return allResults;
@@ -266,8 +306,10 @@ export class BCClient {
 
   // Fetch General Ledger Entries for a specific account range
   async getGLEntries(companyId, startDate, endDate, accountMin, accountMax) {
+    const sd = this._sanitizeOData(startDate);
+    const ed = this._sanitizeOData(endDate);
     const url = this.buildApiUrl(companyId, 'generalLedgerEntries', {
-      $filter: `postingDate ge ${startDate} and postingDate le ${endDate} and accountNumber ge '${accountMin}' and accountNumber le '${accountMax}'`,
+      $filter: `postingDate ge ${sd} and postingDate le ${ed} and accountNumber ge '${accountMin}' and accountNumber le '${accountMax}'`,
       $select: 'entryNumber,postingDate,documentNumber,accountNumber,description,debitAmount,creditAmount',
       $orderby: 'postingDate desc',
     });
@@ -509,13 +551,13 @@ export class BCClient {
   async getDetailedGLEntries(companyId, filters = {}) {
     const conditions = [];
 
-    if (filters.startDate) conditions.push(`postingDate ge ${filters.startDate}`);
-    if (filters.endDate) conditions.push(`postingDate le ${filters.endDate}`);
+    if (filters.startDate) conditions.push(`postingDate ge ${this._sanitizeOData(filters.startDate)}`);
+    if (filters.endDate)   conditions.push(`postingDate le ${this._sanitizeOData(filters.endDate)}`);
     if (filters.accountNumber) {
-      conditions.push(`accountNumber eq '${filters.accountNumber}'`);
+      conditions.push(`accountNumber eq '${this._sanitizeOData(filters.accountNumber)}'`);
     } else if (filters.accountMin && filters.accountMax) {
-      conditions.push(`accountNumber ge '${filters.accountMin}'`);
-      conditions.push(`accountNumber le '${filters.accountMax}'`);
+      conditions.push(`accountNumber ge '${this._sanitizeOData(filters.accountMin)}'`);
+      conditions.push(`accountNumber le '${this._sanitizeOData(filters.accountMax)}'`);
     }
 
     const params = {
@@ -533,8 +575,10 @@ export class BCClient {
   // ── Sales Analysis Methods ──────────────────────────────────────
 
   async getSalesInvoicesExpanded(companyId, startDate, endDate) {
+    const sd = this._sanitizeOData(startDate);
+    const ed = this._sanitizeOData(endDate);
     const url = this.buildApiUrl(companyId, 'salesInvoices', {
-      $filter: `postingDate ge ${startDate} and postingDate le ${endDate}`,
+      $filter: `postingDate ge ${sd} and postingDate le ${ed}`,
       $orderby: 'postingDate desc',
       $expand: 'salesInvoiceLines',
     });
@@ -567,7 +611,23 @@ export class BCClient {
 
   async getItemsCatalog(companyId) {
     const url = this.buildApiUrl(companyId, 'items', {
-      $select: 'id,number,displayName,type,unitPrice,unitCost,itemCategoryCode,lastDirectCost',
+      $select: 'id,number,displayName,type,unitPrice,unitCost,itemCategoryCode',
+    });
+    return this.apiCallAllPages(url);
+  }
+
+  // Fetch Sale-type Item Ledger Entries for one or more items in a date range.
+  // Returns the raw per-entry rows from BC (signs unchanged: quantity & costAmountActual negative).
+  async getItemLedgerSaleEntries(companyId, { items, startDate, endDate }) {
+    if (!items || items.length === 0) return [];
+    const itemFilter = items.length === 1
+      ? `itemNumber eq '${items[0]}'`
+      : `(${items.map((i) => `itemNumber eq '${i}'`).join(' or ')})`;
+
+    const url = this.buildApiUrl(companyId, 'itemLedgerEntries', {
+      $filter: `${itemFilter} and entryType eq 'Sale' and postingDate ge ${startDate} and postingDate le ${endDate}`,
+      $select: 'entryNumber,itemNumber,postingDate,entryType,documentNumber,description,quantity,salesAmountActual,costAmountActual',
+      $orderby: 'itemNumber,postingDate',
     });
     return this.apiCallAllPages(url);
   }
@@ -619,7 +679,7 @@ export class BCClient {
       const item = itemsMap[itemNo];
       if (item) {
         line.itemCategoryCode = item.itemCategoryCode;
-        line.unitCostUSD = item.lastDirectCost || item.unitCost || 0;
+        line.unitCostUSD = item.unitCost || 0;
         line.displayName = item.displayName || line.description;
       }
       if (!line.displayName) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fullqueso/mcp-bc-gastos",
-  "version": "1.17.0",
+  "version": "1.23.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": {
@@ -23,7 +23,8 @@
     "start": "node server.js",
     "dev": "nodemon server.js",
     "test-connection": "node test-connection.js",
-    "test-tools": "node test-tools.js"
+    "test-tools": "node test-tools.js",
+    "test-item-sales-detail": "node tests/test-item-sales-detail.js"
   },
   "keywords": [
     "mcp",

package/scripts/diagnose-closing.js

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+// Read-only diagnostic for any (store, month) bank closing snapshot.
+//
+// Usage:
+//   node scripts/diagnose-closing.js --store FQ01 --month 2025-12
+//   node scripts/diagnose-closing.js -s FQ28 -m 2026-01 --bank FQ28-MN0001
+//
+// Hits BC OData/Beta API read-only. Writes a JSON snapshot to /tmp and
+// prints a summary to stderr.
+
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { existsSync, writeFileSync } from 'fs';
+import dotenv from 'dotenv';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const envPath = join(__dirname, '..', '.env');
+if (existsSync(envPath)) dotenv.config({ path: envPath });
+
+const { BCClient } = await import('../lib/bc-client.js');
+const { handleReconciliationStatus } = await import('../tools/auditoria/reconciliation-status.js');
+const { handleBankReconciliationReport } = await import('../tools/auditoria/bank-reconciliation-report.js');
+const { handleOpenReceivables } = await import('../tools/cobranzas/open-receivables.js');
+const { handleOpenPayables } = await import('../tools/cobranzas/open-payables.js');
+const { resolveStores } = await import('../config/company-config.js');
+
+// ── CLI args ───────────────────────────────────────────────
+function parseArgs(argv) {
+  const out = {};
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    const next = argv[i + 1];
+    if (a === '--store' || a === '-s') { out.store = next; i++; }
+    else if (a === '--month' || a === '-m') { out.month = next; i++; }
+    else if (a === '--bank' || a === '-b') { out.bank = next; i++; }
+    else if (a === '--help' || a === '-h') { out.help = true; }
+  }
+  return out;
+}
+const args = parseArgs(process.argv);
+if (args.help || !args.store || !args.month) {
+  console.error('Usage: node scripts/diagnose-closing.js --store FQ01 --month 2025-12 [--bank FQ01-MN0001]');
+  process.exit(args.help ? 0 : 2);
+}
+
+const STORE = args.store;
+const MONTH = args.month;
+const MONTH_END = lastDayOfMonth(MONTH);
+const BANK_FILTER = args.bank || null;
+
+const bc = new BCClient();
+const out = { store: STORE, month: MONTH, bank_filter: BANK_FILTER, generated_at: new Date().toISOString() };
+
+console.error(`\n=== Diagnostic ${STORE} ${MONTH} ${BANK_FILTER ? '/' + BANK_FILTER : ''} ===\n`);
+
+// 1. Reconciliation status
+try {
+  console.error('[1/4] reconciliation_status…');
+  out.reconciliation_status = await handleReconciliationStatus(bc, { store: STORE });
+  const recs = out.reconciliation_status.reconciliations || [];
+  const monthRecs = recs.filter((r) => (r.statement_date || '').startsWith(MONTH));
+  console.error(`  → ${recs.length} open reconciliations total; ${monthRecs.length} for ${MONTH}`);
+  for (const r of monthRecs) {
+    if (BANK_FILTER && r.bank_account_no !== BANK_FILTER) continue;
+    console.error(`     ${r.bank_account_no} #${r.statement_no} date=${r.statement_date} matched=${r.matched_lines}/${r.total_lines} ending=${r.statement_ending_balance}`);
+  }
+  out.month_reconciliations = monthRecs;
+} catch (err) {
+  console.error('  ✗', err.message);
+  out.reconciliation_status_error = err.message;
+}
+
+// 2. Bank reconciliation report (per bank or filter)
+try {
+  console.error('\n[2/4] bank_reconciliation_report…');
+  const targets = BANK_FILTER
+    ? [BANK_FILTER]
+    : (out.month_reconciliations || []).map((r) => r.bank_account_no);
+  out.bank_reports = {};
+  for (const bank of targets) {
+    const r = await handleBankReconciliationReport(bc, {
+      store: STORE, bank_account: bank, month: MONTH, include_suggestions: true,
+    });
+    out.bank_reports[bank] = {
+      statement_no: r.statement_no,
+      statement_date: r.statement_date,
+      balance_last_statement: r.balance_last_statement,
+      statement_ending_balance: r.statement_ending_balance,
+      unmatched_debits_count: r.unmatched_debits?.count,
+      unmatched_debits_total: r.unmatched_debits?.total_amount,
+      unmatched_credits_count: r.unmatched_credits?.count,
+      unmatched_credits_total: r.unmatched_credits?.total_amount,
+      match_rate_pct: r.unmatched_summary?.match_rate_pct,
+      suggestions_summary: r.journal_suggestions?.summary,
+    };
+    console.error(`  ${bank}: end=${r.statement_ending_balance} unmD=${r.unmatched_debits?.count} unmC=${r.unmatched_credits?.count} match=${r.unmatched_summary?.match_rate_pct}%`);
+  }
+} catch (err) {
+  console.error('  ✗', err.message);
+  out.bank_reports_error = err.message;
+}
+
+// 3. Open receivables / payables as of month_end
+try {
+  console.error('\n[3/4] open_receivables + open_payables…');
+  const [ar, ap] = await Promise.all([
+    handleOpenReceivables(bc, { store: STORE, as_of_date: MONTH_END }),
+    handleOpenPayables(bc, { store: STORE, as_of_date: MONTH_END }),
+  ]);
+  out.ar_summary = { customers: ar.receivables_by_customer?.length, aging: ar.aging_summary };
+  out.ap_summary = { vendors: ap.payables_by_vendor?.length, aging: ap.aging_summary };
+  console.error(`  AR: ${ar.receivables_by_customer?.length} customers, total ${ar.aging_summary?.total} USD`);
+  console.error(`  AP: ${ap.payables_by_vendor?.length} vendors, total ${ap.aging_summary?.total} USD`);
+} catch (err) {
+  console.error('  ✗', err.message);
+  out.arap_error = err.message;
+}
+
+// 4. Multi-Payment drafts (Gestion BC) — Transferred status
+try {
+  console.error('\n[4/4] multi-payment drafts (Transferred)…');
+  const { handleDraftPayables, handleDraftReceivables } = await import('../tools/multi-payment/index.js');
+  const [dp, dr] = await Promise.all([
+    handleDraftPayables(bc, { store: STORE }),
+    handleDraftReceivables(bc, { store: STORE }),
+  ]);
+  // Count Transferred drafts
+  const tp = (dp?.drafts_by_status?.Transferred || dp?.results || []).length;
+  const tr = (dr?.drafts_by_status?.Transferred || dr?.results || []).length;
+  out.mp_drafts = { transferred_payables: tp, transferred_receivables: tr };
+  console.error(`  Transferred drafts → payables: ${tp}, receivables: ${tr}`);
+} catch (err) {
+  console.error('  ✗', err.message);
+  out.mp_error = err.message;
+}
+
+const outPath = `/tmp/diagnose-${STORE}-${MONTH}.json`;
+writeFileSync(outPath, JSON.stringify(out, null, 2));
+console.error(`\n✓ Snapshot → ${outPath}\n`);
+
+function lastDayOfMonth(yyyyMm) {
+  const [y, m] = yyyyMm.split('-').map(Number);
+  return new Date(Date.UTC(y, m, 0)).toISOString().slice(0, 10);
+}