Ir al contenido

Asistente de IA y Caja

Caja se conecta con la IA por tres caminos: la consulta en lenguaje natural (POST /api/ai/cashbox), el asistente que registra movimientos (POST /api/ai/assistant/process y confirm, y el agente de chat) y la exportación que prepara el agente. Todas las rutas están dentro del grupo ai con el límite de tasa throttle:ai: 15 solicitudes por minuto por usuario (RouteServiceProvider).

Camino Ruta Clase
Consulta POST /api/ai/cashbox AiApiController::getInformationCashbox
Interpretar un movimiento POST /api/ai/assistant/process con module igual a cashbox_movement AiAssistantController::process, processCashboxMovement
Confirmar un movimiento POST /api/ai/assistant/confirm AiAssistantController::confirm, confirmCashboxMovement
Chat con herramientas POST /api/ai/agent/chat y chat/stream ErpAssistant con sus herramientas
Descarga de exportaciones GET /api/ai/exports/{token} AiExportController::download

getInformationCashbox exige question y llama a Gate::authorize('viewAny', CashboxMovement::class). El endpoint se describe en Consulta con IA; aquí interesa qué datos salen hacia el modelo. El contexto (getCashboxContext) se arma con todas las filas de estas tablas, sin filtrar por la caja o los permisos del usuario:

Dato Campos Límite
Cajas id, name, status y su última apertura (id, date, status) Todas
Aperturas id, cashbox_id, user_id, date, status Todas
Usuarios id, name, status, incluidos los eliminados Todos
Movimientos recientes id, cajas, cuenta, método de pago, type, concept, montos, comisión, payment_date, is_transfer, transfer_cashbox_movement_id, conciliated, status, segment, created_at Los últimos 100 ingresos o egresos con status activo
Resumen Suma de total_amount de ingresos y de egresos activos Todos los movimientos activos, sin separar por moneda
Cuentas id, banco, moneda, name, cashbox_id, amount, type, status, datos de conciliación y su última conciliación Todas
Conciliaciones id, cuenta, apertura, caja, created_at, amount Las últimas 50
Catálogos Tipos de comisión, bancos, monedas y métodos de pago Todos

No se envían a la consulta el código de operación, la observación, los archivos ni los datos del tercero. Sí se envía el concept de los movimientos recientes.

process (módulo cashbox_movement)
|-- Gate::allows create CashboxMovement
|-- CashboxMovementExtractor interpreta el mensaje (agente de IA)
|-- resuelve caja, cuenta, método de pago, tercero y segmento de ingreso
v
respuesta con el payload y los campos a aclarar (no escribe en la base)
confirm (módulo cashbox_movement)
|-- Gate::allows create CashboxMovement (se vuelve a comprobar)
|-- confirmCashboxMovement, dentro de DB::transaction
v
CashboxMovement::create

process no guarda nada. Si la caja viene del contexto del chat (context.cashbox_id), se inyecta con confianza 1. confirm es lo único que escribe.

Validación Mensaje
type es ingreso o egreso. El tipo de movimiento no es válido. Debe ser ingreso o egreso.
Hay cuenta, método de pago y subtotal_amount de al menos 0.01. Mensajes por campo
En un ingreso, existe el segmento (CashboxIncomeSegment). El segmento del ingreso es requerido o no existe.
Hay caja en el payload. No se identificó la caja. Por favor abre el chat desde la vista de una caja.
La caja existe, no está anulada y tiene apertura abierta. CashboxHelper::validateOpening
La cuenta existe, pertenece a la caja y está activa. Mensajes por caso
El método de pago está habilitado para ese tipo y para el tipo de cuenta (payment_settings: ingreso o egreso, account.virtual o account.fisica). Mensajes por caso
Saldo suficiente en un egreso (salvo overdraft_enabled) y fecha no menor al último movimiento conciliado. AccountHelper::validateMovement

Los errores de validación y los inesperados se devuelven como success falso con un mensaje; el error inesperado se registra como ai_assistant.cashbox_movement_confirm_error.

type, account_id, cashbox_id, cashbox_opening_id, payment_method_id, subtotal_amount y total_amount iguales, concept (si falta, uno generado como Ingreso de N con la fecha), cashbox_income_segment_id, payment_date, tercero (third_party_type por defecto other, con provider_id o customer_id y responsible con su nombre), observation, opcode, invoice_number, code, user_id, status activo y create_user_id.

La fecha se resuelve igual que en el alta normal: si el día ya tiene movimientos, toma el último más un segundo; si no, usa la hora actual de Lima.

El asistente no pasa por CashboxMovementStoreService::store; usa CashboxMovement::create directamente. Por eso:

Efecto del alta normal En el asistente
Saldo de la cuenta y bitácora Sí, por CashboxMovementObserver::created
Movimiento de centro de costos No: el asistente no recibe cost_center_id. Un egreso queda sin centro.
Reparto contable No
Comisión No: no se registra ni se suma
Bloqueo de la cuenta antes de validar saldo Solo el que hace el observador al guardar; la validación previa no bloquea la fila
Código Se calcula en el controlador con CashboxMovement::max('code') (columna de texto) y 12 dígitos, no con el generador del servicio

ErpAssistant agrega herramientas según los permisos del usuario:

Herramienta Se ofrece si Qué hace
CreateCashboxMovement Gate::allows('create', CashboxMovement::class) Llama a processCashboxMovementForTool; el registro real sigue exigiendo confirm.
ExportCashboxMovementTool Gate::allows('viewAny', CashboxMovement::class) Prepara una exportación de movimientos.
ExportAccountBalanceTool Gate::allows('viewAny', Account::class) Prepara una exportación de saldos de cuentas.

La herramienta genérica QueryERP también existe en el agente. Qué tablas de Caja expone depende de la configuración de app/AI/Config; no se encontró una referencia explícita a los modelos de Caja en el código revisado y no se verificó.

Las herramientas de exportación no generan el archivo: crean un AiExportRequest y devuelven una vista previa.

Paso Detalle
Permiso BaseExportTool::handle comprueba viewAny sobre el modelo; si falla responde action igual a denied.
Solicitud Guarda user_id, module, los filtros, las columnas, el formato (xlsx por defecto, o pdf), un token UUID y expires_at a 10 minutos.
Filtros de movimientos date_from, date_to, cashbox_id (obligatorios en el esquema de la herramienta), account_id, type y columnas.
Vista previa Las primeras 5 filas, el total de filas y los totales por moneda y tipo.
Descarga GET /api/ai/exports/{token} (AiExportController::download) exige que el usuario sea quien creó la solicitud (si no, 403), que no haya expirado (si no, 410) y vuelve a comprobar viewAny. Cuenta las descargas (downloaded_count) y permite repetirlas mientras el enlace viva.

Columnas disponibles de movimientos: fecha de pago, concepto, tipo y monto total (básicas); método de pago, cuenta, código, proveedor o cliente y centro de costo (ampliadas); conciliado y fecha de conciliación.

La consulta (ExportCashboxMovementTool::buildQuery) solo toma ingresos y egresos. No excluye los movimientos anulados (los eliminados con borrado lógico sí quedan fuera) y ninguna columna disponible muestra el estado. Los totales de la vista previa suman todo lo que devuelve esa consulta.

  • AiExportController::download responde El link de descarga expiró. Pedí de nuevo la exportación al asistente.: el mensaje usa voseo y debería ser neutro.
  • El permiso de Caja no restringe ni la consulta ni la exportación, porque viewAny es siempre verdadero.
  • El asistente no admite centro de costos, comisión ni reparto contable: un egreso registrado con él no genera el movimiento de centro de costos que sí genera el alta manual.