================================================================================
Documentación: consultas de contexto para el chat IA (beeStock)
================================================================================
Ruta base: public/server/php/ia/

Estos archivos construyen el JSON / datos que se envían al modelo como contexto
para responder en el chat. No son endpoints por sí solos: suelen incluirse desde
los controladores PHP del IA según la entidad y el registro en pantalla.

Convenciones comunes
--------------------
- $con: conexión mysqli.
- $recordId: ID del registro principal (cliente, ítem, compra, venta, etc.).
- Muchas consultas usan SET SESSION group_concat_max_len para permitir cadenas
  largas en GROUP_CONCAT + JSON_OBJECT.
- Los subselects suelen devolver un array JSON como texto; el PHP hace
  json_decode sobre cada columna antes de devolver el resultado.

================================================================================
customer / customer_query.php
================================================================================
Propósito
  Contexto del chat IA para UN cliente (customer.id = $recordId).

Salida
  Array de filas (normalmente una): identificación del cliente más varios
  arrays JSON ya decodificados.

Bloques de datos (columnas → significado)
  - sales: ventas del cliente (sale): id, code, sale_date, grand_total,
    paid_amount, payment_status.
  - sale_items: líneas sale_vs_item ligadas a esas ventas: saleId, qty, price,
    total, selling_type.
  - returns: devoluciones sale_vs_return: saleId, lost_qty, lost_price, date.
  - behavior_history: sales_behaivor_history por cliente: profit, roi, date,
    item_id.
  - item_behavior: item_customer_behaivor_history: item_id, roi_star,
    profit_star, profit.
  - credits_paid: customer_credit_vs_paid_sale (vinculado a ventas del
    cliente): sale_id, sent_amount, type 'paid_sale'.

================================================================================
item / item_query.php
================================================================================
Propósito
  Contexto del chat IA para UN producto / ítem (item.id = $recordId).

Salida
  Array de filas con item_id, item_name, item_brand y arrays decodificados.

Bloques de datos
  - pvi: líneas purchase_vs_item del ítem: qty, unit_price, selling_price,
    total_price, sold_qty, returned_qty, lost_qty.
  - svi: líneas sale_vs_item enlazadas por purchase_vs_itemId: selling_type,
    cost, cogs_row_amount, item_unit_cost, qty, returned_qty, price, total.
  - ibhm: item_behaivor_history_month: profit, inversion, speed, friction,
    roi, perishable, last_update.
  - ipbh: item_provider_behaivor_history con nombre de proveedor: roi_star,
    profit_star, provider.
  - icbh: item_customer_behaivor_history con nombre de cliente: roi_star,
    profit_star, customer.

    [0].behavior_history: 
    - {
        "profit": 63.48,
        "roi": 11.79,
        "date": "2024-06-16",
        "item_id": 112
      }
    [0].customer_id: 55
    [0].customer_name: IGUA PRODUCE, INC. 
    [0].item_behavior: 
    - {
      "item_id": 44,
      "roi_star": 1,
      "profit_star": 1,
      "profit": -3695.46
    }
    [0].returns:
    - {
      "saleId": 1640,
      "lost_qty": 64,
      "lost_price": 3200,
      "date": "2024-10-03"
    }
    [0].sale_items: 
    - {
      "saleId": 117,
      "qty": 43,
      "price": 14,
      "total": 602,
      "selling_type": "BOX"
    }
    [0].sales:
    - {
      "id": 117,
      "code": "INV000117",
      "sale_date": "2024-06-16",
      "grand_total": 12037.5,
      "paid_amount": 12037.5,
      "payment_status": "paid"
    }

================================================================================
item / itemAll_query.php
================================================================================
Propósito
  Vista resumida de TODO el inventario (todos los ítems no eliminados) para
  contextos que necesitan el catálogo completo sin el detalle de item_query.

Salida
  Array de filas, una por ítem.

Campos por fila
  - item_id, item_name, item_brand
  - current_stock: SUM(pvi.qty - sold_qty - returned_qty - lost_qty) por ítem.
  - avg_cost: promedio de unit_price en purchase_vs_item.
  - latest_price: último selling_price del purchase_vs_item (por id DESC).
  - latest_behavior: un JSON_OBJECT con la fila más reciente de
    item_behaivor_history_month (profit, inversion, roi, speed, last_update).

  {
    "item_id": "2",
    "item_name": "Avocado",
    "item_brand": "HASH",
    "current_stock": 0,
    "avg_cost": 15.25,
    "latest_price": 2,
    "latest_behavior": {
      "profit": 0,
      "inversion": 20,
      "roi": 0,
      "speed": 0,
      "last_update": "2025-08-31"
    }
  }

================================================================================
provider / provider_query.php
================================================================================
Propósito
  Contexto del chat IA para UN proveedor (provider.id = $recordId).

Salida
  Array de filas con datos del proveedor y arrays decodificados.

Bloques de datos
  - purchases: compras (purchase): id, code, purchase_date, general_total_price,
    paid_amount, payment_status.
  - purchase_items: purchase_vs_item de ese proveedor: purchaseId, item_id,
    qty, unit_price, total_price, sold_qty.
  - lost_items: purchase_vs_lost: purchaseId, lost_qty, lost_price, date,
    notes.
  - expenses: purchase_vs_expenses del proveedor: purchaseId, amount,
    paid_amount, payment_status, date.
  - credits: providercredit: id, code, amount, date.
  - behavior_month: provider_behaivor_history_month: profit, roi,
    last_update.
  - purchase_behavior: purchase_behaivor_history: purchase_id, item_id,
    inversion, profit, roi, date.
  - item_behavior: item_provider_behaivor_history: item_id, roi_star,
    profit_star, profit.

  [0].behavior_month: 
  - {
    "profit": 6132.9,
    "roi": 42.32,
    "last_update": "2024-07-31"
  }
  [0].item_behavior: 
  - {
    "item_id": 602,
    "roi_star": 1,
    "profit_star": 1,
    "profit": -83436
  }
  [0].lost_items:
  - {
    "purchaseId": 1018,
    "lost_qty": 104,
    "lost_price": 832,
    "date": "2025-04-14",
    "notes": "RETURN  104"
  }
  [0].provider_id: 425
  [0].provider_name: WILLIAMS CATTLE
  [0].provider_type: Inventory
  [0].purchase_behavior: 
  - {
    "purchase_id": 199,
    "item_id": 370,
    "inversion": 3840,
    "profit": 4732,
    "roi": 123.23,
    "date": "2024-07-24"
  }
  [0].purchase_items:
  - {
    "purchaseId": 199,
    "item_id": 370,
    "qty": 960,
    "unit_price": 4,
    "total_price": 3840,
    "sold_qty": 960
  }
  [0].purchases:
  - {
    "id": 199,
    "code": "PU000199",
    "purchase_date": "2024-07-24",
    "general_total_price": 14490.1,
    "paid_amount": 14490.1,
    "payment_status": "paid"
  }

================================================================================
purchase / purchase_query.php
================================================================================
Propósito
  Contexto del chat IA para UNA compra guardada (purchase.id = $recordId).

Salida
  Array de filas con purchase_id y subestructuras.

Bloques de datos
  - pvi: líneas de la compra con item embebido (name, brand) en item_data.
  - svi: sale_vs_item ligadas a las líneas purchase_vs_item de esa compra
    (mismos campos de coste/venta que en item_query).
  - ibhm: métricas mensuales por ítem presente en la compra
    (item_behaivor_history_month).
  - ipbh / icbh: estrellas por ítem con proveedor y cliente respectivamente
    (solo roi_star, profit_star en el JSON agregado).

  [0].ibhm:
  - {
    "profit": 1450,
    "inversion": 21304,
    "speed": 3,
    "friction": 5,
    "roi": 6.81,
    "perishable": 0,
    "last_update": "2024-06-30"
  }
  [0].icbh:
  - {
    "roi_star": 1,
    "profit_star": 1
  }
  [0].ipbh:
  - {
    "roi_star": 1,
    "profit_star": 1
  }
  [0].purchase_id: 2351
  [0].pvi:
  - {
    "qty": 140,
    "unit_price": 34,
    "selling_price": 40,
    "total_price": 4760,
    "sold_qty": 0,
    "returned_qty": 0,
    "lost_qty": 0,
    "item_data": {
      "name": "LIME",
      "brand": "PERSIAN"
    }
  }
  [0].svi:
  - [{"selling_type": "230-SIZE", "cost": 34.00, "cogs_row_amount": 0.00, "item_unit_cost": "", "qty": 15.00, "returned_qty": 0, "price": 38.00, "total": 570.00}]

================================================================================
purchase / purchaseBefore_query.php
================================================================================
Propósito
  Contexto “antes de guardar la compra”: cotización en curso con proveedor
  e ítems seleccionados (no usa $recordId de compra).

Entradas esperadas (variables externas)
  - $provider_id: ID del proveedor.
  - $items_array: lista de IDs de ítem; si vacía, los filtros por ítem quedan
    sin filas útiles (IN (-1) / AND 1=0 según subconsulta).

Salida
  Una sola fila asociativa (asignada directamente a $contextoRows en el
  include), con objetos/arrays JSON decodificados:

  - info_provider: id, nombre, credito_disponible, credito_usado del
    proveedor (incluye lógica de deuda y créditos de proveedor).
  - historial_financiero_proveedor: filas de provider_behaivor_history_month.
  - historial_compras_especificas: item_provider_behaivor_history filtrado
    por proveedor e ítems del array.
  - metricas_items_globales: item_behaivor_history_month + nombre de ítem
    para los ítems del array.
  - inventario_compras_previas: purchase_vs_item histórico (qty comprada,
    disponible, costos y precios de venta pasados) para esos ítems.

  {
      "datos_generales": {
          "estado": "delivered",
          "fecha_emision": "2026-04-06",
          "fecha_entrega": "2026-04-08",
          "terminos_legales": "The perishable agricultural commodities listed on this invoice are sold subject to the statutory trust authorized by section 5(c) of the Perishable Agricultural Commodities Act, 1930 (7 U.S.C. 499e(c)). The seller of these commodities retains a trust claim over these commodities, all inventories of food or other products derived from these commodities, and any receivables or proceeds from the sale of these commodities until full payment is received."
      },
      "productos_a_comprar": [
          {
              "id_producto": "2",
              "cantidad": "",
              "precio_unitario": "",
              "precio_venta": "",
              "precio_total": ""
          }
      ]
  }
  {
      "id": 7,
      "nombre": "Cotsco LLC.",
      "credito_disponible": 0,
      "credito_usado": 0
  }
  inventario_compras_previas:
  - {
    "item_id": 2,
    "compra_nro": 515,
    "qty_comprada": 165,
    "qty_disponible": 0,
    "costo_unitario_pasado": 5,
    "precio_venta_pasado": 10
  }
  metricas_items_globales:
  - {
    "item_name": "Avocado",
    "item_id": 2,
    "profit": 165,
    "inversion": 825,
    "speed": 0,
    "friction": 1,
    "roi": 20,
    "perishable": 0,
    "last_update": "2024-10-31"
  }

================================================================================
sale / sale_query.php
================================================================================
Propósito
  Contexto del chat IA para UNA venta guardada (sale.id = $recordId).

Salida
  Array de filas con cabecera de venta + cliente y varios arrays decodificados.

Bloques de datos
  - Datos de la venta: sale_id, code, sale_date, grand_total, paid_amount,
    payment_status, sale_notes; customer_id, customer_name.
  - sale_items: líneas sale_vs_item de esa venta.
  - sale_returns: sale_vs_return (la consulta filtra svr.deleted = 1).
  - sale_credits_paid: créditos aplicados a esa venta
    (customer_credit_vs_paid_sale).
  - customer_all_sales: todas las ventas del mismo cliente.
  - customer_behavior_history: sales_behaivor_history del cliente.
  - customer_item_behavior: item_customer_behaivor_history del cliente.
  - customer_all_credits: créditos pagados del cliente en el tiempo
    (vía join con sus ventas).

  [0].customer_all_sales:
  - {
    "id": 248,
    "code": "INV000248",
    "sale_date": "2024-06-24",
    "grand_total": 2316,
    "payment_status": "paid"
  }
  [0].customer_behavior_history:
  - {
    "profit": 22.08,
    "roi": 2.14,
    "date": "2024-06-24",
    "item_id": 534
  }
  [0].customer_id: 44
  [0].customer_item_behavior:
  - {
    "item_id": 604,
    "roi_star": 1,
    "profit_star": 1,
    "profit": -63.73
  }
  [0].customer_name: EL COMPADRE
  [0].paid_amount: 0.00
  [0].grand_total: 2819.00
  [0].payment_status: unpaid
  [0].sale_code: INV010025
  [0].sale_date: 2026-02-18
  [0].sale_id: 10025
  [0].sale_items:
  - {
    "id": 56462,
    "selling_type": "BOX",
    "qty": 1,
    "price": 19,
    "total": 19,
    "cost": 16.5
  }
  [0].sale_notes
  [0].sale_returns

================================================================================
sale / saleAll_query.php
================================================================================
Propósito
  Contexto agregado para el chat “todas las ventas”: muestras limitadas de
  inventario, clientes, pares ítem–cliente y líneas de venta recientes.

Salida
  Arreglo asociativo $contextoRows con:
  - meta: description + limits (150 ítems, 120 clientes, 120 pares, 120
    líneas de venta recientes).
  - items_inventory: por ítem — stock actual, costo unitario medio, último
    precio de venta (misma lógica que itemAll en parte).
  - customers: cliente con credit_limit y total_due_outstanding (deuda de
    ventas no pagadas/creditadas).
  - item_customer_pairs: última fila por par (item_id, customer_id) en
    item_customer_behaivor_history, ordenada por profit.
  - recent_sale_lines: últimas líneas de venta con cliente e ítem resueltos.

  customers:
  - {
    "customer_id": "106",
    "customer_name": " LOS POLINES  PRODUCE CORP",
    "customer_code": "C0106",
    "credit_limit": 0,
    "total_due_outstanding": 0
  }
  item_customer_pairs:
  - {
    "item_id": "352",
    "item_name": "PLANTAIN GREEN",
    "item_brand": "",
    "current_stock": 3794,
    "avg_unit_cost": 20.9768,
    "latest_selling_price": 22
  }
  meta:
  - meta.description: Inventario por ítem, resumen de clientes, rendimiento histórico ítem–cliente y líneas de venta recientes.
  - meta.limits:
    - {
      "items_inventory": 150,
      "customers": 120,
      "item_customer_pairs": 120,
      "recent_sale_lines": 120
    }
  recent_sale_lines:
  - {
    "sale_id": "10025",
    "sale_code": "INV010025",
    "sale_date": "2026-02-18",
    "customer_id": "44",
    "customer_name": "EL COMPADRE ",
    "item_id": "84",
    "item_name": "CILLANTRO MEX",
    "qty": 1,
    "price": 19
  }

================================================================================
sale / saleBefore_query.php
================================================================================
Propósito
  Contexto “antes de guardar la venta”: cliente e ítems en la cotización.

Entradas esperadas
  - $items_array: IDs de ítem.
  - $provider_id: nombre engañoso en código — aquí se usa como ID de CLIENTE
    ($customer_id_safe). Conviene tenerlo en cuenta al mantener el front/back.

Salida
  Una fila asociativa con JSON decodificado:

  - info_customer: id, nombre, credito_disponible, credito_usado, deuda_total.
  - historial_financiero_cliente: customer_behaivor_history_month (profit, roi).
  - historial_ventas_especificas: item_customer_behaivor_history para ese
    cliente y los ítems del array.
  - metricas_items_globales: item_behaivor_history_month para los ítems.
  - historial_ventas_previas_cliente: ventas anteriores de esos ítems a ese
    cliente (sale_vs_item + sale + purchase_vs_item).

  historial_financiero_cliente:
  - {
      "profit": 704.33,
      "roi": 24.05
  }
  historial_ventas_especificas
  historial_ventas_previas_cliente
  info_customer:
  - {
    "id": 276,
    "nombre": "BOLIVA EL MANA",
    "credito_disponible": 0,
    "credito_usado": 0,
    "deuda_total": 0
  }
  metricas_items_globales:
  - {
    "item_name": "ONIONS WHITE JUMBO",
    "item_id": 579,
    "profit": 108,
    "inversion": 180,
    "speed": 0,
    "friction": 2,
    "roi": 60,
    "perishable": 0,
    "last_update": "2024-08-31"
  }
  sale_actual:
    sale_actual.sale_items:
      - {
        "id_producto": "579",
        "cogs_row_amount": "0.00",
        "cost": "0.01",
        "price": "1.00",
        "qty": "",
        "returned_qty": "",
        "selling_type": "Pound",
        "total": ""
      }

================================================================================
suggestion / suggestionAll_query.php
================================================================================
Propósito
  Contexto amplio para sugerencias comerciales: compras (proveedor) y ventas
  (cliente), con inventario, métricas por ítem y movimientos recientes.

Salida
  Arreglo asociativo con meta + siete listas:

  - meta: descripción y límites por limites de GPT (150 ítems, 120 clientes, 120 pares cliente,
    120 ventas recientes, 120 proveedores, 120 pares proveedor, 120 compras
    recientes).

  Reutiliza / extiende patrones de saleAll:
  - items_inventory: como saleAll pero añade latest_behavior (último mes por
    ítem desde item_behaivor_history_month).
  - customers, item_customer_pairs, recent_sale_lines: igual filosofía que
    saleAll_query.php.

  Bloques adicionales para compras:
  - providers: proveedor con deuda (compras + gastos pendientes) y créditos
    disponibles / usados (providercredit).
  - item_provider_pairs: última fila por (item_id, provider_id) en
    item_provider_behaivor_history.
  - recent_purchase_lines: últimas líneas de compra con proveedor e ítem.

  customers:
  - {
    "customer_id": "106",
    "customer_name": " LOS POLINES  PRODUCE CORP",
    "customer_code": "C0106",
    "credit_limit": 0,
    "total_due_outstanding": 0
  }
  item_customer_pairs:
  - {
    "item_id": "352",
    "customer_id": "45",
    "customer_name": "NATIONAL FARM WHOLESALE FRUIT ",
    "item_name": "PLANTAIN GREEN",
    "profit": 75675,
    "roi": 22.15,
    "roi_star": 4,
    "profit_star": 5,
    "behavior_date": "2026-01-13"
  }
  item_provider_pairs:
  - {
    "item_id": "535",
    "provider_id": "400",
    "provider_name": "HARVEST WHOLESALE PRODUCE",
    "item_name": "KABOCHA",
    "profit": 58210.5,
    "roi": 15.28,
    "roi_star": 4,
    "profit_star": 5,
    "behavior_date": "2025-01-07"
  }
  items_inventory:
  - {
    "item_id": "352",
    "item_name": "PLANTAIN GREEN",
    "item_brand": "",
    "current_stock": 3794,
    "avg_unit_cost": 20.9768,
    "latest_selling_price": 22,
    "latest_behavior": {
      "profit": 14534.5,
      "inversion": 79998,
      "roi": 14.46,
      "speed": 17,
      "last_update": "2026-02-28"
    }
  }
  meta:
  meta.description: Datos para sugerir compras (proveedor) y ventas (cliente): inventario, métricas por ítem, historiales ítem–proveedor e ítem–cliente, y movimientos recientes.
  meta.limits: {
    "items_inventory": 150,
    "customers": 120,
    "item_customer_pairs": 120,
    "recent_sale_lines": 120,
    "providers": 120,
    "item_provider_pairs": 120,
    "recent_purchase_lines": 120
  }
  providers:
  - {
    "provider_id": "502",
    "provider_name": "1 yanks import export",
    "provider_code": "P00502",
    "total_due_outstanding": 0,
    "available_credit": 0,
    "used_credit": 0
  }
  recent_purchase_lines:
  - {
    "purchase_id": "2353",
    "purchase_code": "PU002353",
    "purchase_date": "2026-02-23",
    "provider_id": "6",
    "provider_name": "Walmart",
    "item_id": "538",
    "item_name": "LIME",
    "qty": 10,
    "unit_price": 2
  }
  recent_sale_lines:
  - {
  "sale_id": "10025",
  "sale_code": "INV010025",
  "sale_date": "2026-02-18",
  "customer_id": "44",
  "customer_name": "EL COMPADRE ",
  "item_id": "84",
  "item_name": "CILLANTRO MEX",
  "qty": 1,
  "price": 19
}