Financing Module: French Amortization and Payment Plans

El módulo Financing es el motor de cálculo financiero de ArccNova v2. Su única responsabilidad es la matemática: cuánto paga el cliente por periodo, cuánto de cada pago va a interés y cuánto a capital, cuándo vence cada cuota según la modalidad pactada, y cómo se aplica un abono extra a capital. No registra cobros — esa tarea corresponde exclusivamente al módulo Collections. Sales consume Financing al dar de alta los planes de una venta; la calculadora manual y las cotizaciones lo usan para simular escenarios antes de firmar.

Financing solo calcula; Collections ejecuta el cobro. Los dos módulos son independientes. Cualquier cambio en la lógica de amortización debe reflejarse en ambos, pero el origen de la verdad matemática reside aquí.

Sistema francés

Cuota constante por periodo. El interés decrece y el capital aumenta en cada pago.

Hasta 4 planes por venta

Principal, Hitch (Enganche), Additional y ServicePlan, cada uno con su propia tabla.

Modalidades configurables

Frecuencias de pago (mensual, quincenal, etc.) definidas por tenant en el catálogo de modalidades.

Sin cuotas anticipadas

La cuota N nace al cobrarse; la tabla completa no se materializa hasta que el arquitecto lo decida.

Planes de financiamiento

Financing trabaja sobre los cuatro planes que Sales registra en la venta. Cada plan comparte los mismos atributos:

Atributo	Tipo	Descripción
`PaymentByPeriod`	`decimal`	Cuota constante calculada por el motor.
`PeriodInterest`	`decimal`	Tasa de interés por periodo (8 decimales).
`InterestRate`	`decimal`	Tasa anual. Default = TEA del proyecto.
`ModalityId`	`int`	Referencia al catálogo de modalidades del tenant.
`Installments`	`int`	Número total de cuotas del plan.
`PaymentFirstDate`	`DateOnly`	Fecha del primer pago.
`GracePeriod`	`int`	Días de gracia antes de generar mora.
`IsSettled`	`bool`	`true` cuando el saldo del plan llega a cero.
`ApplyInterest`	`bool`	Bandera: el plan cobra interés.
`ApplyLateFee`	`bool`	Bandera: el plan aplica mora por atraso.

Plan	Descripción
Principal	Financiamiento del `RemainingAmount` de la venta (precio − reserva − enganche − adicionales).
Hitch (Enganche)	El primer pago; puede fraccionarse en cuotas con su propia amortización.
Additional	Monto adicional que, al registrarse, se resta del saldo a financiar del Principal.
ServicePlan	Plan de servicio (ej. mantenimiento), independiente del financiamiento principal.

Motor de cálculo

Cuota por periodo — sistema francés (cuota constante)

i = InterestRate / Frecuencia_de_la_modalidad   ← tasa por periodo

PaymentByPeriod = Remanente × [ i(1+i)^n / ((1+i)^n − 1) ]

Si InterestRate = 0:
  PaymentByPeriod = Remanente / n      (sin interés; el total de interés es 0)

Remanente — Monto que el cliente financiará después de descontar enganche, reserva y adicionales.
Frecuencia — Periodos por año de la modalidad (FrecuencyYears del catálogo; mensual = 12).
n — Número total de cuotas del plan.

Ejemplo verificado (de la fuente): lote 80 000, tasa 0 %, 81 meses →

PaymentByPeriod = 80,000 / 81 = 987.65 / mes
Total de pagos  = 80,000.00
Total interés   = 0.00

Reparto de cada pago: interés y capital

En cada cuota i, sobre el saldo vivo:

InterestPayment  = round(Remanente × PeriodInterest, 2)
PrincipalPayment = round(PaymentByPeriod − InterestPayment, 2)
NewRemanente     = round(Remanente − PrincipalPayment, 2)

Este cálculo corresponde a Calculator.CalculateNewPaymentD del código v1. En el sistema francés puro, InterestPayment decrece y PrincipalPayment crece en cada periodo, manteniendo PaymentByPeriod constante.

Precisión y redondeo

Valor	Decimales
`PaymentByPeriod` y saldo del crédito	2
`PeriodInterest` (tasa por periodo)	8
Interés, capital y saldo de cada cuota	2

No existe una regla de “ajuste de centavos en la última cuota”. El diseño de cobranza por demanda hace que la última cuota reciba el saldo exacto restante con tope al PaymentByPeriod, absorbiendo naturalmente cualquier descuadre de centavos.Nota de implementación: el código v1 trunca PaymentByPeriod a 8 decimales mientras la respuesta devuelve 2 (inconsistencia registrada). La regla canónica para v2 — calcular con precisión decimal completa y cobrar redondeado a 2 — está pendiente de confirmación por el arquitecto.

Fechas de vencimiento por modalidad

Para la cuota n con fecha de primer pago F:

Modalidad	Fórmula
MENSUAL, BIMESTRAL, TRIMESTRAL, CUATRIMESTRAL, SEMESTRAL	`F.AddMonths((n−1) × Frequency)`
DIARIO, SEMANAL, QUINCENAL	`F.AddDays((n−1) × Frequency_en_días)`
ANUAL	`F.AddYears((n−1) × Frequency)`

Reglas especiales:

Si n ≤ 0 → sin fecha (null).
Si n = 1 → fecha del primer pago (F).

Capital y liquidación anticipada

Abono extra a capital
Liquidación anticipada

Un pago que supera la cuota del periodo puede aplicar el excedente como abono extra a capital. Efecto: reduce el número de cuotas (se eliminan cuotas del final del plan); el monto de la cuota periódica no cambia.

RN-C1: ExtraPrincipalPayment reduce Installments
       (no modifica PaymentByPeriod)

El asesor debe confirmar con el cliente antes de aplicar el excedente a capital. Si no hay confirmación, el excedente se registra como cambio (Change) y se descuenta del monto que va al financiamiento.Restricción: el abono extra está prohibido cuando el cobro cubre dos cuotas equivalentes al mismo tiempo (InstallmentEquivalent > 1). Si el extra supera el saldo restante, el sistema devuelve error.

No existe una función dedicada de “liquidación anticipada”. El flujo es:

El asesor calcula manualmente cuánto extra a capital se necesita para liquidar el saldo restante.
El sistema cobra el interés de la cuota en curso.
Los intereses no devengados del capital restante no se cobran — se condonan automáticamente.
No hay descuento adicional ni recálculo de la tabla de amortización.

RN-C2: Liquidación anticipada = abono extra a capital hasta saldo = 0
        Sin intereses futuros no devengados
        Sin función dedicada en la UI

Flujo HU-26: captura de planes de financiamiento en la venta

Datos del plan Principal

El asesor selecciona la modalidad, ingresa el número de cuotas, la fecha de inicio y la tasa de interés. Si el proyecto tiene una TEA configurada, se precarga como valor por defecto.

Cálculo automático de la cuota

En cuanto se completan los campos, el sistema llama al motor y muestra:

PaymentByPeriod (cuota constante)
Fecha del último pago (calculada con la fórmula de modalidad)
Total a pagar en capital e interés

Configurar planes opcionales

Si aplica, el asesor habilita y configura el plan Hitch, Additional y/o ServicePlan. Cada uno tiene su propio monto base y parámetros. Los montos de Hitch y Additional se restan del RemainingAmount antes de calcular el Principal.

Validación y grabado

El backend valida que las tasas no sean negativas y que las modalidades existan en el catálogo del tenant. Los planes aprobados se persisten junto con PaymentByPeriod y PeriodInterest precalculados.

Catálogo de modalidades

Las frecuencias de pago se definen por tenant en el catálogo Modalidades (C25). Cada entrada incluye:

Atributo	Ejemplo
Nombre	Mensual
`FrecuencyYears`	12 (periodos por año)
Tipo de cálculo de fecha	`AddMonths`
`Frequency` (días o meses)	1

Los valores predefinidos habituales son: Diario, Semanal, Quincenal, Mensual, Bimestral, Trimestral, Cuatrimestral, Semestral, Anual. El tenant puede agregar o desactivar modalidades sin afectar las ventas ya creadas.

Reglas de negocio

Clave	Regla
RN-01	Sistema francés puro (cuota constante). La mención de “interés simple” de versiones anteriores quedó descartada.
RN-02	Tasa 0 % = división simple del remanente entre el número de cuotas.
RN-03	Precisión: cuota/saldo a 2 decimales, tasa por periodo a 8 decimales.
RN-04	Fechas de vencimiento calculadas según la tabla de modalidad (AddMonths / AddDays / AddYears).
RN-05	Abono extra a capital reduce el número de cuotas, no el monto de la cuota periódica.
RN-06	Liquidación anticipada sin función dedicada; los intereses no devengados se condonan.
RN-07	El interés y la mora son banderas independientes por plan. Un plan puede tener una activa, ambas o ninguna.
RN-08	Cambio de fecha de pago: sin recálculo de intereses.

Puntos abiertos

Decisiones arquitectónicas pendientes

Tabla de amortización materializada vs. cuotas bajo demanda — El v1 genera las cuotas una a una conforme se cobran (las 81 cuotas de un plan no existen en base de datos hasta pagarse). El v2 puede conservar este diseño o materializar la tabla completa al crear el plan. Las reglas funcionales documentadas aquí son idénticas en ambos casos; la decisión afecta persistencia, estado de cuenta y proyecciones. Decide el arquitecto (Flag 2 del cierre).
Precisión de PaymentByPeriod — El código v1 trunca a 8 decimales; la respuesta al cliente muestra 2. Regla canónica para v2 pendiente de fijación (propuesta: calcular con precisión decimal completa, cobrar redondeado a 2 decimales).

Introducción

Fundamentos

Módulos del Sistema

Arquitectura y Decisiones

Referencia

Financing Module: French Amortization and Payment Plans

Sistema francés

Hasta 4 planes por venta

Modalidades configurables

Sin cuotas anticipadas

Planes de financiamiento

Motor de cálculo

Cuota por periodo — sistema francés (cuota constante)

Reparto de cada pago: interés y capital

Precisión y redondeo

Fechas de vencimiento por modalidad

Capital y liquidación anticipada

Flujo HU-26: captura de planes de financiamiento en la venta

Catálogo de modalidades

Reglas de negocio

Puntos abiertos

Build docs developers (and LLMs) love

Introducción

Fundamentos

Módulos del Sistema

Arquitectura y Decisiones

Referencia

Documentation Index

Sistema francés

Hasta 4 planes por venta

Modalidades configurables

Sin cuotas anticipadas

​Planes de financiamiento

​Motor de cálculo

​Cuota por periodo — sistema francés (cuota constante)

​Reparto de cada pago: interés y capital

​Precisión y redondeo

​Fechas de vencimiento por modalidad

​Capital y liquidación anticipada

​Flujo HU-26: captura de planes de financiamiento en la venta

​Catálogo de modalidades

​Reglas de negocio

​Puntos abiertos

Build docs developers (and LLMs) love

Planes de financiamiento

Motor de cálculo

Cuota por periodo — sistema francés (cuota constante)

Reparto de cada pago: interés y capital

Precisión y redondeo

Fechas de vencimiento por modalidad

Capital y liquidación anticipada

Flujo HU-26: captura de planes de financiamiento en la venta

Catálogo de modalidades

Reglas de negocio

Puntos abiertos