FINERACT-1153: Split oversized last reschedule installment

fineract-core/src/main/java/org/apache/fineract/infrastructure/configuration/api/GlobalConfigurationConstants.java

@@ -24,6 +24,7 @@ public final class GlobalConfigurationConstants {
     public static final String AMAZON_S3 = "amazon-s3";
     public static final String RESCHEDULE_FUTURE_REPAYMENTS = "reschedule-future-repayments";
     public static final String RESCHEDULE_REPAYMENTS_ON_HOLIDAYS = "reschedule-repayments-on-holidays";
+    public static final String SPLIT_LARGE_LAST_INSTALLMENT_ON_LOAN_RESCHEDULE = "split-large-last-installment-on-loan-reschedule";
     public static final String ALLOW_TRANSACTIONS_ON_HOLIDAY = "allow-transactions-on-holiday";
     public static final String ALLOW_TRANSACTIONS_ON_NON_WORKING_DAY = "allow-transactions-on-non-workingday";
     public static final String CONSTRAINT_APPROACH_FOR_DATATABLES = "constraint-approach-for-datatables";

fineract-core/src/main/java/org/apache/fineract/infrastructure/configuration/domain/ConfigurationDomainService.java

@@ -38,6 +38,8 @@ public interface ConfigurationDomainService {
 
     boolean isRescheduleRepaymentsOnHolidaysEnabled();
 
+    boolean isSplitLargeLastInstallmentOnLoanRescheduleEnabled();
+
     boolean allowTransactionsOnHolidayEnabled();
 
     boolean allowTransactionsOnNonWorkingDayEnabled();

fineract-provider/src/main/java/org/apache/fineract/infrastructure/configuration/api/GlobalConfigurationApiResource.java

@@ -60,6 +60,7 @@
         + "reschedule-future-repayments - defaults to false - if true reschedules repayemnts which falls on a non-working day to configured repayment rescheduling rule\n"
         + "allow-transactions-on-non-workingday - defaults to false - if true allows transactions on non-working days\n"
         + "reschedule-repayments-on-holidays - defaults to false - if true reschedules repayemnts which falls on a non-working day to defined reschedule date\n"
+        + "split-large-last-installment-on-loan-reschedule - defaults to false - if true adds extra repayment term(s) during loan reschedule to avoid an oversized final installment\n"
         + "allow-transactions-on-holiday - defaults to false - if true allows transactions on holidays\n"
         + "savings-interest-posting-current-period-end - Set it at the database level before any savings interest is posted. When set as false(default), interest will be posted on the first date of next period. If set as true, interest will be posted on last date of current period. There is no difference in the interest amount posted.\n"
         + "financial-year-beginning-month - Set it at the database level before any savings interest is posted. Allowed values 1 - 12 (January - December). Interest posting periods are evaluated based on this configuration.\n"

fineract-provider/src/main/java/org/apache/fineract/infrastructure/configuration/domain/ConfigurationDomainServiceJpa.java

@@ -104,6 +104,13 @@ public boolean isRescheduleRepaymentsOnHolidaysEnabled() {
         return property.isEnabled();
     }
 
+    @Override
+    public boolean isSplitLargeLastInstallmentOnLoanRescheduleEnabled() {
+        final GlobalConfigurationPropertyData property = getGlobalConfigurationPropertyData(
+                GlobalConfigurationConstants.SPLIT_LARGE_LAST_INSTALLMENT_ON_LOAN_RESCHEDULE);
+        return property.isEnabled();
+    }
+
     @Override
     public boolean allowTransactionsOnHolidayEnabled() {
         final GlobalConfigurationPropertyData property = getGlobalConfigurationPropertyData(

fineract-provider/src/main/java/org/apache/fineract/portfolio/loanaccount/rescheduleloan/service/LoanRescheduleRequestWritePlatformServiceImpl.java

@@ -20,6 +20,7 @@
 
 import java.math.BigDecimal;
 import java.math.MathContext;
+import java.math.RoundingMode;
 import java.time.LocalDate;
 import java.time.format.DateTimeFormatter;
 import java.util.ArrayList;
@@ -35,6 +36,7 @@
 import lombok.extern.slf4j.Slf4j;
 import org.apache.fineract.infrastructure.codes.domain.CodeValue;
 import org.apache.fineract.infrastructure.codes.domain.CodeValueRepositoryWrapper;
+import org.apache.fineract.infrastructure.configuration.domain.ConfigurationDomainService;
 import org.apache.fineract.infrastructure.core.api.JsonCommand;
 import org.apache.fineract.infrastructure.core.data.ApiParameterError;
 import org.apache.fineract.infrastructure.core.data.CommandProcessingResult;
@@ -47,6 +49,7 @@
 import org.apache.fineract.infrastructure.event.business.domain.loan.LoanRescheduledDueAdjustScheduleBusinessEvent;
 import org.apache.fineract.infrastructure.event.business.service.BusinessEventNotifierService;
 import org.apache.fineract.infrastructure.security.service.PlatformSecurityContext;
+import org.apache.fineract.organisation.monetary.domain.MonetaryCurrency;
 import org.apache.fineract.organisation.monetary.domain.MoneyHelper;
 import org.apache.fineract.portfolio.loanaccount.data.LoanTermVariationsData;
 import org.apache.fineract.portfolio.loanaccount.data.ScheduleGeneratorDTO;
@@ -98,8 +101,10 @@
 public class LoanRescheduleRequestWritePlatformServiceImpl implements LoanRescheduleRequestWritePlatformService {
 
     private static final DefaultScheduledDateGenerator DEFAULT_SCHEDULED_DATE_GENERATOR = new DefaultScheduledDateGenerator();
+    private static final int MAX_AUTO_SPLIT_ADDITIONAL_TERMS = 120;
 
     private final CodeValueRepositoryWrapper codeValueRepositoryWrapper;
+    private final ConfigurationDomainService configurationDomainService;
     private final PlatformSecurityContext platformSecurityContext;
     @Qualifier("loanRescheduleRequestDataValidator")
     private final LoanRescheduleRequestDataValidator loanRescheduleRequestDataValidator;
@@ -486,12 +491,6 @@ public CommandProcessingResult approve(JsonCommand jsonCommand) {
                     loanTermVariationsRepository.save(previousLoanTermVariations);
                 }
             }
-            BigDecimal annualNominalInterestRate = null;
-            List<LoanTermVariationsData> loanTermVariations = new ArrayList<>();
-            loanTermVariationsMapper.constructLoanTermVariations(scheduleGeneratorDTO.getFloatingRateDTO(), annualNominalInterestRate,
-                    loanTermVariations, loan);
-            loanApplicationTerms.getLoanTermVariations().setExceptionData(loanTermVariations);
-
             /*
              * for (LoanTermVariationsData loanTermVariation :
              * loanApplicationTerms.getLoanTermVariations().getDueDateVariation( )) { if
@@ -507,10 +506,28 @@ public CommandProcessingResult approve(JsonCommand jsonCommand) {
             final MathContext mathContext = MoneyHelper.getMathContext();
             final LoanRepaymentScheduleTransactionProcessor loanRepaymentScheduleTransactionProcessor = this.loanRepaymentScheduleTransactionProcessorFactory
                     .determineProcessor(loan.transactionProcessingStrategy());
-            final LoanScheduleGenerator loanScheduleGenerator = this.loanScheduleFactory.create(loanApplicationTerms.getLoanScheduleType(),
-                    loanApplicationTerms.getInterestMethod());
-            final LoanScheduleDTO loanScheduleDTO = loanScheduleGenerator.rescheduleNextInstallments(mathContext, loanApplicationTerms,
-                    loan, loanApplicationTerms.getHolidayDetailDTO(), loanRepaymentScheduleTransactionProcessor, rescheduleFromDate);
+            LoanScheduleDTO loanScheduleDTO = generateRescheduledLoanSchedule(scheduleGeneratorDTO, loan, rescheduleFromDate, mathContext,
+                    loanRepaymentScheduleTransactionProcessor);
+            if (configurationDomainService.isSplitLargeLastInstallmentOnLoanRescheduleEnabled()) {
+                int autoAddedTerms = 0;
+                while (isLastInstallmentAmountTooLarge(loanScheduleDTO, loan.getCurrency(), rescheduleFromDate)
+                        && autoAddedTerms < MAX_AUTO_SPLIT_ADDITIONAL_TERMS) {
+                    final LocalDate extendFromDate = getLastRescheduledInstallmentDueDate(loanScheduleDTO, rescheduleFromDate);
+                    if (extendFromDate == null) {
+                        log.warn("Unable to determine extension due date for loan reschedule request {}", loanRescheduleRequestId);
+                        break;
+                    }
+                    addAutoExtendRepaymentPeriodVariation(loanRescheduleRequest, loan, extendFromDate);
+                    autoAddedTerms++;
+                    hasInterestRateChange = true;
+                    loanScheduleDTO = generateRescheduledLoanSchedule(scheduleGeneratorDTO, loan, rescheduleFromDate, mathContext,
+                            loanRepaymentScheduleTransactionProcessor);
+                }
+                if (autoAddedTerms == MAX_AUTO_SPLIT_ADDITIONAL_TERMS) {
+                    log.warn("Reached auto-split safeguard limit ({}) for loan reschedule request {}", MAX_AUTO_SPLIT_ADDITIONAL_TERMS,
+                            loanRescheduleRequestId);
+                }
+            }
 
             // Either the installments got recalculated or the model
             if (loanScheduleDTO.getInstallments() != null) {
@@ -564,6 +581,84 @@ public CommandProcessingResult approve(JsonCommand jsonCommand) {
         }
     }
 
+    private LoanScheduleDTO generateRescheduledLoanSchedule(final ScheduleGeneratorDTO scheduleGeneratorDTO, final Loan loan,
+            final LocalDate rescheduleFromDate, final MathContext mathContext,
+            final LoanRepaymentScheduleTransactionProcessor loanRepaymentScheduleTransactionProcessor) {
+        final LoanApplicationTerms loanApplicationTerms = loanTermVariationsMapper.constructLoanApplicationTerms(scheduleGeneratorDTO,
+                loan);
+        final BigDecimal annualNominalInterestRate = null;
+        final List<LoanTermVariationsData> loanTermVariations = new ArrayList<>();
+        loanTermVariationsMapper.constructLoanTermVariations(scheduleGeneratorDTO.getFloatingRateDTO(), annualNominalInterestRate,
+                loanTermVariations, loan);
+        loanApplicationTerms.getLoanTermVariations().setExceptionData(loanTermVariations);
+
+        final LoanScheduleGenerator loanScheduleGenerator = this.loanScheduleFactory.create(loanApplicationTerms.getLoanScheduleType(),
+                loanApplicationTerms.getInterestMethod());
+        return loanScheduleGenerator.rescheduleNextInstallments(mathContext, loanApplicationTerms, loan,
+                loanApplicationTerms.getHolidayDetailDTO(), loanRepaymentScheduleTransactionProcessor, rescheduleFromDate);
+    }
+
+    private void addAutoExtendRepaymentPeriodVariation(final LoanRescheduleRequest loanRescheduleRequest, final Loan loan,
+            final LocalDate termApplicableFromDate) {
+        final LoanTermVariations loanTermVariation = new LoanTermVariations(LoanTermVariationType.EXTEND_REPAYMENT_PERIOD.getValue(),
+                termApplicableFromDate, BigDecimal.ONE, null, false, loan, loan.getStatus().getValue(), true, null);
+        loan.getLoanTermVariations().add(loanTermVariation);
+        loanRescheduleRequest.getLoanRescheduleRequestToTermVariationMappings()
+                .add(LoanRescheduleRequestToTermVariationMapping.createNew(loanRescheduleRequest, loanTermVariation));
+    }
+
+    private LocalDate getLastRescheduledInstallmentDueDate(final LoanScheduleDTO loanScheduleDTO, final LocalDate rescheduleFromDate) {
+        final List<LoanRepaymentScheduleInstallment> installments = loanScheduleDTO.getInstallments();
+        if (installments == null || installments.isEmpty()) {
+            return null;
+        }
+        LocalDate lastDueDate = null;
+        for (LoanRepaymentScheduleInstallment installment : installments) {
+            if (installment.isDownPayment() || DateUtils.isBefore(installment.getDueDate(), rescheduleFromDate)) {
+                continue;
+            }
+            lastDueDate = installment.getDueDate();
+        }
+        return lastDueDate;
+    }
+
+    private boolean isLastInstallmentAmountTooLarge(final LoanScheduleDTO loanScheduleDTO, final MonetaryCurrency currency,
+            final LocalDate rescheduleFromDate) {
+        final List<LoanRepaymentScheduleInstallment> installments = loanScheduleDTO.getInstallments();
+        if (installments == null || installments.size() < 2) {
+            return false;
+        }
+
+        final List<LoanRepaymentScheduleInstallment> rescheduledInstallments = new ArrayList<>();
+        for (LoanRepaymentScheduleInstallment installment : installments) {
+            if (installment.isDownPayment() || DateUtils.isBefore(installment.getDueDate(), rescheduleFromDate)) {
+                continue;
+            }
+            rescheduledInstallments.add(installment);
+        }
+
+        if (rescheduledInstallments.size() < 2) {
+            return false;
+        }
+
+        final LoanRepaymentScheduleInstallment lastInstallment = rescheduledInstallments.get(rescheduledInstallments.size() - 1);
+        BigDecimal maxPriorDueAmount = BigDecimal.ZERO;
+        for (int i = 0; i < rescheduledInstallments.size() - 1; i++) {
+            final BigDecimal dueAmount = rescheduledInstallments.get(i).getDue(currency).getAmount();
+            if (dueAmount.compareTo(maxPriorDueAmount) > 0) {
+                maxPriorDueAmount = dueAmount;
+            }
+        }
+
+        final BigDecimal lastInstallmentDueAmount = lastInstallment.getDue(currency).getAmount();
+        // Treat "too large" as a material increase, not rounding noise.
+        final BigDecimal minimumAbsoluteDifference = BigDecimal.ONE.setScale(currency.getDigitsAfterDecimal(), RoundingMode.UNNECESSARY);
+        final BigDecimal minimumRelativeDifference = maxPriorDueAmount.multiply(new BigDecimal("0.01"))
+                .setScale(currency.getDigitsAfterDecimal(), RoundingMode.HALF_UP);
+        final BigDecimal minimumMaterialDifference = minimumAbsoluteDifference.max(minimumRelativeDifference);
+        return lastInstallmentDueAmount.subtract(maxPriorDueAmount).compareTo(minimumMaterialDifference) > 0;
+    }
+
     private Loan saveAndFlushLoanWithDataIntegrityViolationChecks(final Loan loan) {
         try {
             List<LoanRepaymentScheduleInstallment> installments = loan.getRepaymentScheduleInstallments();

fineract-provider/src/main/resources/db/changelog/tenant/changelog-tenant.xml

@@ -246,4 +246,5 @@
     <include file="parts/0225_add_originator_external_ids_to_aggregation_summary.xml" relativeToChangelogFile="true" />
     <include file="parts/0226_trial_balance_summary_fix_originator_join_conditions.xml" relativeToChangelogFile="true" />
     <include file="parts/0227_postgresql_client_and_loan_trends_reports.xml" relativeToChangelogFile="true" />
+    <include file="parts/0228_add_reschedule_split_large_last_installment_config.xml" relativeToChangelogFile="true" />
 </databaseChangeLog>

fineract-provider/src/main/resources/db/changelog/tenant/parts/0228_add_reschedule_split_large_last_installment_config.xml

@@ -0,0 +1,35 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+
+    Licensed to the Apache Software Foundation (ASF) under one
+    or more contributor license agreements. See the NOTICE file
+    distributed with this work for additional information
+    regarding copyright ownership. The ASF licenses this file
+    to you under the Apache License, Version 2.0 (the
+    "License"); you may not use this file except in compliance
+    with the License. You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing,
+    software distributed under the License is distributed on an
+    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+    KIND, either express or implied. See the License for the
+    specific language governing permissions and limitations
+    under the License.
+
+-->
+<databaseChangeLog xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
+                   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+                   xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-4.3.xsd">
+    <changeSet author="fineract" id="1">
+        <insert tableName="c_configuration">
+            <column name="name" value="split-large-last-installment-on-loan-reschedule"/>
+            <column name="value" valueNumeric="0"/>
+            <column name="enabled" valueBoolean="false"/>
+            <column name="is_trap_door" valueBoolean="false"/>
+            <column name="description"
+                    value="If enabled, loan reschedule may add repayment term(s) to avoid an oversized last installment."/>
+        </insert>
+    </changeSet>
+</databaseChangeLog>