Ir al contenido

Comandos de mantenimiento de Caja

Dos comandos de app/Console/Commands escriben datos de Caja de forma masiva. Ambos son de reparación o migración de datos: no son parte del uso diario. Conviene tener una copia de respaldo antes de ejecutarlos con escritura.

Comando Clase Qué repara Escribe por defecto
data:backfill-missing-cost-center-movements BackfillMissingCostCenterMovements Egresos con centro de costos que no tienen su CostCenterMovement No: muestra una vista previa
data:backfill-conciliation-fields BackfillConciliationAndClosureFields Campos nuevos de conciliaciones y cierres mensuales Sí

Ambos usan ConfirmableTrait: en el entorno de producción piden confirmación antes de escribir, salvo que se pase --force. Fuera de producción no preguntan.

Detecta egresos de Caja que deberían tener movimiento de centro de costos y no lo tienen, y los crea. El origen típico es un egreso creado por un camino que no pasa por CashboxMovementStoreService::store (ver Resumen de flujos) o datos anteriores a esa regla.

Opción Valor por defecto Efecto
--execute Sin activar Sin esta opción solo cuenta y muestra una vista previa. Con ella escribe.
--cost_center_id= Sin filtro Limita la búsqueda de faltantes a un centro de costos.
--chunk= 500 Tamaño de lote al ejecutar.
--limit= 200 Cantidad de ids que lista la vista previa.
--force Sin activar Omite la confirmación en producción.

Un CashboxMovement que cumple todo esto:

  • type igual a egreso.
  • cost_center_id no nulo.
  • status distinto de anulado (y no eliminado, por el borrado lógico).
  • Sin ningún CostCenterMovement con el mismo cost_center_id (whereDoesntHave('costCenterMovements', ...)). La condición mira cualquier movimiento de centro de costos, aunque esté anulado, por lo que un egreso cuyo movimiento de centro fue anulado no se vuelve a crear.

Por cada faltante crea un CostCenterMovement con:

Campo Valor
cost_center_id, cashbox_movement_id Los del egreso
movement_date payment_date del egreso
concept concept del egreso
cashbox_movement_coin_id Moneda de la cuenta
cost_center_coin_value, cashbox_movement_coin_value value actual de la moneda del centro y de la cuenta
total_amount_cashbox_movement total_amount del egreso
amount Total convertido a la moneda del centro: monto por (valor de la moneda de la cuenta entre valor de la moneda del centro), redondeado a 2 decimales
available_amount 0
status activo
create_user_id, update_user_id create_user_id del egreso, o su user_id, o el usuario autenticado (en la consola suele no haber)

Se omite (skipped) el egreso sin cuenta, sin centro o sin moneda, o con un valor de moneda menor o igual a 0. Al terminar imprime created, skipped y converted (los que cambiaron de moneda).

Punto Alta normal (createDirectCostCenterMovement) Comando
Tipo de cambio ExchangeRateService::valueForCoin con la fecha del movimiento Coin.value vigente al ejecutar el comando
Disponible Calcula available_amount con el centro bloqueado Lo deja en 0
Validaciones del centro Estado activo o abierto, no bloqueado, sin sobregiro Ninguna
Transacción La del controlador Ninguna: si falla a mitad, queda lo creado hasta ese punto
Resumen del centro CostCenterBudgetSummaryService::sync del centro syncMany de todos los centros, aunque se haya usado --cost_center_id

Puntos a tener en cuenta:

  • Es idempotente: una segunda ejecución solo procesa lo que aún falte.
  • Un egreso en una moneda distinta a la del centro recibe el valor actual de las monedas, no el de la fecha del gasto, y por eso su amount puede diferir de lo que habría guardado el alta normal.
  • La resincronización final recorre todos los centros de costos en lotes, lo que puede tardar en una base grande.
  • El comando calcula una lista de centros tocados (touchedCostCenterIds) que no usa.
  • La resincronización corre solo cuando hubo faltantes y se ejecutó con --execute.

Cuando el reporte de un centro de costos no refleja un egreso que sí está en Caja con ese centro. Primero ejecútalo sin --execute y compara la cantidad de faltantes con lo esperado.

php artisan data:backfill-missing-cost-center-movements
php artisan data:backfill-missing-cost-center-movements --cost_center_id=12 --execute

Rellena los campos que se agregaron a account_conciliations y account_closure_monthlies con las migraciones de abril de 2026 (2026_04_25_100000 y 2026_04_25_100001), calculándolos desde los datos existentes. Se pensó para ejecutarse una vez tras esas migraciones.

Opción Efecto
--force Omite la confirmación en producción. No existe modo de vista previa ni --execute: el comando siempre escribe.

Paso 1: conciliaciones (account_conciliations)

Sección titulada «Paso 1: conciliaciones (account_conciliations)»

Toma las conciliaciones con period_year nulo, incluidas las eliminadas, agrupadas por cuenta y en orden de id. Para cada una:

Campo Cálculo
period_year, period_month, period_label De la fecha de pago más antigua de sus movimientos
sequence Contador por cuenta y período
from_date, to_date, movements_count Mínimo y máximo de fecha de pago y cantidad de movimientos
opening_balance amount menos amount_in más amount_out
closing_balance amount
conciliation_status revertida si está eliminada, cerrada si no
conciliated_at, conciliated_by_user_id created_at y create_user_id de la conciliación
has_monthly_close Siempre false

Los movimientos considerados son los ingresos y egresos vinculados por account_conciliation_id, no anulados y no eliminados. Una conciliación sin movimientos vinculados se omite con una advertencia (omitida) y conserva period_year nulo.

Paso 2: cierres mensuales (account_closure_monthlies)

Sección titulada «Paso 2: cierres mensuales (account_closure_monthlies)»

Toma los cierres no eliminados con period_label nulo y calcula net_amount (ingresos menos egresos), movements_count, period_label, conciliations_count, first_conciliation_id y last_conciliation_id (conciliaciones de la cuenta en ese año y mes, ya completadas en el paso 1 y no eliminadas), close_status en cerrado, closed_at igual a created_at y closed_by_user_id igual a create_user_id.

  • Usa DB::table, así que no dispara observadores ni eventos de modelo, y no hay una transacción envolvente: un fallo a medias deja el paso 1 o parte del paso 2 aplicado.
  • Es idempotente solo por los filtros de campos nulos. Si se ejecuta cuando ya existen conciliaciones del flujo nuevo en la misma cuenta y mes, el contador sequence de las conciliaciones antiguas empieza de 1 y puede repetir números ya usados.
  • Las conciliaciones revertidas con el flujo nuevo (AccountConciliationService) quedan sin movimientos vinculados, porque la reversión pone account_conciliation_id en nulo; este comando las omite.
  • has_monthly_close queda en false para todas las conciliaciones, aunque exista un cierre mensual del mismo mes. Revisa ese dato si algún reporte depende de él.
  • Los totales del cierre se calculan con los campos del cierre ya guardados; no recalculan los movimientos.

Solo si hay conciliaciones o cierres con period_label o period_year nulos tras migrar datos antiguos. En una base ya al día no hace nada: imprime 0 conciliaciones y 0 cierres pendientes.

php artisan data:backfill-conciliation-fields
php artisan data:backfill-conciliation-fields --force

App\Console\Kernel::schedule (registrado en bootstrap/app.php) define estas tareas, en horario de Lima:

Hora Tarea Relación con Caja
3:00 backup:run, solo si backup.backup.enabled es verdadero Respalda la base, incluida Caja
3:30 backup:clean, con la misma condición Limpia respaldos antiguos
6:00 y 12:30 UpdateDolarPrice Actualiza el tipo de cambio; lo usa ExchangeRateService::valueForCoin al convertir egresos a la moneda del centro de costos
0:30 purchasing:expire-budget-reservations Compras; no toca Caja
1:00 purchasing:notify-upcoming-installments Compras; no toca Caja
Cada hora ExpireStockReservationsJob y RecalculateInventoryAlertsJob Inventario; no tocan Caja

No hay ninguna tarea programada que cree, cambie o concilie movimientos de Caja. routes/console.php solo define el comando inspire. El job CostCenterTracingJob aparece comentado en el programador y no corre.

Los comandos data:backfill-* solo corren si alguien los ejecuta a mano.

Existen cost-center:merge, cost-center:merge-revert, cost-center:recalculate-parents y cost-center:consolidate-set-point. Operan sobre centros de costos y su presupuesto. No hacen referencia a CashboxMovement en el código, y no se revisó a fondo si cambian CostCenterMovement.