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 updatePeriodPaymentRateWorkingCapitalLoanApplication(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

@@ -77,4 +77,7 @@ private WorkingCapitalLoanConstants() {
 
     public static final String WRITE_OFF_REASONS = "WriteOffReasons";
     public static final String CHARGE_OFF_REASONS = "ChargeOffReasons";
+
+    // 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,64 @@ private CommandProcessingResult updateDiscount(final Long loanId, final String l
                 .updateDiscountWorkingCapitalLoanApplication(resolvedLoanId).build();
         return this.commandsSourceWritePlatformService.logCommandSource(commandRequest);
     }
+
+    @PUT
+    @Path("{loanId}/payment-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)))
+    public CommandProcessingResult updatePeriodPaymentRateById(
+            @PathParam("loanId") @Parameter(description = "loanId", required = true) final Long loanId,
+            @Parameter(hidden = true) final String apiRequestBodyAsJson) {
+        return updatePeriodPaymentRate(loanId, null, apiRequestBodyAsJson);
+    }
+
+    @PUT
+    @Path("external-id/{loanExternalId}/payment-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)))
+    public CommandProcessingResult updatePeriodPaymentRateByExternalId(
+            @PathParam("loanExternalId") @Parameter(description = "loanExternalId", required = true) final String loanExternalId,
+            @Parameter(hidden = true) final String apiRequestBodyAsJson) {
+        return updatePeriodPaymentRate(null, loanExternalId, apiRequestBodyAsJson);
+    }
+
+    private CommandProcessingResult updatePeriodPaymentRate(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)
+                .updatePeriodPaymentRateWorkingCapitalLoanApplication(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.")
+    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.")
+    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,19 @@ 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;
+    }
+
 }

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

@@ -54,4 +54,12 @@ 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) {
+        model.applyRateChange(newPeriodPaymentRate, rateChangeDate);
+        return model;
+    }
 }

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);
+
+    /**
+     * Applies a rate change to the model in-place. Adds a {@link ProjectedAmortizationScheduleModel.RateSegment} and
+     * rebuilds the payment list.
+     *
+     * @param model
+     *            the model to mutate
+     * @param newPeriodPaymentRate
+     *            the new period payment rate
+     * @param rateChangeDate
+     *            effective date of the rate change
+     * @return the same model instance (mutated)
+     */
+    @NonNull
+    ProjectedAmortizationScheduleModel applyRateChange(@NonNull ProjectedAmortizationScheduleModel model,
+            @NonNull BigDecimal newPeriodPaymentRate, @NonNull LocalDate rateChangeDate);
 }