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.
data:backfill-missing-cost-center-movements
Sección titulada «data:backfill-missing-cost-center-movements»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.
Opciones
Sección titulada «Opciones»| 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. |
Qué considera faltante
Sección titulada «Qué considera faltante»Un CashboxMovement que cumple todo esto:
typeigual aegreso.cost_center_idno nulo.statusdistinto deanulado(y no eliminado, por el borrado lógico).- Sin ningún
CostCenterMovementcon el mismocost_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.
Qué escribe
Sección titulada «Qué escribe»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).
Riesgos y diferencias con el alta normal
Sección titulada «Riesgos y diferencias con el alta normal»| 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
amountpuede 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.
Cuándo usarlo
Sección titulada «Cuándo usarlo»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-movementsphp artisan data:backfill-missing-cost-center-movements --cost_center_id=12 --executedata:backfill-conciliation-fields
Sección titulada «data:backfill-conciliation-fields»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.
Opciones
Sección titulada «Opciones»| 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.
Riesgos
Sección titulada «Riesgos»- 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
sequencede 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 poneaccount_conciliation_iden nulo; este comando las omite. has_monthly_closequeda enfalsepara 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.
Cuándo usarlo
Sección titulada «Cuándo usarlo»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-fieldsphp artisan data:backfill-conciliation-fields --forceTareas programadas
Sección titulada «Tareas programadas»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.
Comandos relacionados con centros de costos
Sección titulada «Comandos relacionados con centros de costos»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.
