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 |
Consulta en lenguaje natural
Sección titulada «Consulta en lenguaje natural»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.
Registrar un movimiento con el asistente
Sección titulada «Registrar un movimiento con el asistente»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 vrespuesta 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 vCashboxMovement::createprocess 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.
Validaciones de confirmCashboxMovement
Sección titulada «Validaciones de confirmCashboxMovement»| 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.
Qué fija el movimiento
Sección titulada «Qué fija el movimiento»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.
Diferencias con el alta normal
Sección titulada «Diferencias con el alta normal»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 |
Chat con herramientas
Sección titulada «Chat con herramientas»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ó.
Exportación
Sección titulada «Exportación»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.
Hallazgos del código
Sección titulada «Hallazgos del código»AiExportController::downloadrespondeEl 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
viewAnyes 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.
