@fullqueso/mcp-bc-gastos 1.17.0 → 1.19.0

package/CHANGELOG.md

@@ -1,10 +1,54 @@
 # CHANGELOG
 
+## [1.19.0] - 2026-04-13
+
+### Added
+- **`get_customer_list` tool (cobranzas)** — Lists customers with number, name, and RIF (taxRegistrationNumber) per store. Supports optional filter by customer number.
+- **`config/bank-gl-map.json`** — Reference config documenting the full bank account suffix → GL account mapping per store (FQ01, FQ28, FQ88), including GL structure for Caja y Bancos (181xx–189xx).
+
+### Changed
+- **POS reconciliation: per-store bank GL mapping** — `BANK_GL_MAP` in `reconcile-pos-sales.js` now keyed by store (FQ01, FQ28) instead of flat suffix lookup. Adds cash register accounts (MN0030, ME0030) and full FQ28 bank set. `getBankGLAccount()` now accepts store parameter for correct GL resolution.
+- Tool count: 44 → 45
+
+---
+
+## [1.18.2] - 2026-04-13
+
+### Fixed
+- **Inventory tools: exclude FQ-\* sale/combo categories** — `get_inventory_levels`, `get_inventory_change`, and `get_inventory_by_location` now filter out items with `itemCategoryCode` starting with `FQ-`, `FQ_`, or equal to `FQVENTA`. These are sales/combo products, not real inventory, and their BC `unitCost` can be contaminated (zero-inventory edge cases), producing inflated inventory valuations. Real inventory items (TERMINADO, INSUMO, etc.) keep BC's FIFO-based `unitCost` which is accurate.
+
+### Changed
+- **Extracted `getCalculatedCosts` to shared module** — Moved from `item-card.js` to `tools/inventario/shared/cost-calculator.js` along with `isInventoryCategory()`. Avoids duplication across inventory tools.
+- **Updated `calculated_unit_cost_method.md`** — Documented category filtering logic and clarified that calculated cost is for FQ-* items only; real inventory uses BC FIFO cost.
+
+---
+
+## [1.18.1] - 2026-04-13
+
+### Changed
+- `get_inventory_by_location` — Added `as_of_date` parameter for historical inventory reconstruction by location. Filters OData V4 item ledger entries with `Posting_Date <= as_of_date`. Also added `isInventoryCategory` filter to exclude FQ-* sale/combo items (aligns with `get_inventory_levels` behavior).
+
+---
+
+## [1.18.0] - 2026-03-19
+
+### Added
+
+**Inventario domain — 2 new tools (inventory levels & change tracking):**
+- `get_inventory_levels` — Inventory snapshot grouped by itemCategoryCode and inventoryPostingGroupCode (congelados/imported/local). Supports historical reconstruction via `as_of_date` (e.g., 1st of month post-EOM adjustment). Returns classification matrix with qty, cost value, and top items per group.
+- `get_inventory_change` — WoW and MoM inventory change analysis. Reconstructs opening/closing inventory per period walking backwards from current balance. Movement breakdown by type (purchases, sales, adjustments, assembly). Trend summary per category and classification.
+
+### Changed
+- Tool count: 42 → 44
+- Inventario domain: 4 → 6 tools
+
+---
+
 ## [1.17.0] - 2026-03-18
 
 ### Highlights
 - **Ventas domain consolidated** from `mcp-bc-analisis-ventas` — 3 new sales analysis tools
-- Full Queso now has one unified BC MCP with 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-03-23",
+  "description": "Mapeo banco_code (BC Bank Account suffix) → cuenta GL (Chart of Accounts). Usado por POS reconciliation y journal entry suggestions. Cada tienda tiene su propio CoA con bancos distintos.",
+  "stores": {
+    "FQ01": {
+      "store_name": "FQ01 - Chacao Sambil",
+      "accounts": {
+        "MN0001": { "gl": "18210", "name": "Banesco 4421 Bs.", "currency": "VES", "category": "bancos_nacionales" },
+        "MN0002": { "gl": "18220", "name": "BDV 1925 Bs.", "currency": "VES", "category": "bancos_nacionales" },
+        "MN0003": { "gl": "18230", "name": "Bancamiga 7015 Bs.", "currency": "VES", "category": "bancos_nacionales" },
+        "MN0004": { "gl": "18240", "name": "BDV 5550 Bs.", "currency": "VES", "category": "bancos_nacionales" },
+        "MN0005": { "gl": "18250", "name": "Bancamiga 4523 Bs.", "currency": "VES", "category": "bancos_nacionales" },
+        "MN0006": { "gl": "18260", "name": "Bancrecer 2450 Bs.", "currency": "VES", "category": "bancos_nacionales" },
+        "MN0007": { "gl": "18270", "name": "Bancrecer 2467 Bs.", "currency": "VES", "category": "bancos_nacionales" },
+        "MN0008": { "gl": "18280", "name": "BDV 5187 Bs. (Pago Móvil)", "currency": "VES", "category": "bancos_nacionales" },
+        "MN0012": { "gl": "18290", "name": "UBII", "currency": "VES", "category": "bancos_nacionales" },
+        "MN0030": { "gl": "18130", "name": "Caja tienda ventas Bs.", "currency": "VES", "category": "caja" },
+        "ME0030": { "gl": "18140", "name": "Caja tienda ventas $", "currency": "USD", "category": "caja" },
+        "ME0006": { "gl": null, "name": "Zelle USD (Wells Fargo)", "currency": "USD", "category": "bancos_extranjeros", "_nota": "GL pendiente de confirmar" }
+      }
+    },
+    "FQ28": {
+      "store_name": "FQ28 - Marqués El Unicentro",
+      "accounts": {
+        "MN0001": { "gl": "18210", "name": "BDV 8139 Bs.", "currency": "VES", "category": "bancos_nacionales" },
+        "MN0002": { "gl": "18220", "name": "Bancrecer 5474 Bs.", "currency": "VES", "category": "bancos_nacionales" },
+        "MN0028": { "gl": "18290", "name": "UBII 6249 Bs", "currency": "VES", "category": "bancos_nacionales" },
+        "MN0029": { "gl": "18291", "name": "UBII 6442 * Bs", "currency": "VES", "category": "bancos_nacionales" },
+        "MN0030": { "gl": "18130", "name": "Caja tienda ventas Bs.", "currency": "VES", "category": "caja" },
+        "MN0031": { "gl": "18160", "name": "Caja transitoria tienda ventas Bs.", "currency": "VES", "category": "caja" },
+        "MN0032": { "gl": "18292", "name": "UBII 4 FQ-28", "currency": "VES", "category": "bancos_nacionales" },
+        "MN0033": { "gl": "18295", "name": "UBII 7 FQ-28", "currency": "VES", "category": "bancos_nacionales" },
+        "MN0098": { "gl": "18298", "name": "Operaciones en Tránsito", "currency": "VES", "category": "bancos_nacionales" },
+        "ME0002": { "gl": "18310", "name": "Bancrecer $", "currency": "USD", "category": "bancos_nacionales_divisas" },
+        "ME0005": { "gl": "18410", "name": "Zelle Bofa $ *", "currency": "USD", "category": "bancos_extranjeros" },
+        "ME0030": { "gl": "18140", "name": "Caja tienda ventas $", "currency": "USD", "category": "caja" },
+        "ME0031": { "gl": "18170", "name": "Caja transitoria tienda ventas $", "currency": "USD", "category": "caja" },
+        "ME0035": { "gl": "18150", "name": "Banco Bóveda $", "currency": "USD", "category": "caja" }
+      }
+    },
+    "FQ88": {
+      "store_name": "FQ88 - La Candelaria",
+      "_nota": "GL accounts pendientes de confirmar con CoA de FQ88",
+      "accounts": {
+        "MN0001": { "gl": null, "name": "Bancamiga 0240 Bs.", "currency": "VES", "category": "bancos_nacionales" },
+        "MN0002": { "gl": null, "name": "Bancamiga 9379 Bs. *", "currency": "VES", "category": "bancos_nacionales" },
+        "MN0003": { "gl": null, "name": "BDV 9127 Bs.", "currency": "VES", "category": "bancos_nacionales" },
+        "MN0004": { "gl": null, "name": "BDV 7191 Bs. *", "currency": "VES", "category": "bancos_nacionales" },
+        "MN0005": { "gl": null, "name": "Bancrecer 2558 Bs.", "currency": "VES", "category": "bancos_nacionales" },
+        "MN0007": { "gl": null, "name": "BDV Pago Movil 5145", "currency": "VES", "category": "bancos_nacionales" },
+        "MN0028": { "gl": null, "name": "Ubii Bank", "currency": "VES", "category": "bancos_nacionales" },
+        "MN0030": { "gl": "18130", "name": "Caja tienda ventas Bs.", "currency": "VES", "category": "caja" },
+        "ME0030": { "gl": "18140", "name": "Caja tienda ventas $", "currency": "USD", "category": "caja" },
+        "ME0005": { "gl": null, "name": "Zelle USD", "currency": "USD", "category": "bancos_extranjeros" }
+      }
+    }
+  },
+  "gl_structure": {
+    "18100": "Caja (header)",
+    "18110": "Caja chica VEB",
+    "18120": "Caja chica $",
+    "18130": "Caja tienda ventas VEB",
+    "18140": "Caja tienda ventas $",
+    "18150": "Bóveda $",
+    "18160": "Caja tránsito tienda ventas VEB",
+    "18170": "Caja tránsito tienda ventas $",
+    "18199": "Total Caja",
+    "18200": "Bancos Nacionales Bolívares (header)",
+    "18210": "Banco principal Bs.",
+    "18220": "Banco secundario Bs.",
+    "18230": "Banco terciario Bs.",
+    "18240": "Banco cuarto Bs.",
+    "18250": "Banco quinto Bs.",
+    "18260": "Banco sexto Bs.",
+    "18270": "Banco séptimo Bs.",
+    "18280": "Banco octavo Bs.",
+    "18290": "UBII principal",
+    "18291": "UBII secundario",
+    "18292": "UBII terciario",
+    "18295": "UBII cuarto",
+    "18298": "Operaciones en Tránsito",
+    "18299": "Total Bancos Nacionales",
+    "18300": "Bancos Nacionales Divisas (header)",
+    "18310": "Banco divisas principal",
+    "18399": "Total Bancos Nacionales Divisas",
+    "18400": "Bancos Extranjeros Divisas (header)",
+    "18410": "Banco extranjero principal",
+    "18499": "Total Bancos Extranjeros Divisas",
+    "18998": "Total Bancos",
+    "18999": "Total Caja y Bancos"
+  }
+}

package/lib/bc-client.js

@@ -567,7 +567,7 @@ 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);
   }
@@ -619,7 +619,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.19.0",
   "description": "MCP server for Business Central operational expense analysis, bank reconciliation, POS reconciliation, accounts receivable/payable, multi-payment draft visibility, payroll, inventory cost analysis, and manager reports - Full Queso franchise stores",
   "main": "server.js",
   "bin": {

package/server.js

@@ -54,6 +54,7 @@ import { openReceivablesTool, handleOpenReceivables } from './tools/cobranzas/op
 import { collectionStatusTool, handleCollectionStatus } from './tools/cobranzas/collection-status.js';
 import { vendorLedgerTool, handleVendorLedger } from './tools/cobranzas/vendor-ledger.js';
 import { openPayablesTool, handleOpenPayables } from './tools/cobranzas/open-payables.js';
+import { customerListTool, handleCustomerList } from './tools/cobranzas/customer-list.js';
 
 // Multi-Payment draft visibility tools
 import {
@@ -75,6 +76,9 @@ import {
   itemLedgerEntriesTool, handleItemLedgerEntries,
   itemValueEntriesTool, handleItemValueEntries,
   itemCostTrendTool, handleItemCostTrend,
+  inventoryLevelsTool, handleInventoryLevels,
+  inventoryChangeTool, handleInventoryChange,
+  inventoryByLocationTool, handleInventoryByLocation,
 } from './tools/inventario/index.js';
 
 // Ventas tools (sales analysis)
@@ -136,6 +140,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       collectionStatusTool,
       vendorLedgerTool,
       openPayablesTool,
+      customerListTool,
       // Multi-Payment draft visibility
       draftReceivablesTool,
       draftPayablesTool,
@@ -149,6 +154,9 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       itemLedgerEntriesTool,
       itemValueEntriesTool,  // get_item_cost_analysis
       itemCostTrendTool,
+      inventoryLevelsTool,
+      inventoryChangeTool,
+      inventoryByLocationTool,
       // Ventas (sales analysis)
       salesAnalysisTool,
       productPerformanceTool,
@@ -251,6 +259,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       case 'get_open_payables':
         result = await handleOpenPayables(bcClient, args);
         break;
+      case 'get_customer_list':
+        result = await handleCustomerList(bcClient, args);
+        break;
       // Multi-Payment draft visibility
       case 'get_draft_receivables':
         result = await handleDraftReceivables(bcClient, args);
@@ -284,6 +295,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       case 'get_item_cost_trend':
         result = await handleItemCostTrend(bcClient, args);
         break;
+      case 'get_inventory_levels':
+        result = await handleInventoryLevels(bcClient, args);
+        break;
+      case 'get_inventory_change':
+        result = await handleInventoryChange(bcClient, args);
+        break;
+      case 'get_inventory_by_location':
+        result = await handleInventoryByLocation(bcClient, args);
+        break;
       // Ventas (sales analysis)
       case 'get_sales_analysis':
         result = await handleSalesAnalysis(bcClient, args);

package/tools/auditoria/bank-ledger-entries.js

@@ -1,4 +1,3 @@
-import { DateTime } from 'luxon';
 import { resolveStores } from '../../config/company-config.js';
 
 export const bankLedgerEntriesTool = {
@@ -60,7 +59,6 @@ export async function handleBankLedgerEntries(bcClient, args) {
   });
   const entries = await bcClient.odataCallAllPages(url);
 
-  const today = DateTime.now();
   const formatted = entries.map((e) => {
     const amount = e.Amount || 0;
     const postingDate = e.Posting_Date || null;

package/tools/auditoria/reconcile-pos-sales.js

@@ -4,17 +4,37 @@ import { logger } from '../../utils/logger.js';
 
 // ── Constants ────────────────────────────────────────────────────────────
 
-// Bank account suffix → GL account for journal entry suggestions
+// Bank account suffix → GL account for journal entry suggestions (per store)
 const BANK_GL_MAP = {
-  'MN0001': '18210', // Banesco
-  'MN0002': '18220', // BDV 1925
-  'MN0003': '18230', // Bancamiga 7015
-  'MN0004': '18240', // BDV 5550
-  'MN0005': '18250', // Bancamiga 4523
-  'MN0006': '18260', // Bancrecer 2450
-  'MN0007': '18270', // Bancrecer 2467
-  'MN0008': '18280', // BDV 5187 (Pago Móvil)
-  'MN0012': '18290', // UBII
+  FQ01: {
+    'MN0001': '18210', // Banesco 4421 Bs.
+    'MN0002': '18220', // BDV 1925 Bs.
+    'MN0003': '18230', // Bancamiga 7015 Bs.
+    'MN0004': '18240', // BDV 5550 Bs.
+    'MN0005': '18250', // Bancamiga 4523 Bs.
+    'MN0006': '18260', // Bancrecer 2450 Bs.
+    'MN0007': '18270', // Bancrecer 2467 Bs.
+    'MN0008': '18280', // BDV 5187 Bs. (Pago Móvil)
+    'MN0012': '18290', // UBII
+    'MN0030': '18130', // Caja tienda ventas Bs.
+    'ME0030': '18140', // Caja tienda ventas $
+  },
+  FQ28: {
+    'MN0001': '18210', // BDV 8139 Bs.
+    'MN0002': '18220', // Bancrecer 5474 Bs.
+    'MN0028': '18290', // UBII 6249 Bs
+    'MN0029': '18291', // UBII 6442 * Bs
+    'MN0030': '18130', // Caja tienda ventas Bs.
+    'MN0031': '18160', // Caja transitoria tienda ventas Bs.
+    'MN0032': '18292', // UBII 4 FQ-28
+    'MN0033': '18295', // UBII 7 FQ-28
+    'MN0098': '18298', // Operaciones en Tránsito
+    'ME0002': '18310', // Bancrecer $
+    'ME0005': '18410', // Zelle Bofa $ *
+    'ME0030': '18140', // Caja tienda ventas $
+    'ME0031': '18170', // Caja transitoria tienda ventas $
+    'ME0035': '18150', // Banco Bóveda $
+  },
 };
 
 const COMMISSION_ACCOUNT = '67100'; // Comisiones Bancarias
@@ -140,12 +160,15 @@ function parseBankStatementLot(description) {
  * Get GL account for a bank account number.
  * "FQ01-MN0001" → "18210"
  */
-function getBankGLAccount(bankAccountNo) {
+function getBankGLAccount(bankAccountNo, store) {
   if (!bankAccountNo) return null;
-  // Extract suffix: "FQ01-MN0001" → "MN0001"
+  // Extract store and suffix: "FQ01-MN0001" → store "FQ01", suffix "MN0001"
   const parts = bankAccountNo.split('-');
   const suffix = parts[parts.length - 1];
-  return BANK_GL_MAP[suffix] || null;
+  const storeKey = store || parts[0];
+  const storeMap = BANK_GL_MAP[storeKey];
+  if (!storeMap) return null;
+  return storeMap[suffix] || null;
 }
 
 // ── Union-Find for Compound Lots ─────────────────────────────────────────
@@ -818,7 +841,7 @@ export async function handleReconcilePOSSales(bcClient, args) {
     }
 
     // ── Journal entry suggestions for commissions ──
-    const glAccount = getBankGLAccount(bankAccount);
+    const glAccount = getBankGLAccount(bankAccount, store);
     const journalEntries = [];
 
     if (isBDVAggregate && bdvAggregate.commission_total > 0) {
@@ -1211,7 +1234,7 @@ export async function handleReconcilePOSSales(bcClient, args) {
       const ubiiAvgFee = ubiiTotalBC > 0 ? round2((ubiiTotalFee / ubiiTotalBC) * 100) : 0;
 
       // Journal entries: fee + transfer per matched day
-      const ubiiGL = getBankGLAccount(ubiiFullAccount); // 18290
+      const ubiiGL = getBankGLAccount(ubiiFullAccount, store); // 18290
       const ubiiJournalEntries = [];
       for (const m of ubiiMatchedDays) {
         if (m.fee_ves > 0) {
@@ -1225,7 +1248,7 @@ export async function handleReconcilePOSSales(bcClient, args) {
           });
         }
         // Transfer entry: debit receiving bank, credit UBII
-        const receivingGL = getBankGLAccount(m.bank_deposit_bank);
+        const receivingGL = getBankGLAccount(m.bank_deposit_bank, store);
         if (receivingGL) {
           ubiiJournalEntries.push({
             posting_date: m.bank_deposit_date,

package/tools/cobranzas/customer-list.js

@@ -0,0 +1,63 @@
+import { resolveStores } from '../../config/company-config.js';
+
+export const customerListTool = {
+  name: 'get_customer_list',
+  description:
+    'Lista de clientes con número, nombre y RIF (taxRegistrationNumber). Útil para identificar clientes por RIF o exportar directorio de clientes.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      store: {
+        type: 'string',
+        enum: ['FQ01', 'FQ28', 'FQ88'],
+        description: 'Tienda a consultar.',
+      },
+      customer_number: {
+        type: 'string',
+        description: 'Filtrar por número de cliente específico.',
+      },
+    },
+    required: ['store'],
+  },
+};
+
+export async function handleCustomerList(bcClient, args) {
+  const store = args.store;
+  if (!store) throw new Error('Parámetro requerido: store');
+
+  const stores = resolveStores([store]);
+  const storeInfo = stores[0];
+
+  const selectFields = 'number,displayName,taxRegistrationNumber';
+  const params = { $select: selectFields, $orderby: 'number' };
+
+  if (args.customer_number) {
+    params.$filter = `number eq '${args.customer_number}'`;
+  }
+
+  const url = bcClient.buildApiUrl(storeInfo.companyId, 'customers', params);
+  const allCustomers = await bcClient.apiCallAllPages(url);
+
+  const customers = allCustomers.map((c) => ({
+    number: c.number,
+    name: c.displayName,
+    rif: c.taxRegistrationNumber || '',
+  }));
+
+  return {
+    content: [
+      {
+        type: 'text',
+        text: JSON.stringify(
+          {
+            store,
+            total_customers: customers.length,
+            customers,
+          },
+          null,
+          2
+        ),
+      },
+    ],
+  };
+}

package/tools/inventario/index.js

@@ -2,3 +2,6 @@ export { itemCardTool, handleItemCard } from './item-card.js';
 export { itemLedgerEntriesTool, handleItemLedgerEntries } from './item-ledger-entries.js';
 export { itemValueEntriesTool, handleItemValueEntries } from './item-value-entries.js';
 export { itemCostTrendTool, handleItemCostTrend } from './item-cost-trend.js';
+export { inventoryLevelsTool, handleInventoryLevels } from './inventory-levels.js';
+export { inventoryChangeTool, handleInventoryChange } from './inventory-change.js';
+export { inventoryByLocationTool, handleInventoryByLocation } from './inventory-by-location.js';

package/tools/inventario/inventory-by-location.js

@@ -0,0 +1,212 @@
+import { resolveStores } from '../../config/company-config.js';
+import { logger } from '../../utils/logger.js';
+import { isInventoryCategory } from './shared/cost-calculator.js';
+
+export const inventoryByLocationTool = {
+  name: 'get_inventory_by_location',
+  description:
+    'Inventario desglosado por ubicación (Location Code) dentro de una tienda. Muestra qty y valor por location, con detalle de ítems por cada una. Útil para ver distribución entre depósitos/almacenes internos. Usa OData V4 para acceder a Location_Code.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      store: {
+        type: 'string',
+        enum: ['FQ01', 'FQ28', 'FQ88'],
+        description: 'Tienda a consultar.',
+      },
+      location_code: {
+        type: 'string',
+        description: 'Filtrar por un Location Code específico (e.g. PRINCIPAL, DEPOSITO). Si se omite, muestra todas las ubicaciones.',
+      },
+      item_category: {
+        type: 'string',
+        description: 'Filtrar por itemCategoryCode (e.g. TERMINADO, INSUMO).',
+      },
+      classification: {
+        type: 'string',
+        description: 'Filtrar por inventoryPostingGroupCode (e.g. CONGELADOS, IMPORTADO, LOCAL).',
+      },
+      as_of_date: {
+        type: 'string',
+        description:
+          'Fecha de corte YYYY-MM-DD. Default: hoy (todas las entries). Si es fecha pasada, solo suma ledger entries con Posting_Date <= as_of_date.',
+      },
+    },
+    required: ['store'],
+  },
+};
+
+export async function handleInventoryByLocation(bcClient, args) {
+  const storeParam = args.store;
+  if (!storeParam) throw new Error('Parámetro requerido: store');
+
+  const stores = resolveStores([storeParam]);
+  const store = stores[0];
+  const companyId = store.companyId;
+
+  // 1. Fetch items via standard API (has itemCategoryCode, inventoryPostingGroupCode, unitCost)
+  const itemFilters = [];
+  if (args.item_category) {
+    itemFilters.push(`itemCategoryCode eq '${args.item_category}'`);
+  }
+  if (args.classification) {
+    itemFilters.push(`inventoryPostingGroupCode eq '${args.classification}'`);
+  }
+
+  const itemParams = {
+    $select: 'number,displayName,itemCategoryCode,inventoryPostingGroupCode,unitCost,inventory',
+  };
+  if (itemFilters.length > 0) {
+    itemParams.$filter = itemFilters.join(' and ');
+  }
+
+  const itemUrl = bcClient.buildApiUrl(companyId, 'items', itemParams);
+  const items = await bcClient.apiCallAllPages(itemUrl);
+  logger.info(`${store.code}: ${items.length} items fetched`);
+
+  // Build item metadata map — exclude items without inventoryPostingGroupCode and FQ-* categories
+  const itemMeta = {};
+  let excludedCount = 0;
+  for (const item of items) {
+    if (!item.inventoryPostingGroupCode || !isInventoryCategory(item.itemCategoryCode)) {
+      excludedCount++;
+      continue;
+    }
+    itemMeta[item.number] = {
+      name: item.displayName,
+      category: item.itemCategoryCode || 'SIN_CATEGORIA',
+      classification: item.inventoryPostingGroupCode,
+      unit_cost: item.unitCost || 0,
+      total_inventory: item.inventory || 0,
+    };
+  }
+  if (excludedCount > 0) {
+    logger.info(`${store.code}: excluded ${excludedCount} items without inventoryPostingGroupCode`);
+  }
+
+  // 2. Fetch item ledger entries via OData V4 (has Location_Code field)
+  const today = new Date();
+  const todayStr = today.toISOString().split('T')[0];
+  const asOfDate = args.as_of_date || todayStr;
+  const isHistorical = asOfDate < todayStr;
+
+  const odataFilters = [];
+  if (args.location_code) {
+    odataFilters.push(`Location_Code eq '${args.location_code}'`);
+  }
+  if (isHistorical) {
+    odataFilters.push(`Posting_Date le ${asOfDate}`);
+  }
+
+  const odataParams = {
+    $select: 'Item_No,Location_Code,Quantity',
+  };
+  if (odataFilters.length > 0) {
+    odataParams.$filter = odataFilters.join(' and ');
+  }
+
+  const ledgerUrl = bcClient.buildODataUrl(storeParam, 'ItemLedgerEntries', odataParams);
+  const entries = await bcClient.odataCallAllPages(ledgerUrl);
+  logger.info(`${store.code}: ${entries.length} item ledger entries fetched via OData V4 for location breakdown`);
+
+  // 3. Aggregate: { Location_Code → { Item_No → net_qty } }
+  const locationItems = {};
+
+  for (const e of entries) {
+    const loc = e.Location_Code || 'SIN_UBICACION';
+    const itemNo = e.Item_No;
+    const qty = e.Quantity || 0;
+
+    // Skip items not in our metadata (filtered out or no posting group)
+    if (!itemMeta[itemNo]) continue;
+
+    if (!locationItems[loc]) locationItems[loc] = {};
+    if (!locationItems[loc][itemNo]) locationItems[loc][itemNo] = 0;
+    locationItems[loc][itemNo] += qty;
+  }
+
+  // 4. Build response per location
+  const byLocation = {};
+  const locationSummaries = [];
+
+  for (const [loc, itemQtys] of Object.entries(locationItems)) {
+    let itemCount = 0;
+    let totalQty = 0;
+    let totalCostValue = 0;
+    const itemDetails = [];
+
+    for (const [itemNo, netQty] of Object.entries(itemQtys)) {
+      const roundedQty = round5(netQty);
+      if (roundedQty === 0) continue;
+
+      const meta = itemMeta[itemNo];
+      const costValue = round2(roundedQty * meta.unit_cost);
+
+      itemCount++;
+      totalQty = round5(totalQty + roundedQty);
+      totalCostValue = round2(totalCostValue + costValue);
+
+      itemDetails.push({
+        number: itemNo,
+        name: meta.name,
+        category: meta.category,
+        classification: meta.classification,
+        qty: roundedQty,
+        unit_cost: meta.unit_cost,
+        cost_value: costValue,
+      });
+    }
+
+    if (itemCount === 0) continue;
+
+    // Sort by absolute qty descending, keep top 10
+    itemDetails.sort((a, b) => Math.abs(b.qty) - Math.abs(a.qty));
+    const topItems = itemDetails.slice(0, 10);
+
+    byLocation[loc] = {
+      item_count: itemCount,
+      total_qty: round5(totalQty),
+      total_cost_value: round2(totalCostValue),
+      top_items: topItems,
+    };
+
+    locationSummaries.push({
+      location: loc,
+      item_count: itemCount,
+      total_qty: round5(totalQty),
+      total_cost_value: round2(totalCostValue),
+    });
+  }
+
+  // Sort summaries by cost value descending
+  locationSummaries.sort((a, b) => b.total_cost_value - a.total_cost_value);
+
+  // Grand totals
+  const grandTotal = {
+    locations: locationSummaries.length,
+    item_count: locationSummaries.reduce((s, l) => s + l.item_count, 0),
+    total_qty: round5(locationSummaries.reduce((s, l) => s + l.total_qty, 0)),
+    total_cost_value: round2(locationSummaries.reduce((s, l) => s + l.total_cost_value, 0)),
+  };
+
+  return {
+    store: store.code,
+    store_name: store.name,
+    as_of_date: asOfDate,
+    is_historical: isHistorical,
+    note: isHistorical
+      ? `Inventario histórico al ${asOfDate} reconstruido desde item ledger entries (OData V4) con Posting_Date <= ${asOfDate}, agrupado por Location_Code. unitCost es el actual de BC (no histórico).`
+      : 'Inventario reconstruido desde item ledger entries (OData V4) agrupado por Location_Code. Cada location muestra top 10 ítems por qty. unitCost es el actual de BC.',
+    summary: locationSummaries,
+    by_location: byLocation,
+    grand_total: grandTotal,
+  };
+}
+
+function round2(n) {
+  return Math.round(n * 100) / 100;
+}
+
+function round5(n) {
+  return Math.round(n * 100000) / 100000;
+}