Ir al contenido

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).

POST /api/investment
|
v
InvestmentController::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.

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:

  1. Crea el egreso: type egreso, concept igual a Pago de cuota N de la inversión nombre, y el resto del formulario. Pasa por CashboxMovementController::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.
  2. Actualiza la cuota: status pagado, cashbox_movement_id, delay_interest igual al monto menos fee_amount (la mora), made_payment_date igual a la fecha del movimiento.
  3. Recalcula la inversión con syncInvestmentAfterWithdrawalPayment: last_payment_date, next_number_installment, next_payment_date, payment_amount (cuota siguiente), paid_amount y pending_amount (sumas de fee_amount).

Si algo falla, DB::rollBack y se vuelve a lanzar el error.

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.

CashboxMovementAnnulService::annul llama a reverseInvestmentWithdrawalsForCashboxMovement. El flujo completo de la anulación está en Ciclo de vida.

anular movimiento M
|
v
cuotas 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
|
v
cada cuota del grupo --> pendiente, sin movimiento, sin fecha de pago, mora en 0
|
v
syncInvestmentAfterWithdrawalReversal (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).