@fullqueso/mcp-bc-gastos 1.27.0 → 1.31.0

package/tools/get-crm-rate.js

@@ -0,0 +1,109 @@
+// tools/get-crm-rate.js
+// Tasa de cambio Bs/USD desde el CRM de Full Queso (hora Caracas).
+// Fuente: https://crm-rate.fullqueso.com
+//   - USDT == Binance == tasa paralelo
+//   - VES  == BCV     == tasa oficial
+// Histórica (con fecha) o del día (sin fecha).
+
+import { DateTime } from 'luxon';
+
+const CRM_RATE_BASE =
+  process.env.CRM_RATE_BASE || 'https://crm-rate.fullqueso.com/api/v1';
+
+// Normaliza el coin del usuario al símbolo del endpoint.
+function normalizeCoin(raw) {
+  const c = String(raw || '').trim().toUpperCase();
+  if (['USDT', 'BINANCE', 'PARALELO', 'PARALELA'].includes(c)) {
+    return { history: 'USDT', live: 'usdt', label: 'USDT/Binance' };
+  }
+  if (['VES', 'BCV', 'OFICIAL', 'BS'].includes(c)) {
+    return { history: 'VES', live: 'bcv', label: 'BCV (oficial)' };
+  }
+  return null;
+}
+
+export const crmRateTool = {
+  name: 'get_crm_rate',
+  description:
+    'Obtiene la tasa de cambio Bs/USD desde el CRM de Full Queso (hora Caracas). ' +
+    'Dos monedas: USDT (equivalente a la tasa Binance / paralelo) y VES (tasa BCV oficial). ' +
+    'Si se pasa una fecha (YYYY-MM-DD) retorna la tasa histórica guardada de ese día; ' +
+    'si se omite la fecha retorna la tasa del momento de la consulta. ' +
+    'Usar SIEMPRE que se pida: tasa USDT, tasa Binance, dólar Binance, tasa paralelo/paralela, ' +
+    'tasa BCV, tasa oficial, tasa del día o tasa histórica de una fecha. ' +
+    'Para tasa BCV vigente contable en Business Central usar get_exchange_rate; este tool es la tasa de referencia del CRM.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      coin: {
+        type: 'string',
+        enum: ['USDT', 'BINANCE', 'VES', 'BCV'],
+        description:
+          'Moneda/tasa. USDT y BINANCE son equivalentes (paralelo). VES y BCV son equivalentes (oficial BCV).',
+      },
+      date: {
+        type: 'string',
+        description:
+          'Fecha histórica (YYYY-MM-DD), hora Caracas. Si se omite, devuelve la tasa actual.',
+      },
+    },
+    required: ['coin'],
+  },
+};
+
+export async function handleGetCrmRate(_bcClient, args) {
+  const coin = normalizeCoin(args.coin);
+  if (!coin) {
+    throw new Error(
+      `coin inválido: "${args.coin}". Válidos: USDT/BINANCE (paralelo) o VES/BCV (oficial).`
+    );
+  }
+
+  const isHistorical = !!args.date;
+  let url;
+  if (isHistorical) {
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(args.date)) {
+      throw new Error(`date inválida: "${args.date}". Formato esperado YYYY-MM-DD.`);
+    }
+    url = `${CRM_RATE_BASE}/history/price?coin=${coin.history}&date=${args.date}`;
+  } else {
+    url = `${CRM_RATE_BASE}/coin/${coin.live}`;
+  }
+
+  let res;
+  try {
+    res = await fetch(url, { headers: { Accept: 'application/json' } });
+  } catch (e) {
+    throw new Error(`No se pudo conectar al CRM de tasas (${CRM_RATE_BASE}): ${e.message}`);
+  }
+
+  if (res.status === 400) {
+    throw new Error('CRM 400: coin o date inválidos.');
+  }
+  if (res.status === 404) {
+    return {
+      coin: coin.label,
+      date: args.date || null,
+      price: null,
+      message: `No hay registro de tasa ${coin.label} para ${args.date}.`,
+    };
+  }
+  if (!res.ok) {
+    throw new Error(`CRM respondió ${res.status} en ${url}`);
+  }
+
+  const data = await res.json();
+  const nowCcs = DateTime.now().setZone('America/Caracas');
+  const price =
+    typeof data.price === 'number' ? Math.round(data.price * 100) / 100 : data.price;
+
+  return {
+    coin: coin.label,
+    type: isHistorical ? 'historica' : 'del_dia',
+    date: isHistorical ? args.date : nowCcs.toISODate(),
+    queried_at_caracas: nowCcs.toFormat('yyyy-MM-dd HH:mm:ss'),
+    price,
+    label: `1 USD = ${price} Bs (${coin.label})`,
+    source: url,
+  };
+}

package/tools/get-exchange-rate.js

@@ -10,7 +10,7 @@ export const exchangeRateTool = {
     properties: {
       store: {
         type: 'string',
-        enum: ['FQ01', 'FQ28', 'FQ88'],
+        enum: ['FQ01', 'FQ28', 'FQ88', 'FQFR'],
         description: 'Tienda a consultar.',
       },
       date: {

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

@@ -11,7 +11,7 @@ export const inventoryByLocationTool = {
     properties: {
       store: {
         type: 'string',
-        enum: ['FQ01', 'FQ28', 'FQ88'],
+        enum: ['FQ01', 'FQ28', 'FQ88', 'FQFR'],
         description: 'Tienda a consultar.',
       },
       location_code: {

package/tools/inventario/inventory-change.js

@@ -11,7 +11,7 @@ export const inventoryChangeTool = {
     properties: {
       store: {
         type: 'string',
-        enum: ['FQ01', 'FQ28', 'FQ88'],
+        enum: ['FQ01', 'FQ28', 'FQ88', 'FQFR'],
         description: 'Tienda a consultar.',
       },
       period: {

package/tools/inventario/inventory-levels.js

@@ -11,7 +11,7 @@ export const inventoryLevelsTool = {
     properties: {
       store: {
         type: 'string',
-        enum: ['FQ01', 'FQ28', 'FQ88'],
+        enum: ['FQ01', 'FQ28', 'FQ88', 'FQFR'],
         description: 'Tienda a consultar.',
       },
       item_category: {

package/tools/inventario/item-card.js

@@ -11,7 +11,7 @@ export const itemCardTool = {
     properties: {
       store: {
         type: 'string',
-        enum: ['FQ01', 'FQ28', 'FQ88'],
+        enum: ['FQ01', 'FQ28', 'FQ88', 'FQFR'],
         description: 'Tienda a consultar.',
       },
       item_number: {

package/tools/inventario/item-cost-trend.js

@@ -10,7 +10,7 @@ export const itemCostTrendTool = {
     properties: {
       store: {
         type: 'string',
-        enum: ['FQ01', 'FQ28', 'FQ88'],
+        enum: ['FQ01', 'FQ28', 'FQ88', 'FQFR'],
         description: 'Tienda a consultar.',
       },
       item_number: {

package/tools/inventario/item-ledger-entries.js

@@ -10,7 +10,7 @@ export const itemLedgerEntriesTool = {
     properties: {
       store: {
         type: 'string',
-        enum: ['FQ01', 'FQ28', 'FQ88'],
+        enum: ['FQ01', 'FQ28', 'FQ88', 'FQFR'],
         description: 'Tienda a consultar.',
       },
       item_number: {

package/tools/inventario/item-value-entries.js

@@ -10,7 +10,7 @@ export const itemValueEntriesTool = {
     properties: {
       store: {
         type: 'string',
-        enum: ['FQ01', 'FQ28', 'FQ88'],
+        enum: ['FQ01', 'FQ28', 'FQ88', 'FQFR'],
         description: 'Tienda a consultar.',
       },
       item_number: {

package/tools/list-vendors.js

@@ -12,7 +12,7 @@ export const listVendorsTool = {
     properties: {
       store: {
         type: 'string',
-        enum: ['FQ01', 'FQ28', 'FQ88'],
+        enum: ['FQ01', 'FQ28', 'FQ88', 'FQFR'],
         description: 'Tienda a consultar.',
       },
       start_date: {

package/tools/multi-payment/draft-payables.js

@@ -12,7 +12,7 @@ export const draftPayablesTool = {
     properties: {
       store: {
         type: 'string',
-        enum: ['FQ01', 'FQ28', 'FQ88', 'all'],
+        enum: ['FQ01', 'FQ28', 'FQ88', 'FQFR', 'all'],
         description: 'Tienda(s) a consultar.',
       },
       status_filter: {

package/tools/multi-payment/draft-receivables.js

@@ -12,7 +12,7 @@ export const draftReceivablesTool = {
     properties: {
       store: {
         type: 'string',
-        enum: ['FQ01', 'FQ28', 'FQ88', 'all'],
+        enum: ['FQ01', 'FQ28', 'FQ88', 'FQFR', 'all'],
         description: 'Tienda(s) a consultar.',
       },
       status_filter: {

package/tools/multi-payment/draft-summary.js

@@ -10,7 +10,7 @@ export const draftSummaryTool = {
     properties: {
       store: {
         type: 'string',
-        enum: ['FQ01', 'FQ28', 'FQ88', 'all'],
+        enum: ['FQ01', 'FQ28', 'FQ88', 'FQFR', 'all'],
         description: 'Tienda(s) a consultar.',
       },
     },

package/tools/payroll/cost-model.js

@@ -0,0 +1,51 @@
+// Single source of truth for "how much did this payroll document cost", in USD.
+//
+// Grounded in 448 real BC documents (tests/validate-payroll-cost-model.js):
+//   - Undistributed Drafts:    totalGrossUSD = 0, totalNet* = 0, only totalBonuses* carries value.
+//   - Posted / Accrued docs:   totalGrossUSD is populated and equals the real cost.
+//   - VACACIONES / LIQUIDACION: net is double-booked (the same amount lands in BOTH
+//                              totalNetUSD *and* totalNetVES) → `net_usd + net_ves/rate`
+//                              DOUBLE-COUNTS. Never use that sum as the cost.
+//
+// Rule (in order): cost = totalGrossUSD (>0)  →  else bonuses-equivalent  →  else net (MAX, not sum).
+// `cost_basis` records which branch was used so the number is auditable, and
+// `net_distributed` flags drafts whose net hasn't been split across payment methods yet.
+
+const EPS = 0.005;
+
+// Payroll-cost buckets for the store-vs-events KPI. Managerial (GERENCIAL /
+// GERENCIAL_CIERRE) is neither → stays only in total_cost_usd.
+export const STORE_PAYROLL_TYPES = ['SEMANAL', 'VACACIONES', 'LIQUIDACION'];
+export const EVENT_PAYROLL_TYPES = ['EVENTO'];
+
+export function round2(n) {
+  return Math.round(n * 100) / 100;
+}
+
+export function computeDocCost(doc) {
+  const rate = doc.exchangeRate || 0;
+  const grossUsd = doc.totalGrossUSD || 0;
+  const bonusUsdEq = (doc.totalBonusesUSD || 0) + (rate ? (doc.totalBonusesVES || 0) / rate : 0);
+  // max() (not sum) guards against net booked in both currencies (the double-count above).
+  const netUsdEq = Math.max(doc.totalNetUSD || 0, rate ? (doc.totalNetVES || 0) / rate : 0);
+
+  let cost, basis;
+  if (grossUsd > EPS) {
+    cost = grossUsd;
+    basis = 'gross';
+  } else if (bonusUsdEq > EPS) {
+    cost = bonusUsdEq;
+    basis = 'bonuses';
+  } else {
+    cost = netUsdEq;
+    basis = 'net';
+  }
+
+  const netDistributed = (doc.totalNetUSD || 0) !== 0 || (doc.totalNetVES || 0) !== 0;
+
+  return {
+    total_cost_usd: round2(cost),
+    cost_basis: basis,          // 'gross' | 'bonuses' | 'net' — which field the cost came from
+    net_distributed: netDistributed, // false = Draft not yet split across payment methods (#3)
+  };
+}

package/tools/payroll/employees.js

@@ -1,16 +1,20 @@
 import { resolveStores } from '../../config/company-config.js';
 import { logger } from '../../utils/logger.js';
 
+// Real employee payrollType values in BC (discovered, not assumed — see L-001):
+//   EVENTO, GERENCIAL, SEMANAL. (QUINCENAL/MENSUAL never existed.)
+const EMPLOYEE_PAYROLL_TYPES = ['SEMANAL', 'GERENCIAL', 'EVENTO'];
+
 export const employeesTool = {
   name: 'get_employees',
   description:
-    'Lista empleados de una tienda con datos de nomina: tipo, status, salarios base, bonos predeterminados, fechas. Filtros por status, tipo de nomina, busqueda por nombre.',
+    'Lista empleados de una tienda con datos de nomina: tipo, status, salarios base, bonos predeterminados, fechas. Filtros por status, tipo de nomina, y exclude_managerial para headcount operativo. Soporta multi-tienda (resiliente: una tienda que falle no tumba el consolidado).',
   inputSchema: {
     type: 'object',
     properties: {
       store: {
         type: 'string',
-        enum: ['FQ01', 'FQ28', 'FQ88', 'all'],
+        enum: ['FQ01', 'FQ28', 'FQ88', 'FQFR', 'all'],
         description: 'Tienda(s) a consultar.',
       },
       status: {
@@ -20,8 +24,13 @@ export const employeesTool = {
       },
       payroll_type: {
         type: 'string',
-        enum: ['SEMANAL', 'QUINCENAL', 'MENSUAL'],
-        description: 'Filtrar por tipo de nomina.',
+        enum: EMPLOYEE_PAYROLL_TYPES,
+        description: 'Filtrar por tipo de nomina. Valores reales de empleado: SEMANAL, GERENCIAL, EVENTO.',
+      },
+      exclude_managerial: {
+        type: 'boolean',
+        description:
+          'Excluir empleados gerenciales (payrollType GERENCIAL / employeeType Management) → headcount operativo. Default: false.',
       },
       employee_search: {
         type: 'string',
@@ -46,10 +55,19 @@ export async function handleEmployees(bcClient, args) {
     return processStore(bcClient, stores[0], args);
   }
 
-  const results = await Promise.all(
+  // Resilient consolidation: a single store hanging/failing must not take down
+  // the whole "all" response (root cause behind BUG #1). See L-015 / L-016.
+  const settled = await Promise.allSettled(
     stores.map((s) => processStore(bcClient, s, args))
   );
 
+  const results = [];
+  const errors = [];
+  settled.forEach((r, i) => {
+    if (r.status === 'fulfilled') results.push(r.value);
+    else errors.push({ store: stores[i].code, error: String(r.reason?.message || r.reason) });
+  });
+
   const consolidated = {
     total_employees: 0,
     by_status: {},
@@ -70,7 +88,9 @@ export async function handleEmployees(bcClient, args) {
     }
   }
 
-  return { stores: results, consolidated };
+  const out = { stores: results, consolidated };
+  if (errors.length) out.errors = errors;
+  return out;
 }
 
 async function processStore(bcClient, storeInfo, args) {
@@ -79,6 +99,10 @@ async function processStore(bcClient, storeInfo, args) {
 
   const filters = [`companyCode eq '${storeInfo.code}'`, `status eq '${status}'`];
   if (args.payroll_type) filters.push(`payrollType eq '${args.payroll_type}'`);
+  if (args.exclude_managerial) {
+    filters.push(`payrollType ne 'GERENCIAL'`);
+    filters.push(`employeeType ne 'Management'`);
+  }
   if (args.employee_code) filters.push(`employeeCode eq '${args.employee_code}'`);
 
   const url = bcClient.buildPayrollApiUrl(companyId, 'fqEmployees', {