FINERACT-2354: First step - basic implementation of re-aging for Interest bearing loans - Default Behavior, interestRecalculation = true, without dueDate change (without edge cases) #5053

ruzeynalov · 2025-09-24T11:57:03Z

Description

Describe the changes made and why they were made.

Ignore if these details are present on the associated Apache Fineract JIRA ticket.

Checklist

Please make sure these boxes are checked before submitting your pull request - thanks!

Write the commit message as per https://github.com/apache/fineract/#pull-requests
Acknowledge that we will not review PRs that are not passing the build ("green") - it is your responsibility to get a proposed PR to pass the build, not primarily the project's maintainers.
[] Create/update unit or integration tests for verifying the changes made.
Follow coding conventions at https://cwiki.apache.org/confluence/display/FINERACT/Coding+Conventions.
[] Add required Swagger annotation and update API documentation at fineract-provider/src/main/resources/static/legacy-docs/apiLive.htm with details of any API changes
Submission is not a "code dump". (Large changes can be made "in repository" via a branch. Ask on the developer mailing list for guidance, if required.)

FYI our guidelines for code reviews are at https://cwiki.apache.org/confluence/display/FINERACT/Code+Review+Guide.

adamsaghy · 2025-10-15T09:48:44Z

...java/org/apache/fineract/portfolio/loanaccount/service/reaging/LoanReAgingValidatorTest.java

                .isEqualTo("validation.msg.loan.reAge.numberOfInstallments.not.greater.than.zero");
    }

+    @Disabled


If this test is not valid anymore, remove it.

adamsaghy · 2025-10-15T09:48:49Z

...java/org/apache/fineract/portfolio/loanaccount/service/reaging/LoanReAgingValidatorTest.java

                .isEqualTo("error.msg.loan.reage.supported.only.for.progressive.loan.schedule.type");
    }

+    @Disabled


If this test is not valid anymore, remove it.

...oanaccount/domain/transactionprocessor/impl/AdvancedPaymentScheduleTransactionProcessor.java

adamsaghy · 2025-10-15T09:57:46Z

...oanaccount/domain/transactionprocessor/impl/AdvancedPaymentScheduleTransactionProcessor.java

+        final LoanApplicationTerms loanApplicationTerms = new LoanApplicationTerms.Builder().submittedOnDate(expectedDisbursementDate)
+                .currency(currency.getCurrencyData()).repaymentsStartingFromDate(reAgingStartDate)
+                .expectedDisbursementDate(expectedDisbursementDate).principal(outstandingPrincipalBalance.get())
+                .loanTermFrequency(loanTransaction.getLoanReAgeParameter().getNumberOfInstallments())
+                .loanTermPeriodFrequencyType(loanTransaction.getLoanReAgeParameter().getFrequencyType())
+                .numberOfRepayments(loanTransaction.getLoanReAgeParameter().getNumberOfInstallments())
+                .repaymentEvery(loanTransaction.getLoanReAgeParameter().getFrequencyNumber())
+                .repaymentPeriodFrequencyType(loanTransaction.getLoanReAgeParameter().getFrequencyType())
+                .interestRatePerPeriod(interestRate)
+                .interestRatePeriodFrequencyType(loan.getLoanRepaymentScheduleDetail().getRepaymentPeriodFrequencyType())
+                .annualNominalInterestRate(interestRate).daysInMonthType(loan.getLoanProduct().fetchDaysInMonthType())
+                .daysInYearType(loan.getLoanProduct().fetchDaysInYearType()).inArrearsTolerance(Money.zero(currency, mc))
+                .disbursementDatas(disbursementData).isDownPaymentEnabled(false).downPaymentPercentage(ZERO).seedDate(reAgingStartDate)
+                .interestRecognitionOnDisbursementDate(
+                        loan.getLoanProduct().getLoanProductRelatedDetail().isInterestRecognitionOnDisbursementDate())
+                .daysInYearCustomStrategy(loan.getLoanProduct().getLoanProductRelatedDetail().getDaysInYearCustomStrategy())
+                .interestMethod(loan.getLoanProductRelatedDetail().getInterestMethod()).allowPartialPeriodInterestCalculation(
+                        loan.getLoanProduct().getLoanProductRelatedDetail().isAllowPartialPeriodInterestCalculation())
+                .mc(mc).build();
+        final LoanScheduleModel loanScheduleModelForReAging = scheduleGenerator.generate(mc, loanApplicationTerms, null, null);
+
+        // Now merge the temporary schedule with existing installments
+        mergeTemporaryScheduleWithExistingInstallments(loanScheduleModelForReAging, installments, repaymentPeriods, currency,
+                transactionDate, ctx, loan);


@mariiaKraievska Do we need this? I mean ProgressiveEMICalculator and existing ProgressiveLoanInterestScheduleModel + reage parameters would be enough to generate and update the existing ProgressiveLoanInterestScheduleModel and once its done, just update the LoanRepaymentScheduleInstallment based on the model. what do you think?

Done, please check

what changed here?

adamsaghy · 2025-10-15T10:01:24Z

...oanaccount/domain/transactionprocessor/impl/AdvancedPaymentScheduleTransactionProcessor.java

+        if (chargeOffTransaction.isPresent()) {
+            repaymentPeriods.stream().filter(rp -> !rp.getDueDate().isBefore(reAgingStartDate) && !rp.isFullyPaid())
+                    .forEach(repaymentPeriod -> {
+                        repaymentPeriod.getInterestPeriods().forEach(interestPeriod -> {


why to set 0 rate factor and mark them as paused?

You're right, it's enough to pause them.

why to pause them? :D

mariiaKraievska · 2025-10-15T12:05:17Z

PTAL

adamsaghy · 2025-10-15T12:24:39Z

...oanaccount/domain/transactionprocessor/impl/AdvancedPaymentScheduleTransactionProcessor.java

+        final Optional<LoanTransaction> chargeOffTransaction = ctx.getAlreadyProcessedTransactions().stream()
+                .filter(t -> ((t.isChargeOff() && (loan.hasAccelerateChargeOffStrategy() || loan.hasZeroInterestChargeOffStrategy()))
+                        || t.isContractTermination()) && !t.isReversed() && t.getTransactionDate().isBefore(reAgingStartDate))
+                .findFirst();


Its 2 types of transactions: chargeoff and contract termination

adamsaghy · 2025-10-15T12:24:54Z

...oanaccount/domain/transactionprocessor/impl/AdvancedPaymentScheduleTransactionProcessor.java

+        final Optional<LoanTransaction> chargeOffTransaction = ctx.getAlreadyProcessedTransactions().stream()
+                .filter(t -> ((t.isChargeOff() && (loan.hasAccelerateChargeOffStrategy() || loan.hasZeroInterestChargeOffStrategy()))
+                        || t.isContractTermination()) && !t.isReversed() && t.getTransactionDate().isBefore(reAgingStartDate))
+                .findFirst();


what if txn date and reage start date are matching?

adamsaghy · 2025-10-15T12:37:46Z

...oanaccount/domain/transactionprocessor/impl/AdvancedPaymentScheduleTransactionProcessor.java

+                        loan.getLoanProduct().getLoanProductRelatedDetail().isAllowPartialPeriodInterestCalculation())
+                .mc(mc).build();
+        final LoanScheduleModel loanScheduleModelForReAging = scheduleGenerator.generate(mc, loanApplicationTerms, null, null);


I dont think we need this. scheduleGenerator we should use the existing model + the EmiCalculator and introduce a new action: "reage" and provide its parameters. THe EmiCalculator can calculate interim models and update existing one based on that. After the model is updated we can use to update the existing repayment installments based on the model alone.

adamsaghy · 2025-10-17T10:01:39Z

...oanaccount/domain/transactionprocessor/impl/AdvancedPaymentScheduleTransactionProcessor.java

-        LoanRepaymentScheduleInstallment reAgedInstallment = LoanRepaymentScheduleInstallment.newReAgedInstallment(loan,
-                reAgedInstallmentNumber, fromDate, loanTransaction.getLoanReAgeParameter().getStartDate(), calculatedPrincipal.getAmount());
-        insertOrReplaceRelatedInstallment(installments, reAgedInstallment, currency, loanTransaction.getTransactionDate());
+    private void removeOutstandingAmountsFromInstallment(final LoanRepaymentScheduleInstallment existingInstallment,


Would it be better to use updateInstallmentsByModelForReAging and set principal and interest from the model directly?

adamsaghy · 2025-10-27T08:54:06Z

...n/src/main/java/org/apache/fineract/portfolio/loanproduct/calc/ProgressiveEMICalculator.java

+        LocalDate disbursementDate = transactionDate;
+        if (!reAgingStartDate.isAfter(transactionDate)) {
+            disbursementDate = periodStartDate;
+        }


This might not needed anymore. I believe we always need to go with transaction date.

adamsaghy · 2025-10-27T08:56:52Z

...n/src/main/java/org/apache/fineract/portfolio/loanproduct/calc/ProgressiveEMICalculator.java

+        final List<RepaymentPeriod> periodsBeforeReAging = existingRepaymentPeriods.stream()
+                .filter(rp -> rp.getFromDate().isBefore(reAgingStartDate) && !rp.isFullyPaid()).toList();
+
+        periodsBeforeReAging.forEach(rp -> {
+            final InterestPeriod lastInterestPeriod = rp.getInterestPeriods().getLast();
+            lastInterestPeriod.addBalanceCorrectionAmount(rp.getOutstandingPrincipal().negated());
+            rp.setEmi(rp.getTotalPaidAmount());
+        });


Please extract into a method and leave a short description what it does, like why we are negating the balance correction, etc.

adamsaghy · 2025-10-27T08:57:56Z

...n/src/main/java/org/apache/fineract/portfolio/loanproduct/calc/ProgressiveEMICalculator.java

+        final LocalDate periodStartDate = switch (loanReAgeParameter.getFrequencyType()) {
+            case DAYS -> reAgingStartDate.minusDays(loanReAgeParameter.getFrequencyNumber());
+            case WEEKS -> reAgingStartDate.minusWeeks(loanReAgeParameter.getFrequencyNumber());
+            case MONTHS -> reAgingStartDate.minusMonths(loanReAgeParameter.getFrequencyNumber());
+            case YEARS -> reAgingStartDate.minusYears(loanReAgeParameter.getFrequencyNumber());
+            case WHOLE_TERM -> throw new IllegalStateException("Unexpected RecalculationFrequencyType: WHOLE_TERM");
+            case INVALID -> throw new IllegalStateException("Unexpected RecalculationFrequencyType: INVALID");
+        };
+
+        LocalDate disbursementDate = transactionDate;
+        if (!reAgingStartDate.isAfter(transactionDate)) {
+            disbursementDate = periodStartDate;
+        }


Lets extract into a method and leave a short description what it does, like: calculating the reage start date which is used to calculate the due date, etc.

adamsaghy · 2025-10-27T08:59:28Z

...n/src/main/java/org/apache/fineract/portfolio/loanproduct/calc/ProgressiveEMICalculator.java

+        final List<LoanScheduleModelRepaymentPeriod> expectedRepaymentPeriods = scheduledDateGenerator.generateRepaymentPeriods(mc,
+                periodStartDate, loanApplicationTerms, null);
+        final ProgressiveLoanInterestScheduleModel temporaryReAgedScheduleModel = generatePeriodInterestScheduleModel(
+                expectedRepaymentPeriods, loanApplicationTerms.toLoanProductRelatedDetailMinimumData(), null,
+                loanApplicationTerms.getInstallmentAmountInMultiplesOf(), mc);
+
+        addDisbursement(temporaryReAgedScheduleModel, EmiChangeOperation.disburse(disbursementDate, loanApplicationTerms.getPrincipal()));
+
+        final List<RepaymentPeriod> newPeriods = temporaryReAgedScheduleModel.repaymentPeriods();


Extract into a method (generate reage submodel, or something like that) and leave a short description. Return the new model.

adamsaghy · 2025-10-27T09:00:42Z

...n/src/main/java/org/apache/fineract/portfolio/loanproduct/calc/ProgressiveEMICalculator.java

+        final Optional<RepaymentPeriod> firstExistingRepaymentPeriodOpt = existingRepaymentPeriods.stream()
+                .filter(period -> period.getDueDate().equals(reAgeDate)).findFirst();
+
+        for (final RepaymentPeriod newPeriod : newPeriods) {
+            final Optional<RepaymentPeriod> existingRepaymentPeriodOpt = existingRepaymentPeriods.stream().filter(
+                    period -> period.getFromDate().equals(newPeriod.getFromDate()) && period.getDueDate().equals(newPeriod.getDueDate()))
+                    .findFirst();
+            Optional<RepaymentPeriod> previousExistingRepaymentPeriodOpt = Optional.empty();
+            if (existingRepaymentPeriodOpt.isPresent() && firstExistingRepaymentPeriodOpt.isPresent()
+                    && existingRepaymentPeriodOpt.get().equals(firstExistingRepaymentPeriodOpt.get())) {
+                previousExistingRepaymentPeriodOpt = existingRepaymentPeriodOpt.get().getPrevious();
+            }
+
+            final Money newPrincipal = newPeriod.getDuePrincipal();
+            final Money newInterest = newPeriod.getDueInterest();
+
+            final RepaymentPeriod rp = RepaymentPeriod.create(
+                    previousExistingRepaymentPeriodOpt.orElseGet(existingRepaymentPeriods::getLast), newPeriod.getFromDate(),
+                    newPeriod.getDueDate(), newPrincipal.add(newInterest), MoneyHelper.getMathContext(),
+                    loanTransaction.getLoan().getLoanProductRelatedDetail());
+            rp.setTotalDisbursedAmount(scheduleModel.repaymentPeriods().getFirst().getTotalDisbursedAmount());
+
+            existingRepaymentPeriodOpt.ifPresent(existingRepaymentPeriods::remove);
+            existingRepaymentPeriods.add(rp);
+            calculateRateFactorForRepaymentPeriod(rp, scheduleModel);
+        }
+
+        final RepaymentPeriod lastReAgedInstallment = newPeriods.getLast();
+        final List<RepaymentPeriod> reAgedRepaymentPeriods = existingRepaymentPeriods.stream()
+                .filter(repaymentPeriod -> (!repaymentPeriod.getFromDate().isBefore(reAgingStartDate)
+                        || repaymentPeriod.getDueDate().isEqual(reAgingStartDate))
+                        && !repaymentPeriod.getDueDate().isAfter(lastReAgedInstallment.getDueDate()))
+                .toList();
+
+        calculateOutstandingBalance(scheduleModel);
+        calculateLastUnpaidRepaymentPeriodEMI(scheduleModel, transactionDate);
+        checkAndAdjustEmiIfNeededOnRelatedRepaymentPeriods(scheduleModel, reAgedRepaymentPeriods);


Extract into a method and leave a short description what it does (like merging the newmodel and existing one together and after recalculate the balances).

adamsaghy · 2025-10-27T09:04:27Z

...apache/fineract/portfolio/loanaccount/service/LoanWritePlatformServiceJpaRepositoryImpl.java

+        if (loan.isInterestBearing() && loan.isInterestRecalculationEnabled()) {
+            if (loan.isProgressiveSchedule() && ((loan.hasChargeOffTransaction() && loan.hasAccelerateChargeOffStrategy())
+                    || loan.hasContractTerminationTransaction()
+                    || (loan.isInterestRecalculationEnabled() && loan.hasReAgingTransaction()))) {
+                final ScheduleGeneratorDTO scheduleGeneratorDTO = loanUtilService.buildScheduleGeneratorDTO(loan, null);
+                loanScheduleService.regenerateRepaymentSchedule(loan, scheduleGeneratorDTO);
+            }
+        }


I think this should be moved into the org.apache.fineract.portfolio.loanaccount.service.LoanWritePlatformServiceJpaRepositoryImpl#handleChargebackTransaction method.

I tried to make this changes, but now I get this error "During synchronization a new object was found through a relationship that was not marked cascade PERSIST: org.apache.fineract.portfolio.loanaccount.domain.LoanTransaction"

adamsaghy · 2025-10-27T09:10:45Z

...n/java/org/apache/fineract/portfolio/loanaccount/service/reaging/LoanReAgingServiceImpl.java

+        loan.addLoanTransaction(reAgeTransaction);
+        final LoanRepaymentScheduleTransactionProcessor loanRepaymentScheduleTransactionProcessor = loanRepaymentScheduleTransactionProcessorFactory
+                .determineProcessor(loan.transactionProcessingStrategy());
+        if (reAgeTransaction.getTransactionDate().isBefore(reAgeTransaction.getSubmittedOnDate())
+                && !loan.isInterestBearingAndInterestRecalculationEnabled()) {
            reprocessLoanTransactionsService.reprocessTransactionsWithPostTransactionChecks(loan, reAgeTransaction.getTransactionDate());
+        } else if (loan.isInterestBearingAndInterestRecalculationEnabled()) {
+            if (loan.isProgressiveSchedule() && ((loan.hasChargeOffTransaction() && loan.hasAccelerateChargeOffStrategy())
+                    || loan.hasContractTerminationTransaction()
+                    || (loan.isInterestRecalculationEnabled() && loan.hasReAgingTransaction()))) {
+                final ScheduleGeneratorDTO scheduleGeneratorDTO = loanUtilService.buildScheduleGeneratorDTO(loan, null);
+                loanScheduleService.regenerateRepaymentSchedule(loan, scheduleGeneratorDTO);
+            }
+            reprocessLoanTransactionsService.reprocessTransactions(loan);


I dont think we should add reage txn to the loan before the reprocessing, hence it might be flushed during the loanUtilService.buildScheduleGeneratorDTO or loanScheduleService.regenerateRepaymentSchedule and in that case, it will be immediately reverse-replayed.

I would rather provide transaction list to the reprocessLoanTransactionsService.reprocessTransactions and only after it was reprocessed to be added to the loan (if needed)

adamsaghy · 2025-10-27T11:43:25Z

@mariiaKraievska Please rebase.

…t bearing products with interest calculation: default behavior

…rest bearing loans - Default Behavior, interestRecalculation = true, without dueDate change

mariiaKraievska · 2025-10-27T12:29:53Z

PTAL

adamsaghy

LGTM

ruzeynalov marked this pull request as draft September 24, 2025 11:58

ruzeynalov force-pushed the FINERACT-2354/reaging-for-interest-bearing-products-interest-calculation-default-behaviour branch 4 times, most recently from 2ca485f to f9b159c Compare October 2, 2025 11:22

ruzeynalov force-pushed the FINERACT-2354/reaging-for-interest-bearing-products-interest-calculation-default-behaviour branch from f9b159c to 966268f Compare October 7, 2025 12:51

mariiaKraievska force-pushed the FINERACT-2354/reaging-for-interest-bearing-products-interest-calculation-default-behaviour branch 2 times, most recently from 913e0a7 to a68ea39 Compare October 13, 2025 08:23

galovics approved these changes Oct 13, 2025

View reviewed changes

ruzeynalov force-pushed the FINERACT-2354/reaging-for-interest-bearing-products-interest-calculation-default-behaviour branch from e6d847a to 391fbda Compare October 15, 2025 08:00

ruzeynalov marked this pull request as ready for review October 15, 2025 08:01

mariiaKraievska force-pushed the FINERACT-2354/reaging-for-interest-bearing-products-interest-calculation-default-behaviour branch from 391fbda to c70e3c5 Compare October 15, 2025 08:07

adamsaghy force-pushed the FINERACT-2354/reaging-for-interest-bearing-products-interest-calculation-default-behaviour branch from c70e3c5 to c354140 Compare October 15, 2025 09:45

adamsaghy reviewed Oct 15, 2025

View reviewed changes

...oanaccount/domain/transactionprocessor/impl/AdvancedPaymentScheduleTransactionProcessor.java Outdated Show resolved Hide resolved

adamsaghy reviewed Oct 15, 2025

View reviewed changes

mariiaKraievska force-pushed the FINERACT-2354/reaging-for-interest-bearing-products-interest-calculation-default-behaviour branch from c354140 to 3329a93 Compare October 15, 2025 12:00

adamsaghy reviewed Oct 15, 2025

View reviewed changes

mariiaKraievska force-pushed the FINERACT-2354/reaging-for-interest-bearing-products-interest-calculation-default-behaviour branch 5 times, most recently from 688c242 to ae93391 Compare October 17, 2025 09:05

adamsaghy reviewed Oct 17, 2025

View reviewed changes

mariiaKraievska force-pushed the FINERACT-2354/reaging-for-interest-bearing-products-interest-calculation-default-behaviour branch from ae93391 to e8aea1d Compare October 17, 2025 10:26

mariiaKraievska force-pushed the FINERACT-2354/reaging-for-interest-bearing-products-interest-calculation-default-behaviour branch 5 times, most recently from 2a5c344 to 88cb761 Compare October 20, 2025 14:40

mariiaKraievska force-pushed the FINERACT-2354/reaging-for-interest-bearing-products-interest-calculation-default-behaviour branch 2 times, most recently from 4296417 to 23ec571 Compare October 22, 2025 10:18

adamsaghy reviewed Oct 27, 2025

View reviewed changes

mariiaKraievska force-pushed the FINERACT-2354/reaging-for-interest-bearing-products-interest-calculation-default-behaviour branch from 23ec571 to abb13c1 Compare October 27, 2025 12:17

ruzeynalov and others added 2 commits October 27, 2025 14:22

FINERACT-2354: added e2e tests for validation of re-aging for interes…

3812502

…t bearing products with interest calculation: default behavior

FINERACT-2354: First step - basic implementation of re-aging for Inte…

04e51f8

…rest bearing loans - Default Behavior, interestRecalculation = true, without dueDate change

mariiaKraievska force-pushed the FINERACT-2354/reaging-for-interest-bearing-products-interest-calculation-default-behaviour branch from abb13c1 to 04e51f8 Compare October 27, 2025 12:28

adamsaghy approved these changes Oct 27, 2025

View reviewed changes

adamsaghy merged commit d21a1a9 into apache:develop Oct 27, 2025
33 checks passed

adamsaghy deleted the FINERACT-2354/reaging-for-interest-bearing-products-interest-calculation-default-behaviour branch October 27, 2025 13:22

FINERACT-2354: First step - basic implementation of re-aging for Interest bearing loans - Default Behavior, interestRecalculation = true, without dueDate change (without edge cases) #5053

FINERACT-2354: First step - basic implementation of re-aging for Interest bearing loans - Default Behavior, interestRecalculation = true, without dueDate change (without edge cases) #5053

Uh oh!

Conversation

ruzeynalov commented Sep 24, 2025

Description

Checklist

Uh oh!

adamsaghy Oct 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adamsaghy Oct 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mariiaKraievska commented Oct 15, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adamsaghy Oct 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adamsaghy commented Oct 27, 2025

Uh oh!

mariiaKraievska commented Oct 27, 2025

Uh oh!

adamsaghy left a comment

adamsaghy Oct 15, 2025 •

edited

Loading

adamsaghy Oct 15, 2025 •

edited

Loading

adamsaghy Oct 27, 2025 •

edited

Loading