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.
Estados que intervienen
Sección titulada «Estados que intervienen»| 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.
Resumen del recorrido
Sección titulada «Resumen del recorrido»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)1. Crear
Sección titulada «1. Crear»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. |
Efectos al guardar
Sección titulada «Efectos al guardar»| 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.
2. Editar
Sección titulada «2. Editar»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.
3. Conciliar
Sección titulada «3. Conciliar»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::assertIsAnnullableimpide anularlo. AccountHelper::validateMovementrechaza 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 aconciliatedenfalse,conciated_atnulo y sin lote, y la cuenta vuelve a los valores del lote anterior.
4. Cerrar el mes
Sección titulada «4. Cerrar el mes»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.
5. Anular
Sección titulada «5. Anular»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.
Movimiento simple
Sección titulada «Movimiento simple»| 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. |
Transferencia o cambio de moneda
Sección titulada «Transferencia o cambio de moneda»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.
Hallazgos del código
Sección titulada «Hallazgos del código»- El método
CashboxMovementObserver::updatedes un bloque comentado: la reversión de saldo vive hoy enupdating. CashboxMovementPolicy::updateyupdateTransferrepiten la condiciónconciliateddos veces; no cambia el resultado.- La política
anulateno revisaconciliated; esa comprobación la hacenassertIsAnnullabley el observador.
