Ir al contenido

Ciclo de vida de un movimiento

Esta página sigue a un movimiento de ingreso o egreso desde que se crea hasta que se anula. Los campos del modelo están en Modelos de Caja y en el resumen de CashboxMovement.

Campo Valores Quién lo cambia
status activo al crear. anulado al anular. eliminado al eliminar (borrado lógico). BaseControllerHelper::store, CashboxMovementAnnulService::annul, BaseControllerHelper::destroy
conciliated false al crear. true al conciliar. AccountConciliationService (marca y desmarca el lote)
conciated_at Fecha de conciliación. Nulo mientras no se concilia. El nombre lleva el error de ortografía en la columna. AccountConciliationService
account_conciliation_id Lote que concilió el movimiento. AccountConciliationService
status_update_comment, status_update_date Motivo y fecha de la anulación. CashboxMovementAnnulService::annul

El tipo conciliación no es un movimiento de dinero: es el corte que se inserta al conciliar. El observador no mueve el saldo para ese tipo.

crear ---> efectos ---> editar (limitado) ---> conciliar ---> cerrar mes
| |
| +--> revertir el lote (LIFO)
|
+--> anular (solo si no está conciliado ni anulado)
+--> eliminar (borrado lógico, no revierte nada)

Ruta: POST /api/cashbox-movement, que ejecuta CashboxMovementStoreService::store dentro de DB::transaction. El mismo servicio lo usan las órdenes de pago y las inversiones (ver resumen de flujos).

Paso Qué hace Validación o error
1 StoreCashboxMovementRequest limpia campos fantasma: en un ingreso anula cost_center_id, y conserva solo los ids del tipo de tercero elegido. Reglas del formulario y del método de pago (payment_settings).
2 Redondea subtotal_amount y commission_amount a 2 decimales (NumberUtils::roundDecimal).
3 BaseControllerHelper::store exige el permiso create de la política, fija status en activo y llena el modelo. CashboxMovementPolicy::create (permiso MovementCreate).
4 Si el tercero es cliente o proveedor, copia su nombre en responsible.
5 Si es un egreso con centro de costos: el centro debe estar activo o abierto, no estar bloqueado (ensureCostCenterIsNotLocked) y, si el movimiento trae proyecto, coincidir con el del centro. Errores sobre cost_center_id.
6 Calcula total_amount como subtotal más comisión.
7 Bloquea la fila de la cuenta con lockForUpdate.
8 Ajusta payment_date con paymentDateInDay: conserva el día y pone la hora del último movimiento del día más un segundo, o la hora actual de Lima si el día no tiene movimientos.
9 AccountHelper::validateAvailabilityAndMovement: la cuenta debe estar activa, pertenecer a una caja y la caja debe tener la apertura abierta. En un egreso, el saldo debe alcanzar salvo que la cuenta tenga overdraft_enabled. La fecha no puede ser menor a la del último movimiento conciliado de la cuenta. Errores sobre account_id, amount y payment_date.
10 Fija cashbox_id, cashbox_opening_id (última apertura), user_id y el código correlativo de 12 dígitos.
11 Guarda el movimiento y fija create_user_id.
Efecto Quién lo ejecuta Detalle
Saldo de la cuenta CashboxMovementObserver::created Para ingreso o egreso, bloquea la cuenta, suma o resta total_amount y pone conciliated de la cuenta en false.
Bitácora de Caja CashboxMovementObserver::created Crea un registro de tipo movimiento con el texto del movimiento. Ver bitácora.
Movimiento de centro de costos CashboxMovementStoreService::createDirectCostCenterMovement Solo egresos con centro. Convierte el total a la moneda del centro con ExchangeRateService::valueForCoin, bloquea el centro y rechaza el gasto si supera el disponible y allow_over_budget es falso. Crea el CostCenterMovement activo y luego CostCenterBudgetSummaryService::sync. Ver centro de costos.
Reparto contable CashboxMovementStoreService::createAccountingAccountMovements Solo si se envía accounting_account_movements. Los porcentajes deben sumar 100 y los montos deben igualar total_amount. Crea un AccountingAccountMovement por línea.

Si cualquier paso lanza un error de validación, la transacción se revierte completa, incluido el ajuste del saldo.

Ruta: PUT /api/cashbox-movement/{id} (CashboxMovementController::update), dentro de una transacción.

Regla Origen
Permiso de edición. CashboxMovementPolicy::update (MovementEdit)
Solo edita quien creó el movimiento (create_user_id). CashboxMovementPolicy::update
No se edita si está anulado o conciliado. CashboxMovementPolicy::update
No se edita una transferencia por esta ruta. CashboxMovementPolicy::update
No se edita si está vinculado a una orden de pago (pago o devolución). PaymentCashboxMovementService::assertIsNotLinkedToPayment
La caja debe tener la apertura abierta. CashboxHelper::validateOpening
El monto no se edita. Si se envía subtotal_amount, commission_amount o total_amount distinto al guardado, responde error; si es igual, se ignora. CashboxMovementController::update
La nueva fecha no puede ser menor a la del último movimiento conciliado de la cuenta. CashboxMovementController::update
En un egreso sin centro se puede asignar uno. En uno con centro se puede cambiar, pero no quitar. Cambiar el centro de un egreso que paga cuotas de una inversión no se permite. CashboxMovementController::update, releaseCostCenterForChange
El centro nuevo debe pertenecer al mismo proyecto y no estar bloqueado. El anterior debe seguir abierto. CashboxMovementController::update
El reparto contable se reconstruye solo si se envía. CashboxMovementController::update

La edición usa updateQuietly: no dispara el observador, así que no toca el saldo de la cuenta. Registra el cambio en la bitácora con CashboxLogFacade::cashboxMovementChange. Al cambiar el centro, anula el CostCenterMovement anterior (con el comentario del cambio), crea el nuevo y sincroniza el resumen presupuestal de ambos centros.

Las transferencias y los cambios de moneda se editan por PUT /api/cashbox-movement/{id}/transfer/update (updateCashboxMovementTransfer), que solo cambia opcode, observation y payment_date en las dos patas. Cada pata debe estar sin anular, sin conciliar y con su caja abierta.

AccountConciliationService agrupa los movimientos de una cuenta en un lote. Al cerrar el lote:

Efecto Detalle
Marca los movimientos del lote conciliated en true, conciated_at con la fecha actual y account_conciliation_id con el lote.
Actualiza la cuenta last_conciliation_id, conciliated_movement_last_date, conciliated y conciliated_at.
Bitácora CashboxLogFacade::conciliationCreated.

Las reglas del lote están en Reglas de conciliación y los endpoints en Conciliación de cuentas.

Un movimiento conciliado queda protegido:

  • La política impide editarlo y CashboxMovementAnnulService::assertIsAnnullable impide anularlo.
  • AccountHelper::validateMovement rechaza crear un movimiento con fecha menor a la del último conciliado.
  • Si el lote se revierte (solo el más reciente, AccountConciliationService), los movimientos vuelven a conciliated en false, conciated_at nulo y sin lote, y la cuenta vuelve a los valores del lote anterior.

El cierre mensual (AccountClosureMonthly) se crea en la misma transacción que el lote que cierra el mes (hasMonthlyClose). Ver Cierre mensual.

El cierre no cambia campos de los movimientos. Su efecto sobre ellos es indirecto: los movimientos del mes quedan conciliados por el lote, y mientras el cierre exista no se crean conciliaciones nuevas en ese mes (regla R12). Al revertir el lote que cerró el mes, el cierre se elimina con borrado lógico.

Rutas: PUT /api/cashbox-movement/{id}/anulate para un movimiento simple, y PUT /api/cashbox-movement/anulate/{id} para transferencias y cambios de moneda. El detalle de la ruta está en Anular movimiento.

Paso Qué hace Validación o error
1 Pide status_update_comment. Obligatorio.
2 Si el movimiento es el pago de una orden de pago, delega en AnnulPaymentUseCase. Ver Órdenes de pago.
3 Si es la devolución de un pago, rechaza. assertIsNotPaymentRefund.
4 Comprueba que no esté anulado ni conciliado. CashboxMovementAnnulService::assertIsAnnullable.
5 Verifica la política: permiso MovementAnulate y estado distinto de anulado. CashboxMovementPolicy::anulate.
6 CashboxHelper::validateOpening: la caja debe tener la apertura abierta. Error sobre account_id.
7 Si tiene movimientos de centro de costos: el centro debe estar activo o abierto; anula cada CostCenterMovement y sincroniza el resumen del centro. Un movimiento con detalle de centro pero sin centro asociado no se anula hasta corregir la data.
8 Si paga cuotas de una inversión, las devuelve a pendiente respetando el orden lineal. Ver Inversiones y cuotas.
9 Actualiza status a anulado, status_update_comment, status_update_date y update_user_id.
10 CashboxMovementObserver::updating revierte el saldo (resta un ingreso, suma un egreso) con la cuenta bloqueada y escribe la bitácora. Antes comprueba otra vez conciated_at; si tiene valor, rechaza. Mensaje: el movimiento está conciliado y no puede ser anulado.

CashboxMovementController::anulateMovement exige que el movimiento sea una transferencia (is_transfer), encuentra la otra pata, verifica el permiso sobre la pata de salida y valida cada pata: no anulada, no conciliada y caja abierta. Luego anula ambas patas con update, por lo que el observador revierte el saldo de las dos cuentas. El motivo es opcional: si falta, se guarda Movimiento anulado. No revierte centro de costos, porque las patas no lo usan.

  • El método CashboxMovementObserver::updated es un bloque comentado: la reversión de saldo vive hoy en updating.
  • CashboxMovementPolicy::update y updateTransfer repiten la condición conciliated dos veces; no cambia el resultado.
  • La política anulate no revisa conciliated; esa comprobación la hacen assertIsAnnullable y el observador.