FINERACT-2455: WorkingCapital - % repayment modification options in the middle of the loan life cycle

Author: budaidev

fineract-core/src/main/java/org/apache/fineract/commands/service/CommandWrapperBuilder.java

@@ -913,6 +913,14 @@ public CommandWrapperBuilder creditBalanceRefundWorkingCapitalLoanTransaction(fi
         return this;
     }
 
+    public CommandWrapperBuilder updateRateWorkingCapitalLoanApplication(final Long loanId) {
+        this.actionName = "UPDATERATE";
+        this.entityName = "WORKINGCAPITALLOAN";
+        this.entityId = loanId;
+        this.href = "/workingcapitalloans/" + loanId;
+        return this;
+    }
+
     public CommandWrapperBuilder createClientIdentifier(final Long clientId) {
         this.actionName = ACTION_CREATE;
         this.entityName = ENTITY_CLIENTIDENTIFIER;

fineract-working-capital-loan/src/main/java/org/apache/fineract/portfolio/workingcapitalloan/WorkingCapitalLoanConstants.java

@@ -74,4 +74,7 @@ private WorkingCapitalLoanConstants() {
     public static final String receiptNumberParamName = "receiptNumber";
     public static final String bankNumberParamName = "bankNumber";
     public static final String transactionDateParamName = "transactionDate";
+
+    // Period payment rate change parameters
+    public static final String periodPaymentRateParamName = "periodPaymentRate";
 }

fineract-working-capital-loan/src/main/java/org/apache/fineract/portfolio/workingcapitalloan/api/WorkingCapitalLoanApiResource.java

@@ -54,10 +54,12 @@
 import org.apache.fineract.portfolio.workingcapitalloan.WorkingCapitalLoanConstants;
 import org.apache.fineract.portfolio.workingcapitalloan.data.WorkingCapitalLoanData;
 import org.apache.fineract.portfolio.workingcapitalloan.data.WorkingCapitalLoanDelinquencyTagHistoryData;
+import org.apache.fineract.portfolio.workingcapitalloan.data.WorkingCapitalLoanPeriodPaymentRateChangeData;
 import org.apache.fineract.portfolio.workingcapitalloan.data.WorkingCapitalLoanTemplateData;
 import org.apache.fineract.portfolio.workingcapitalloan.exception.WorkingCapitalLoanNotFoundException;
 import org.apache.fineract.portfolio.workingcapitalloan.service.WorkingCapitalLoanApplicationReadPlatformService;
 import org.apache.fineract.portfolio.workingcapitalloan.service.WorkingCapitalLoanDelinquencyReadPlatformService;
+import org.apache.fineract.portfolio.workingcapitalloan.service.WorkingCapitalLoanPeriodPaymentRateChangeReadService;
 import org.springframework.data.domain.Page;
 import org.springframework.data.domain.Pageable;
 import org.springframework.stereotype.Component;
@@ -74,6 +76,7 @@ public class WorkingCapitalLoanApiResource {
     private final WorkingCapitalLoanApplicationReadPlatformService readPlatformService;
     private final PortfolioCommandSourceWritePlatformService commandsSourceWritePlatformService;
     private final WorkingCapitalLoanDelinquencyReadPlatformService workingCapitalLoanDelinquencyReadPlatformService;
+    private final WorkingCapitalLoanPeriodPaymentRateChangeReadService rateChangeReadService;
 
     @GET
     @Path("template")
@@ -346,4 +349,71 @@ private CommandProcessingResult updateDiscount(final Long loanId, final String l
                 .updateDiscountWorkingCapitalLoanApplication(resolvedLoanId).build();
         return this.commandsSourceWritePlatformService.logCommandSource(commandRequest);
     }
+
+    @PUT
+    @Path("{loanId}/rate")
+    @Consumes({ MediaType.APPLICATION_JSON })
+    @Produces({ MediaType.APPLICATION_JSON })
+    @Operation(operationId = "updateWorkingCapitalLoanRateById", summary = "Update period payment rate for an active Working Capital Loan", description = "Modifies the period payment rate and triggers schedule recalculation for the remaining term.")
+    @RequestBody(required = true, content = @Content(schema = @Schema(implementation = WorkingCapitalLoanApiResourceSwagger.PutWorkingCapitalLoansLoanIdRateRequest.class)))
+    @ApiResponses({
+            @ApiResponse(responseCode = "200", description = "OK", content = @Content(schema = @Schema(implementation = CommandProcessingResult.class))) })
+    public CommandProcessingResult updateRateById(
+            @PathParam("loanId") @Parameter(description = "loanId", required = true) final Long loanId,
+            @Parameter(hidden = true) final String apiRequestBodyAsJson) {
+        return updateRate(loanId, null, apiRequestBodyAsJson);
+    }
+
+    @PUT
+    @Path("external-id/{loanExternalId}/rate")
+    @Consumes({ MediaType.APPLICATION_JSON })
+    @Produces({ MediaType.APPLICATION_JSON })
+    @Operation(operationId = "updateWorkingCapitalLoanRateByExternalId", summary = "Update period payment rate for an active Working Capital Loan by external id", description = "Modifies the period payment rate and triggers schedule recalculation for the remaining term.")
+    @RequestBody(required = true, content = @Content(schema = @Schema(implementation = WorkingCapitalLoanApiResourceSwagger.PutWorkingCapitalLoansLoanIdRateRequest.class)))
+    @ApiResponses({
+            @ApiResponse(responseCode = "200", description = "OK", content = @Content(schema = @Schema(implementation = CommandProcessingResult.class))) })
+    public CommandProcessingResult updateRateByExternalId(
+            @PathParam("loanExternalId") @Parameter(description = "loanExternalId", required = true) final String loanExternalId,
+            @Parameter(hidden = true) final String apiRequestBodyAsJson) {
+        return updateRate(null, loanExternalId, apiRequestBodyAsJson);
+    }
+
+    private CommandProcessingResult updateRate(final Long loanId, final String loanExternalIdStr, final String apiRequestBodyAsJson) {
+        final Long resolvedLoanId = loanId != null ? loanId
+                : readPlatformService.getResolvedLoanId(ExternalIdFactory.produce(loanExternalIdStr));
+        if (resolvedLoanId == null) {
+            throw new WorkingCapitalLoanNotFoundException(ExternalIdFactory.produce(loanExternalIdStr));
+        }
+        final CommandWrapper commandRequest = new CommandWrapperBuilder().withJson(apiRequestBodyAsJson)
+                .updateRateWorkingCapitalLoanApplication(resolvedLoanId).build();
+        return this.commandsSourceWritePlatformService.logCommandSource(commandRequest);
+    }
+
+    @GET
+    @Path("{loanId}/rate-changes")
+    @Produces({ MediaType.APPLICATION_JSON })
+    @Operation(operationId = "getWorkingCapitalLoanRateChangeHistoryById", summary = "Retrieve rate change history for a Working Capital Loan", description = "Returns all rate change records for the loan, ordered by most recent first.")
+    @ApiResponses({
+            @ApiResponse(responseCode = "200", description = "OK", content = @Content(array = @ArraySchema(schema = @Schema(implementation = WorkingCapitalLoanPeriodPaymentRateChangeData.class)))) })
+    public List<WorkingCapitalLoanPeriodPaymentRateChangeData> getRateChangeHistoryById(
+            @PathParam("loanId") @Parameter(description = "loanId", required = true) final Long loanId) {
+        this.context.authenticatedUser().validateHasReadPermission(RESOURCE_NAME_FOR_PERMISSIONS);
+        return this.rateChangeReadService.retrieveRateChangeHistory(loanId);
+    }
+
+    @GET
+    @Path("external-id/{loanExternalId}/rate-changes")
+    @Produces({ MediaType.APPLICATION_JSON })
+    @Operation(operationId = "getWorkingCapitalLoanRateChangeHistoryByExternalId", summary = "Retrieve rate change history for a Working Capital Loan by external id", description = "Returns all rate change records for the loan, ordered by most recent first.")
+    @ApiResponses({
+            @ApiResponse(responseCode = "200", description = "OK", content = @Content(array = @ArraySchema(schema = @Schema(implementation = WorkingCapitalLoanPeriodPaymentRateChangeData.class)))) })
+    public List<WorkingCapitalLoanPeriodPaymentRateChangeData> getRateChangeHistoryByExternalId(
+            @PathParam("loanExternalId") @Parameter(description = "loanExternalId", required = true) final String loanExternalId) {
+        this.context.authenticatedUser().validateHasReadPermission(RESOURCE_NAME_FOR_PERMISSIONS);
+        final Long resolvedLoanId = readPlatformService.getResolvedLoanId(ExternalIdFactory.produce(loanExternalId));
+        if (resolvedLoanId == null) {
+            throw new WorkingCapitalLoanNotFoundException(ExternalIdFactory.produce(loanExternalId));
+        }
+        return this.rateChangeReadService.retrieveRateChangeHistory(resolvedLoanId);
+    }
 }

fineract-working-capital-loan/src/main/java/org/apache/fineract/portfolio/workingcapitalloan/api/WorkingCapitalLoanApiResourceSwagger.java

@@ -609,4 +609,22 @@ private GetWorkingCapitalLoanDelinquencyRangeScheduleTagHistoryResponse() {}
         public BigDecimal delinquentAmount;
     }
 
+    @Schema(description = "Request for updating period payment rate on an active Working Capital Loan")
+    public static final class PutWorkingCapitalLoansLoanIdRateRequest {
+
+        private PutWorkingCapitalLoansLoanIdRateRequest() {}
+
+        @Schema(example = "0.17", description = "New period payment rate")
+        public BigDecimal periodPaymentRate;
+
+        @Schema(example = "Rate change note")
+        public String note;
+
+        @Schema(example = "en_GB")
+        public String locale;
+
+        @Schema(example = "dd MMMM yyyy")
+        public String dateFormat;
+    }
+
 }

fineract-working-capital-loan/src/main/java/org/apache/fineract/portfolio/workingcapitalloan/calc/DefaultProjectedAmortizationScheduleCalculator.java

@@ -54,4 +54,11 @@ public void applyPayment(@NonNull final ProjectedAmortizationScheduleModel model
             @NonNull final BigDecimal paymentAmount) {
         model.applyPayment(paymentDate, paymentAmount);
     }
+
+    @Override
+    @NonNull
+    public ProjectedAmortizationScheduleModel applyRateChange(@NonNull final ProjectedAmortizationScheduleModel model,
+            @NonNull final BigDecimal newPeriodPaymentRate, @NonNull final LocalDate rateChangeDate) {
+        return model.regenerateWithNewRate(newPeriodPaymentRate, rateChangeDate);
+    }
 }

fineract-working-capital-loan/src/main/java/org/apache/fineract/portfolio/workingcapitalloan/calc/ProjectedAmortizationScheduleCalculator.java

@@ -70,4 +70,20 @@ ProjectedAmortizationScheduleModel addDisbursement(@NonNull ProjectedAmortizatio
      *            actual payment amount
      */
     void applyPayment(@NonNull ProjectedAmortizationScheduleModel model, @NonNull LocalDate paymentDate, @NonNull BigDecimal paymentAmount);
+
+    /**
+     * Creates a sub-model with a new period payment rate effective from the given date. The original model is preserved
+     * separately; the returned model covers only the remaining term with recalculated parameters.
+     *
+     * @param model
+     *            current model (not mutated)
+     * @param newPeriodPaymentRate
+     *            the new period payment rate
+     * @param rateChangeDate
+     *            effective date of the rate change
+     * @return new sub-model for the remaining term
+     */
+    @NonNull
+    ProjectedAmortizationScheduleModel applyRateChange(@NonNull ProjectedAmortizationScheduleModel model,
+            @NonNull BigDecimal newPeriodPaymentRate, @NonNull LocalDate rateChangeDate);
 }

fineract-working-capital-loan/src/main/java/org/apache/fineract/portfolio/workingcapitalloan/calc/ProjectedAmortizationScheduleModel.java

@@ -45,6 +45,8 @@
  * <li>{@link #generate} — create initial schedule (at loan creation)</li>
  * <li>{@link #regenerate} — recalculate with new amounts (at approval / disbursement)</li>
  * <li>{@link #applyPayment} — record payments by date; schedule rebuilds after each</li>
+ * <li>{@link #regenerateWithNewRate} — create a sub-model with a new period payment rate (mid-lifecycle rate change);
+ * returns a fresh model for the remaining term, does not carry over applied payments</li>
  * </ol>
  */
 @Getter
@@ -247,6 +249,75 @@ public void recalculateNetAmortizationAndDeferredBalanceFrom(final LocalDate rep
         this.payments = List.copyOf(adjusted);
     }
 
+    /**
+     * Creates a sub-model with a new period payment rate, effective from {@code rateChangeDate}. The sub-model covers
+     * the remaining loan term from the change date forward. Previously applied payments are NOT carried over — they
+     * belong to the original (frozen) model.
+     *
+     * <h4>Sub-model parameter formulas (from spreadsheet)</h4>
+     * <ul>
+     * <li>{@code newNetDisbursement = balanceAtSplitPoint} (NPV balance of remaining expected payments)</li>
+     * <li>{@code newDiscount = origDiscount + origNet - balanceAtSplitPoint - paymentsReceived}</li>
+     * <li>{@code newDailyPayment = ROUND(TPV × newRate / npvDayCount, 2)}</li>
+     * <li>{@code newTotalDays = ROUND((origNet + origDiscount - paymentsReceived) / newDailyPayment, 2)}</li>
+     * <li>{@code newEIR = RATE(floor(newTotalDays), -newDailyPayment, newNetDisbursement)}</li>
+     * </ul>
+     *
+     * @param newPeriodPaymentRate
+     *            the new period payment rate
+     * @param rateChangeDate
+     *            the business date of the rate change (becomes the sub-model's disbursement date)
+     * @return a fresh sub-model covering the remaining term with the new rate
+     */
+    public ProjectedAmortizationScheduleModel regenerateWithNewRate(final BigDecimal newPeriodPaymentRate, final LocalDate rateChangeDate) {
+        Objects.requireNonNull(newPeriodPaymentRate, "newPeriodPaymentRate");
+        Objects.requireNonNull(rateChangeDate, "rateChangeDate");
+
+        final int splitDayIndex = (int) ChronoUnit.DAYS.between(expectedDisbursementDate, rateChangeDate);
+        if (splitDayIndex < 0) {
+            throw new IllegalArgumentException("rateChangeDate must not be before expectedDisbursementDate");
+        }
+
+        BigDecimal paymentsReceived = BigDecimal.ZERO;
+        BigDecimal balanceAtSplit = netDisbursementAmount.getAmount();
+        for (final ProjectedPayment p : payments) {
+            if (p.paymentNo() <= 0 || p.paymentNo() > splitDayIndex) {
+                continue;
+            }
+            if (p.actualPaymentAmount() != null) {
+                paymentsReceived = paymentsReceived.add(p.actualPaymentAmount().getAmount(), mc);
+            }
+            if (p.balance() != null) {
+                balanceAtSplit = p.balance().getAmount();
+            }
+        }
+
+        final BigDecimal origNet = netDisbursementAmount.getAmount();
+        final BigDecimal origDiscount = originationFeeAmount.getAmount();
+        final BigDecimal tpv = totalPaymentValue.getAmount();
+
+        final BigDecimal newNetDisb = balanceAtSplit;
+        final BigDecimal newDiscount = origDiscount.add(origNet, mc).subtract(balanceAtSplit, mc).subtract(paymentsReceived, mc);
+        final BigDecimal newDailyPayment = tpv.multiply(newPeriodPaymentRate, mc).divide(BigDecimal.valueOf(npvDayCount), mc).setScale(2,
+                RoundingMode.HALF_UP);
+        final BigDecimal fractionalTotalDays = origNet.add(origDiscount, mc).subtract(paymentsReceived, mc).divide(newDailyPayment, mc)
+                .setScale(2, RoundingMode.HALF_UP);
+        final int newTerm = fractionalTotalDays.intValue();
+
+        if (newTerm <= 0) {
+            throw new IllegalArgumentException("computed sub-model term must be positive, got: " + newTerm);
+        }
+        if (newNetDisb.signum() <= 0) {
+            throw new IllegalArgumentException("newNetDisbursement must be positive for sub-model");
+        }
+
+        final BigDecimal newEir = TvmFunctions.rate(newTerm, newDailyPayment.negate(), newNetDisb, mc);
+
+        return new ProjectedAmortizationScheduleModel(Money.of(currency, newDiscount, mc), Money.of(currency, newNetDisb, mc),
+                totalPaymentValue, newPeriodPaymentRate, npvDayCount, rateChangeDate, Money.of(currency, newDailyPayment, mc), newTerm,
+                newEir, mc, currency);
+    }
+
     private void rebuildPayments() {
         final Map<LocalDate, BigDecimal> paymentsByDate = aggregatePaymentsByDate();
         final List<BigDecimal> paymentList = buildPaymentList(paymentsByDate);

fineract-working-capital-loan/src/main/java/org/apache/fineract/portfolio/workingcapitalloan/calc/TvmFunctions.java

@@ -119,8 +119,14 @@ public static BigDecimal rate(final int nper, final BigDecimal pmt, final BigDec
     }
 
     /**
-     * Linear approximation for the initial Newton-Raphson guess: {@code r ≈ 2·(pmt·n + pv) / (pv·n)}. Falls back to
-     * {@value #DEFAULT_GUESS} if the estimate is non-positive.
+     * Linear approximation for the initial Newton-Raphson guess: {@code r ≈ 2·(pmt·n + pv) / (pv·n)}.
+     *
+     * <p>
+     * When total payments exceed the present value (typical for loans with origination fees), the formula yields a
+     * negative estimate. Its <em>absolute</em> value is still a good approximation of the periodic rate — it equals
+     * {@code 2·interest / (pv·n)} — so we return {@code |estimate|} instead of a fixed default. This avoids
+     * catastrophic divergence in Newton-Raphson when {@code nper} is large (e.g., daily-payment loans with thousands of
+     * periods), where the old default of 0.01 caused {@code (1+0.01)^nper} to explode.
      */
     private static BigDecimal estimateInitialGuess(final int nper, final BigDecimal pmt, final BigDecimal pv, final MathContext mc) {
         final BigDecimal n = BigDecimal.valueOf(nper);
@@ -129,7 +135,10 @@ private static BigDecimal estimateInitialGuess(final int nper, final BigDecimal
             return DEFAULT_GUESS;
         }
         final BigDecimal estimate = pmt.multiply(n, mc).add(pv, mc).multiply(TWO, mc).divide(pvTimesN, mc);
-        return estimate.signum() > 0 ? estimate : DEFAULT_GUESS;
+        if (estimate.signum() == 0) {
+            return DEFAULT_GUESS;
+        }
+        return estimate.abs();
     }
 
     /**

fineract-working-capital-loan/src/main/java/org/apache/fineract/portfolio/workingcapitalloan/data/WorkingCapitalLoanPeriodPaymentRateChangeData.java

@@ -0,0 +1,28 @@
+/**
+ * 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.
+ */
+package org.apache.fineract.portfolio.workingcapitalloan.data;
+
+import java.math.BigDecimal;
+import java.time.LocalDate;
+import java.time.OffsetDateTime;
+
+public record WorkingCapitalLoanPeriodPaymentRateChangeData(Long id, Long loanId, LocalDate effectiveDate, BigDecimal previousRate,
+        BigDecimal newRate, boolean reversed, LocalDate reversedOnDate, OffsetDateTime createdDate) {
+
+}

fineract-working-capital-loan/src/main/java/org/apache/fineract/portfolio/workingcapitalloan/domain/ProjectedAmortizationLoanModel.java

@@ -54,4 +54,7 @@ public class ProjectedAmortizationLoanModel extends AbstractPersistableCustom<Lo
 
     @Column(name = "json_model_version", nullable = false)
     private String jsonModelVersion;
+
+    @Column(name = "previous_json_model", columnDefinition = "text")
+    private String previousJsonModel;
 }