Inversiones y cuotas
Una inversión nace de un ingreso en Caja (el capital que entrega el inversionista) y se devuelve con egresos, uno por cuota o uno por varias cuotas. Dos controladores crean esos movimientos: InvestmentController y InvestmentWithdrawalController. La anulación vive en CashboxMovementAnnulService.
| Pieza | Clase | Rol |
|---|---|---|
| Alta de la inversión | InvestmentController::store |
Crea el ingreso, la inversión, su centro de costos y el cronograma de cuotas. |
| Pago de cuotas | InvestmentWithdrawalController::payInstallmentInvestment y payPendingInstallmentsInvestment |
Crean el egreso y marcan las cuotas como pagadas. |
| Liquidación y alta manual de un retiro | InvestmentWithdrawalController::liquidationInstallmentInvestment y store |
Crean el egreso por el camino heredado CashboxMovementCreateService::createFromLegacyPayload. |
| Anulación | CashboxMovementAnnulService::reverseInvestmentWithdrawalsForCashboxMovement |
Devuelve las cuotas a pendiente y recalcula la inversión. |
Rutas: POST /api/investment, POST /api/investment-withdrawal-pay, POST /api/investment-withdrawal-pay-pending, POST /api/investment/liquidation/{investmentId} y el recurso investment-withdrawal. El recurso investment y el de retiros tienen además listado y edición (index, show, update, destroy, restore).
Alta de una inversión
Sección titulada «Alta de una inversión»POST /api/investment | vInvestmentController::store (DB::beginTransaction ... commit o rollback) 1. ingreso en Caja --> CashboxMovementController::store --> CashboxMovementStoreService::store 2. Investment (cashbox_movement_id = el ingreso) 3. InvestmentProject (si se asignan proyectos) 4. CostCenter ("INVERSIÓN: nombre", techo = suma de cuotas) 5. InvestmentWithdrawal (una por cuota, estado pendiente)| Paso | Detalle |
|---|---|
| Datos del ingreso | cashbox_movement es obligatorio y debe ser un arreglo. Si falta subtotal_amount se calcula desde total_amount (restando la comisión si se incluye) y, si sigue vacío, toma el monto de la inversión. |
| Validación del monto | El subtotal del movimiento debe igualar el monto de la inversión con una diferencia máxima de 0.01. Si no, error sobre amount: El monto de la inversión debe coincidir con el subtotal del movimiento de caja. |
| Campos forzados | type igual a ingreso. concept por defecto: Inversión de, el inversionista y el nombre. third_party_type por defecto other. |
| Creación del ingreso | StoreCashboxMovementRequest::fromArray valida y CashboxMovementController::store ejecuta CashboxMovementStoreService::store. Los errores de validación se devuelven con el prefijo cashbox_movement.. Rige el permiso create de Caja. |
| Inversión | Guarda cashbox_movement_id, cuenta y moneda del movimiento, pending_amount y total_payable_amount igual a la suma de las cuotas, paid_amount en 0, next_number_installment igual a 1 y la próxima fecha. |
| Centro de costos | total_budget y available_amount iguales a la suma de las cuotas, is_budget_adjustable falso, allow_over_budget verdadero (una cuota con mora supera el techo y Caja no debe bloquear el pago), módulo asociado investment y investment_id de la inversión. Tipo de centro: el del proyecto del movimiento, si lo tiene; si no, uno activo de nivel 1 cuyo nombre contenga inversiones; si no, cualquier activo de nivel 1; si no, el primero. Sin ningún tipo: error No se encontró un tipo de centro de costo. Por favor, crea uno primero. |
| Cuotas | Una InvestmentWithdrawal por elemento de investment_withdrawals, con nombre RI N° más el número y el nombre de la inversión, estado StatusModelEnum::PENDIENTE y los importes del cronograma. |
Si cualquier paso falla, DB::rollBack deshace el ingreso, la inversión, el centro y las cuotas.
Editar una inversión solo cambia name y description (InvestmentController::update). Monto, condiciones, cuotas y movimiento quedan fijos.
Pagar una cuota
Sección titulada «Pagar una cuota»payInstallmentInvestment paga la siguiente cuota pendiente de la inversión.
| Validación | Error |
|---|---|
| La cuenta debe existir y estar en la moneda de la inversión. | No se puede efectuar el pago porque el tipo de moneda de la cuenta no coincide con la moneda de las cuotas de la inversión. |
| El centro de costos debe ser el de la inversión. Si la inversión no tiene centro (registros antiguos), se usa el del formulario. | El pago de la cuota se debe cargar al centro de costo de la inversión. |
| Debe quedar una cuota pendiente. | Esta inversión ya no tiene cuotas pendientes de pagar |
La cuota indicada debe ser la siguiente (nextPayInvestmentWithdrawal). |
Esta cuota no está disponible para procesar el pago |
El monto (total o subtotal) debe ser mayor a 0 y no menor a fee_amount. |
El monto a pagar no debe ser menor al de la cuota |
No puede haber una cuota anterior pendiente (comparación por number_installment, o por id si no hay número). |
No se puede pagar esta cuota porque existe una cuota anterior en estado pendiente. El pago de cuotas debe ser lineal. |
Luego, en una transacción:
- Crea el egreso:
typeegreso,conceptigual aPago de cuota N de la inversión nombre, y el resto del formulario. Pasa porCashboxMovementController::store, así que aplica todos los efectos de Ciclo de vida: saldo, centro de costos y reparto contable. Caja descuenta el monto completo del centro de la inversión. - Actualiza la cuota:
statuspagado,cashbox_movement_id,delay_interestigual al monto menosfee_amount(la mora),made_payment_dateigual a la fecha del movimiento. - Recalcula la inversión con
syncInvestmentAfterWithdrawalPayment:last_payment_date,next_number_installment,next_payment_date,payment_amount(cuota siguiente),paid_amountypending_amount(sumas defee_amount).
Si algo falla, DB::rollBack y se vuelve a lanzar el error.
Pagar todas las cuotas pendientes
Sección titulada «Pagar todas las cuotas pendientes»payPendingInstallmentsInvestment paga todas las pendientes con un solo egreso.
| Validación | Error |
|---|---|
Los ids enviados deben ser exactamente las cuotas pendientes (se bloquean con lockForUpdate). |
Las cuotas pendientes han cambiado. Actualice la información y vuelva a intentarlo. |
| Debe haber cuotas pendientes con total mayor a 0. | Esta inversión ya no tiene cuotas pendientes de pagar. |
El monto debe ser igual a la suma de fee_amount pendiente, con 0.01 de tolerancia. |
El monto del movimiento debe ser igual al total de cuotas pendientes |
| Misma moneda y mismo centro de costos que en el pago individual. | Los mismos mensajes |
El concepto es Pago total de cuotas pendientes (cuotas: 1,2,3) de la inversión nombre, recortado a 255 caracteres. Todas las cuotas reciben el mismo cashbox_movement_id, delay_interest en 0 y la misma fecha. Un movimiento puede entonces tener varias cuotas (InvestmentWithdrawal por cashbox_movement_id), y por eso la anulación trabaja por grupo.
Liquidación y alta manual de un retiro (camino heredado)
Sección titulada «Liquidación y alta manual de un retiro (camino heredado)»Estas dos rutas no usan CashboxMovementStoreService. Llaman a CashboxMovementCreateService::createFromLegacyPayload, que valida la caja, la apertura, la cuenta (por defecto la primera de la apertura), el método de pago y el saldo con AccountHelper::validateAvailabilityAndMovement, y crea el movimiento con CashboxMovement::create. El observador sí ajusta el saldo y escribe la bitácora, pero el movimiento no genera movimiento de centro de costos, ni reparto contable, ni código de 12 dígitos (usa uno de 6 dígitos con CashboxMovementCreateService::generateCode).
| Ruta | Qué hace |
|---|---|
POST /api/investment/liquidation/{investmentId} |
Elimina con borrado lógico las cuotas pendientes, crea un egreso con concepto Liquidación de la inversión nombre y una InvestmentWithdrawal pagada con ese movimiento y fee_amount igual al subtotal. |
POST /api/investment-withdrawal |
Crea un egreso con box_movement y un InvestmentWithdrawal con ese movimiento. Rechaza montos mayores al pendiente de la inversión. |
PUT /api/investment-withdrawal/{id} |
Actualiza el movimiento ligado con box_movement (update directo del modelo, sin pasar por las validaciones de edición de Caja) y la cuota. |
Anular un movimiento que pagó cuotas
Sección titulada «Anular un movimiento que pagó cuotas»CashboxMovementAnnulService::annul llama a reverseInvestmentWithdrawalsForCashboxMovement. El flujo completo de la anulación está en Ciclo de vida.
anular movimiento M | vcuotas con cashbox_movement_id = M (bloqueadas) |-- ninguna --> sigue la anulación normal | |-- por cada inversión afectada: | ¿hay cuotas pagadas fuera del grupo y posteriores a la mayor del grupo? | sí --> error: la anulación de cuotas debe ser lineal | vcada cuota del grupo --> pendiente, sin movimiento, sin fecha de pago, mora en 0 | vsyncInvestmentAfterWithdrawalReversal (recalcula la inversión)| Regla | Detalle |
|---|---|
| Orden lineal | “Posterior” se compara con number_installment si todas las cuotas del grupo lo tienen, y con id en caso contrario. Si existe una cuota pagada fuera del grupo y posterior, responde sobre investment_withdrawal_id: No se puede anular este movimiento porque existen cuotas posteriores en estado pagado (posteriores a N). La anulación de cuotas debe ser lineal. |
| Efecto en las cuotas | status pendiente, cashbox_movement_id nulo, made_payment_date nula, delay_interest 0 y update_user_id del usuario. |
| Efecto en la inversión | Se bloquea la inversión y se recalcula: last_payment_date (máxima fecha de pago de las cuotas pagadas), next_number_installment, next_payment_date y payment_amount (primera pendiente por number_installment), paid_amount y pending_amount. |
| Centro de costos | Antes de revertir las cuotas, la anulación revierte los CostCenterMovement del movimiento y sincroniza el centro de la inversión (paso 7 de la anulación). |
| Un movimiento con varias cuotas | Una anulación revierte todo el grupo que pagó ese movimiento. Para dejar pagadas solo algunas, no hay camino: se anula el movimiento completo. |
El código convive con dos enums de estado: las cuotas nuevas se crean con StatusModelEnum::PENDIENTE, se pagan con ModelStatusEnum::Pagado y la anulación las devuelve con ModelStatusEnum::Pendiente. Por eso las consultas comparan contra los valores de ambos enums (pendingStatusValues y paidStatusValues).
