@fullqueso/mcp-bc-gastos 1.28.0 → 1.33.0

package/tools/multi-payment/unposted-invoices.js

@@ -0,0 +1,224 @@
+// tools/multi-payment/unposted-invoices.js
+// Facturas de compra y venta SIN POSTEAR en Business Central (status Draft /
+// In Review en api/v2.0 purchaseInvoices y salesInvoices). A diferencia de los
+// tools de multi-payment (settlement de facturas ya posteadas), estos documentos
+// NO están en el GL todavía → son los ajustes de "Cierre Parcial" del P&L:
+//   compras draft → +COGS/gasto estimado; ventas draft → +ingreso estimado.
+// Consumido por skill-fq-resultados-mensual.
+
+import { resolveStores } from '../../config/company-config.js';
+import { logger } from '../../utils/logger.js';
+
+const round2 = (n) => Math.round((n + Number.EPSILON) * 100) / 100;
+
+export const unpostedInvoicesTool = {
+  name: 'get_unposted_invoices',
+  description:
+    'Facturas de compra y/o venta SIN POSTEAR en Business Central (status Draft o In Review). ' +
+    'Estos documentos NO están en el GL: son la base del ajuste de CIERRE PARCIAL del P&L ' +
+    '(compras draft → costo/gasto estimado; ventas draft → ingreso estimado). ' +
+    'NO confundir con get_draft_payables/receivables (Multi-Payments de cobro/pago sobre ' +
+    'facturas ya posteadas). Filtra por rango de postingDate, separa ventas intercompañía (IC-*) ' +
+    'y totaliza por moneda. Úsalo para: cierre parcial, resultados con drafts, facturas sin ' +
+    'postear, "qué falta por postear del mes". READ-ONLY.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      store: {
+        type: 'string',
+        enum: ['FQ01', 'FQ28', 'FQ88', 'FQFR', 'all'],
+        description: 'Tienda(s) a consultar.',
+      },
+      type: {
+        type: 'string',
+        enum: ['purchases', 'sales', 'both'],
+        description: 'Tipo de facturas. Default: both.',
+      },
+      start_date: {
+        type: 'string',
+        description: 'Fecha inicio YYYY-MM-DD (filtra por postingDate). Opcional.',
+      },
+      end_date: {
+        type: 'string',
+        description: 'Fecha fin YYYY-MM-DD (filtra por postingDate). Opcional.',
+      },
+      include_in_review: {
+        type: 'boolean',
+        description: "Incluir status 'In Review' además de 'Draft'. Default: true.",
+      },
+      summary_only: {
+        type: 'boolean',
+        description: 'Solo totales, sin lista de facturas. Default: false.',
+      },
+    },
+    required: ['store'],
+  },
+};
+
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+
+function buildStatusFilter(includeInReview) {
+  return includeInReview
+    ? "(status eq 'Draft' or status eq 'In Review')"
+    : "status eq 'Draft'";
+}
+
+function buildFilter(args) {
+  const parts = [buildStatusFilter(args.include_in_review !== false)];
+  if (args.start_date) {
+    if (!DATE_RE.test(args.start_date)) throw new Error(`start_date inválida: ${args.start_date}`);
+    parts.push(`postingDate ge ${args.start_date}`);
+  }
+  if (args.end_date) {
+    if (!DATE_RE.test(args.end_date)) throw new Error(`end_date inválida: ${args.end_date}`);
+    parts.push(`postingDate le ${args.end_date}`);
+  }
+  return parts.join(' and ');
+}
+
+function mapInvoice(inv, kind) {
+  return {
+    number: inv.number,
+    status: inv.status,
+    counterparty_number: kind === 'purchases' ? inv.vendorNumber : inv.customerNumber,
+    counterparty_name: kind === 'purchases' ? inv.vendorName : inv.customerName,
+    invoice_date: inv.invoiceDate,
+    posting_date: inv.postingDate,
+    currency: inv.currencyCode || 'LCY',
+    total_excl_tax: round2(inv.totalAmountExcludingTax ?? 0),
+    total_incl_tax: round2(inv.totalAmountIncludingTax ?? 0),
+  };
+}
+
+function summarize(invoices, kind) {
+  const by_currency = {};
+  const non_ic_by_currency = {};
+  const ic = { count: 0, by_currency: {} };
+  for (const inv of invoices) {
+    by_currency[inv.currency] = round2((by_currency[inv.currency] || 0) + inv.total_excl_tax);
+    const isIC = kind === 'sales' && String(inv.counterparty_number || '').toUpperCase().startsWith('IC-');
+    if (isIC) {
+      ic.count += 1;
+      ic.by_currency[inv.currency] = round2((ic.by_currency[inv.currency] || 0) + inv.total_excl_tax);
+    } else if (kind === 'sales') {
+      non_ic_by_currency[inv.currency] = round2((non_ic_by_currency[inv.currency] || 0) + inv.total_excl_tax);
+    }
+  }
+  const summary = {
+    count: invoices.length,
+    by_currency,
+    mixed_currency: Object.keys(by_currency).length > 1,
+    by_status: invoices.reduce((acc, i) => { acc[i.status] = (acc[i.status] || 0) + 1; return acc; }, {}),
+  };
+  if (kind === 'sales') {
+    summary.intercompany = ic;
+    summary.non_ic_by_currency = non_ic_by_currency;
+  }
+  return summary;
+}
+
+function fmtByCurrency(byCurrency) {
+  const parts = Object.entries(byCurrency).map(([cur, amt]) => {
+    const n = amt.toLocaleString('en-US', { minimumFractionDigits: 2 });
+    return cur === 'VES' ? `Bs ${n}` : `$${n}${cur === 'LCY' ? '' : ` ${cur}`}`;
+  });
+  return parts.join(' + ') || '0';
+}
+
+function mergeByCurrency(target, source) {
+  for (const [cur, amt] of Object.entries(source || {})) {
+    target[cur] = round2((target[cur] || 0) + amt);
+  }
+}
+
+async function fetchKind(bcClient, companyId, kind, filter) {
+  const endpoint = kind === 'purchases' ? 'purchaseInvoices' : 'salesInvoices';
+  const select = kind === 'purchases'
+    ? 'number,status,vendorNumber,vendorName,invoiceDate,postingDate,currencyCode,totalAmountExcludingTax,totalAmountIncludingTax'
+    : 'number,status,customerNumber,customerName,invoiceDate,postingDate,currencyCode,totalAmountExcludingTax,totalAmountIncludingTax';
+  const url = bcClient.buildApiUrl(companyId, endpoint, {
+    $filter: filter,
+    $select: select,
+    $orderby: 'postingDate desc',
+  });
+  const rows = await bcClient.apiCallAllPages(url);
+  return rows.map((r) => mapInvoice(r, kind));
+}
+
+async function processStore(bcClient, store, args, filter) {
+  const type = args.type || 'both';
+  const wantP = type === 'purchases' || type === 'both';
+  const wantS = type === 'sales' || type === 'both';
+
+  const [purchases, sales] = await Promise.all([
+    wantP ? fetchKind(bcClient, store.companyId, 'purchases', filter) : Promise.resolve(null),
+    wantS ? fetchKind(bcClient, store.companyId, 'sales', filter) : Promise.resolve(null),
+  ]);
+
+  const result = { store: store.code, store_name: store.name };
+  if (purchases) {
+    result.purchases = { summary: summarize(purchases, 'purchases') };
+    if (!args.summary_only) result.purchases.invoices = purchases;
+  }
+  if (sales) {
+    result.sales = { summary: summarize(sales, 'sales') };
+    if (!args.summary_only) result.sales.invoices = sales;
+  }
+  // Hint directo para el Cierre Parcial (skill-fq-resultados-mensual):
+  result.pl_adjustment_hint = {
+    purchases_by_currency: purchases ? result.purchases.summary.by_currency : null,
+    sales_non_ic_by_currency: sales ? result.sales.summary.non_ic_by_currency : null,
+    note: 'Estimación sin IVA de documentos no posteados en el rango. Montos VES convertir a USD con get_exchange_rate (BCV). No sustituye el posteo.',
+  };
+  return result;
+}
+
+export async function handleUnpostedInvoices(bcClient, args) {
+  if (!args.store) throw new Error('Parámetro requerido: store');
+  const filter = buildFilter(args);
+  const stores = resolveStores(args.store === 'all' ? null : [args.store]);
+
+  logger.info(`get_unposted_invoices: stores=${stores.map((s) => s.code).join(',')} filter="${filter}"`);
+
+  const storeResults = await Promise.all(
+    stores.map((s) => processStore(bcClient, s, args, filter))
+  );
+
+  const storesObj = {};
+  const consolidated = {
+    purchases_by_currency: {},
+    sales_by_currency: {},
+    sales_non_ic_by_currency: {},
+    invoice_count: 0,
+  };
+  const insights = [];
+
+  for (const r of storeResults) {
+    storesObj[r.store] = r;
+    if (r.purchases) {
+      mergeByCurrency(consolidated.purchases_by_currency, r.purchases.summary.by_currency);
+      consolidated.invoice_count += r.purchases.summary.count;
+      if (r.purchases.summary.count > 0) {
+        insights.push(`${r.store}: ${r.purchases.summary.count} factura(s) de compra sin postear por ${fmtByCurrency(r.purchases.summary.by_currency)} (sin IVA)`);
+      }
+    }
+    if (r.sales) {
+      mergeByCurrency(consolidated.sales_by_currency, r.sales.summary.by_currency);
+      mergeByCurrency(consolidated.sales_non_ic_by_currency, r.sales.summary.non_ic_by_currency);
+      consolidated.invoice_count += r.sales.summary.count;
+      if (r.sales.summary.count > 0) {
+        insights.push(`${r.store}: ${r.sales.summary.count} factura(s) de venta sin postear por ${fmtByCurrency(r.sales.summary.by_currency)} (sin IVA${r.sales.summary.intercompany.count ? `, ${r.sales.summary.intercompany.count} IC` : ''})`);
+      }
+    }
+  }
+
+  if (insights.length === 0) insights.push('Sin facturas pendientes de postear en el rango consultado.');
+
+  return {
+    filter_applied: filter,
+    period: { start: args.start_date || null, end: args.end_date || null },
+    stores: storesObj,
+    consolidated,
+    insights,
+  };
+}

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,10 +1,14 @@
 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: {
@@ -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', {

package/tools/payroll/payroll-documents.js

@@ -1,10 +1,17 @@
 import { resolveStores } from '../../config/company-config.js';
 import { logger } from '../../utils/logger.js';
+import { computeDocCost, round2, STORE_PAYROLL_TYPES, EVENT_PAYROLL_TYPES } from './cost-model.js';
+
+// Real document payrollType values in BC (discovered, not assumed — see LESSONS L-001):
+//   EVENTO, GERENCIAL, GERENCIAL_CIERRE, LIQUIDACION, SEMANAL, VACACIONES
+// The old enum [SEMANAL|QUINCENAL|MENSUAL] was wrong (QUINCENAL/MENSUAL don't exist).
+const DOC_PAYROLL_TYPES = ['SEMANAL', 'GERENCIAL', 'GERENCIAL_CIERRE', 'EVENTO', 'VACACIONES', 'LIQUIDACION'];
+const MANAGERIAL_TYPES = ['GERENCIAL', 'GERENCIAL_CIERRE'];
 
 export const payrollDocumentsTool = {
   name: 'get_payroll_documents',
   description:
-    'Lista documentos de nomina (headers) con filtros por periodo, tipo, status. Muestra totales por documento, cantidad de empleados, tasas de cambio. Soporta multi-tienda.',
+    'Lista documentos de nomina (headers) con filtros por periodo, tipo, status. Devuelve costo total en USD por documento (total_cost_usd, robusto a drafts sin distribuir), buckets store_payroll/event_payroll, tasas de cambio, y un summary con costo por tipo. Con include_employee_count agrega empleados unicos y pagados (dedup por cedula) para cruzar activos vs pagados. Soporta multi-tienda y excluir gerencia (exclude_managerial) para KPIs de nomina operativa.',
   inputSchema: {
     type: 'object',
     properties: {
@@ -19,8 +26,14 @@ export const payrollDocumentsTool = {
       },
       payroll_type: {
         type: 'string',
-        enum: ['SEMANAL', 'QUINCENAL', 'MENSUAL'],
-        description: 'Filtrar por tipo de nomina.',
+        enum: DOC_PAYROLL_TYPES,
+        description:
+          'Filtrar por tipo de documento de nomina. Valores reales: SEMANAL, GERENCIAL, GERENCIAL_CIERRE, EVENTO, VACACIONES, LIQUIDACION.',
+      },
+      exclude_managerial: {
+        type: 'boolean',
+        description:
+          'Excluir nomina gerencial (GERENCIAL + GERENCIAL_CIERRE) en un solo call → deja la nomina operativa. Default: false.',
       },
       status: {
         type: 'string',
@@ -35,6 +48,11 @@ export const payrollDocumentsTool = {
         type: 'string',
         description: 'Fecha fin (YYYY-MM-DD) para filtrar por documentDate.',
       },
+      include_employee_count: {
+        type: 'boolean',
+        description:
+          'Calcular empleados unicos + lista paid_employees (dedup por cedula, con costo/lineas/tipos/clasificacion) y duplicate_codes. Requiere leer las lineas de los docs filtrados (consultas extra, en lotes). Default: false.',
+      },
       summary_only: {
         type: 'boolean',
         description: 'Solo resumen (sin lista de documentos). Default: false.',
@@ -52,38 +70,82 @@ export async function handlePayrollDocuments(bcClient, args) {
   const summaryOnly = args.summary_only || false;
 
   if (stores.length === 1) {
-    return processStore(bcClient, stores[0], args, summaryOnly);
+    const r = await processStore(bcClient, stores[0], args, summaryOnly);
+    delete r.summary._paid_contribs;
+    return r;
   }
 
-  const results = await Promise.all(
+  // Resilient consolidation: one store failing/timing out must NOT hang or nuke
+  // 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, summaryOnly))
   );
 
+  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_documents: 0,
     total_employees_lines: 0,
+    total_cost_usd: 0,
+    store_payroll: 0,
+    event_payroll: 0,
     total_net_usd: 0,
     total_net_ves: 0,
     by_status: { Draft: 0, Posted: 0 },
     by_type: {},
   };
 
+  const allContribs = [];
+  let anyEmployeeCount = false;
+
   for (const r of results) {
     consolidated.total_documents += r.summary.total_documents;
     consolidated.total_employees_lines += r.summary.total_employees_lines;
+    consolidated.total_cost_usd += r.summary.total_cost_usd;
+    consolidated.store_payroll += r.summary.store_payroll;
+    consolidated.event_payroll += r.summary.event_payroll;
     consolidated.total_net_usd += r.summary.total_net_usd;
     consolidated.total_net_ves += r.summary.total_net_ves;
     consolidated.by_status.Draft += r.summary.by_status.Draft || 0;
     consolidated.by_status.Posted += r.summary.by_status.Posted || 0;
-    for (const [type, count] of Object.entries(r.summary.by_type)) {
-      consolidated.by_type[type] = (consolidated.by_type[type] || 0) + count;
+    for (const [type, agg] of Object.entries(r.summary.by_type)) {
+      const c = consolidated.by_type[type] || { count: 0, lines: 0, cost_usd: 0 };
+      c.count += agg.count;
+      c.lines += agg.lines;
+      c.cost_usd = round2(c.cost_usd + agg.cost_usd);
+      consolidated.by_type[type] = c;
+    }
+    if (r.summary._paid_contribs) {
+      anyEmployeeCount = true;
+      allContribs.push(...r.summary._paid_contribs);
     }
   }
 
+  consolidated.total_cost_usd = round2(consolidated.total_cost_usd);
+  consolidated.store_payroll = round2(consolidated.store_payroll);
+  consolidated.event_payroll = round2(consolidated.event_payroll);
   consolidated.total_net_usd = round2(consolidated.total_net_usd);
   consolidated.total_net_ves = round2(consolidated.total_net_ves);
 
-  return { stores: results, consolidated };
+  if (anyEmployeeCount) {
+    // Re-dedup across stores too (same cédula in two stores = one person).
+    const agg = aggregatePaidEmployees(allContribs);
+    consolidated.unique_employees = agg.unique_employees;
+    consolidated.paid_employees = agg.paid_employees;
+    consolidated.duplicate_codes = agg.duplicate_codes;
+  }
+
+  // Strip the internal contribution list from per-store summaries before returning.
+  for (const r of results) delete r.summary._paid_contribs;
+
+  const out = { stores: results, consolidated };
+  if (errors.length) out.errors = errors;
+  return out;
 }
 
 async function processStore(bcClient, storeInfo, args, summaryOnly) {
@@ -92,12 +154,16 @@ async function processStore(bcClient, storeInfo, args, summaryOnly) {
   const filters = [];
   if (args.period_code) filters.push(`periodCode eq '${args.period_code}'`);
   if (args.payroll_type) filters.push(`payrollType eq '${args.payroll_type}'`);
+  if (args.exclude_managerial) {
+    for (const t of MANAGERIAL_TYPES) filters.push(`payrollType ne '${t}'`);
+  }
   if (args.status) filters.push(`status eq '${args.status}'`);
   if (args.start_date) filters.push(`documentDate ge ${args.start_date}`);
   if (args.end_date) filters.push(`documentDate le ${args.end_date}`);
 
   const params = {
-    $select: 'documentNo,periodCode,payrollType,companyCode,documentDate,postingDate,paymentDate,status,lineCount,totalBonusesVES,totalBonusesUSD,totalNetUSD,totalNetVES,exchangeRate,createdBy,postedBy,createdDateTime,postedDateTime',
+    $select:
+      'documentNo,periodCode,payrollType,companyCode,documentDate,postingDate,paymentDate,status,lineCount,totalGrossUSD,totalDeductionsUSD,totalBonusesVES,totalBonusesUSD,totalNetUSD,totalNetVES,exchangeRate,createdBy,postedBy,createdDateTime,postedDateTime',
     $orderby: 'documentDate desc',
   };
   if (filters.length > 0) params.$filter = filters.join(' and ');
@@ -110,6 +176,9 @@ async function processStore(bcClient, storeInfo, args, summaryOnly) {
   const summary = {
     total_documents: data.length,
     total_employees_lines: 0,
+    total_cost_usd: 0,
+    store_payroll: 0,
+    event_payroll: 0,
     total_net_usd: 0,
     total_net_ves: 0,
     by_status: { Draft: 0, Posted: 0 },
@@ -122,12 +191,19 @@ async function processStore(bcClient, storeInfo, args, summaryOnly) {
     const lineCount = doc.lineCount || 0;
     const netUsd = doc.totalNetUSD || 0;
     const netVes = doc.totalNetVES || 0;
+    const cost = computeDocCost(doc);
 
     summary.total_employees_lines += lineCount;
+    summary.total_cost_usd += cost.total_cost_usd;
     summary.total_net_usd += netUsd;
     summary.total_net_ves += netVes;
     summary.by_status[doc.status] = (summary.by_status[doc.status] || 0) + 1;
-    summary.by_type[doc.payrollType] = (summary.by_type[doc.payrollType] || 0) + 1;
+
+    const typeAgg = summary.by_type[doc.payrollType] || { count: 0, lines: 0, cost_usd: 0 };
+    typeAgg.count += 1;
+    typeAgg.lines += lineCount;
+    typeAgg.cost_usd = round2(typeAgg.cost_usd + cost.total_cost_usd);
+    summary.by_type[doc.payrollType] = typeAgg;
 
     if (!summaryOnly) {
       documents.push({
@@ -140,6 +216,11 @@ async function processStore(bcClient, storeInfo, args, summaryOnly) {
         payment_date: doc.paymentDate,
         status: doc.status,
         line_count: lineCount,
+        total_cost_usd: cost.total_cost_usd,
+        cost_basis: cost.cost_basis,
+        net_distributed: cost.net_distributed,
+        total_gross_usd: round2(doc.totalGrossUSD || 0),
+        total_deductions_usd: round2(doc.totalDeductionsUSD || 0),
         total_bonuses_ves: round2(doc.totalBonusesVES || 0),
         total_bonuses_usd: round2(doc.totalBonusesUSD || 0),
         total_net_usd: round2(netUsd),
@@ -153,9 +234,28 @@ async function processStore(bcClient, storeInfo, args, summaryOnly) {
     }
   }
 
+  summary.total_cost_usd = round2(summary.total_cost_usd);
   summary.total_net_usd = round2(summary.total_net_usd);
   summary.total_net_ves = round2(summary.total_net_ves);
 
+  // #4 (buckets) — tienda vs eventos (gerencia queda solo en total_cost_usd).
+  summary.store_payroll = round2(
+    STORE_PAYROLL_TYPES.reduce((s, t) => s + (summary.by_type[t]?.cost_usd || 0), 0)
+  );
+  summary.event_payroll = round2(
+    EVENT_PAYROLL_TYPES.reduce((s, t) => s + (summary.by_type[t]?.cost_usd || 0), 0)
+  );
+
+  // #6/#1/#2/#3 — empleados pagados (dedup por cedula) en el periodo (opt-in).
+  if (args.include_employee_count) {
+    const contribs = await fetchPaidContribs(bcClient, companyId, data);
+    const agg = aggregatePaidEmployees(contribs);
+    summary.unique_employees = agg.unique_employees;
+    summary.paid_employees = agg.paid_employees;
+    summary.duplicate_codes = agg.duplicate_codes;
+    summary._paid_contribs = contribs; // internal, stripped before return
+  }
+
   const result = {
     store: storeInfo.code,
     store_name: storeInfo.name,
@@ -167,6 +267,90 @@ async function processStore(bcClient, storeInfo, args, summaryOnly) {
   return result;
 }
 
-function round2(n) {
-  return Math.round(n * 100) / 100;
+// Per-line contributions (one per employee-line) with the document's payrollType
+// and exchangeRate, so cost_usd = totalVESEquivalent / rate. Lines only filter by
+// documentNo → batch in OR-chunks to avoid N calls.
+async function fetchPaidContribs(bcClient, companyId, docs, chunkSize = 15) {
+  const docMap = {};
+  for (const d of docs) docMap[d.documentNo] = { payrollType: d.payrollType, rate: d.exchangeRate || 0 };
+  const documentNos = docs.map((d) => d.documentNo);
+
+  const contribs = [];
+  for (let i = 0; i < documentNos.length; i += chunkSize) {
+    const chunk = documentNos.slice(i, i + chunkSize);
+    const filter = chunk.map((no) => `documentNo eq '${no}'`).join(' or ');
+    const url = bcClient.buildPayrollApiUrl(companyId, 'fqPayrollLines', {
+      $filter: filter,
+      $select: 'documentNo,employeeCode,employeeName,cedulaDeIdentidad,totalVESEquivalent',
+    });
+    const lines = await bcClient.apiCallAllPages(url);
+    for (const l of lines) {
+      const dm = docMap[l.documentNo] || {};
+      const rate = dm.rate || 0;
+      contribs.push({
+        employee_code: l.employeeCode,
+        employee_name: l.employeeName,
+        cedula: l.cedulaDeIdentidad,
+        payroll_type: dm.payrollType,
+        cost_usd: rate ? (l.totalVESEquivalent || 0) / rate : 0,
+      });
+    }
+  }
+  return contribs;
+}
+
+// Aggregate line contributions into one record per PERSON, deduped by cédula.
+// A person with a SEMANAL code and an EVENTO code (same cédula) collapses into one
+// record; their codes are surfaced in duplicate_codes for BC cleanup. When cédula
+// is null/empty the code is treated as a unique person (never merge by name).
+export function aggregatePaidEmployees(contribs) {
+  // Pass 1: learn each code's cédula from ANY line that carries one, so a line
+  // with a blank cédula still collapses into that person (avoids splitting one
+  // code into two when the cédula is only populated on some weeks).
+  const codeToCedula = {};
+  for (const c of contribs) {
+    const ced = c.cedula != null && String(c.cedula).trim() ? String(c.cedula).trim() : null;
+    if (ced && c.employee_code && !codeToCedula[c.employee_code]) codeToCedula[c.employee_code] = ced;
+  }
+
+  const byPerson = new Map();
+  for (const c of contribs) {
+    const cedula =
+      (c.cedula != null && String(c.cedula).trim() ? String(c.cedula).trim() : null) ||
+      codeToCedula[c.employee_code] ||
+      null;
+    const key = cedula ? `ced:${cedula}` : `code:${c.employee_code}`;
+    let p = byPerson.get(key);
+    if (!p) {
+      p = { employee_code: c.employee_code, employee_name: c.employee_name || null, cedula, cost_usd: 0, lines: 0, types: new Set(), codes: new Set() };
+      byPerson.set(key, p);
+    }
+    p.cost_usd += c.cost_usd || 0;
+    p.lines += 1;
+    if (c.payroll_type) p.types.add(c.payroll_type);
+    if (c.employee_code) p.codes.add(c.employee_code);
+    if (!p.employee_name && c.employee_name) p.employee_name = c.employee_name;
+  }
+
+  const paid_employees = [];
+  const duplicate_codes = [];
+  for (const p of byPerson.values()) {
+    const codes = [...p.codes].sort();
+    const hasEvento = p.types.has('EVENTO');
+    const hasNonEvento = [...p.types].some((t) => t !== 'EVENTO');
+    const classification = hasEvento && hasNonEvento ? 'mixto' : hasEvento ? 'evento' : 'operativo';
+    paid_employees.push({
+      employee_code: p.employee_code,
+      employee_name: p.employee_name,
+      cedula: p.cedula,
+      cost_usd: round2(p.cost_usd),
+      lines: p.lines,
+      payroll_types: [...p.types].sort(),
+      classification,
+    });
+    if (p.cedula && codes.length > 1) duplicate_codes.push({ cedula: p.cedula, codes });
+  }
+
+  paid_employees.sort((a, b) => b.cost_usd - a.cost_usd);
+  return { unique_employees: byPerson.size, paid_employees, duplicate_codes };
 }