FINERACT-2455: Working Capital Loan Charge - Product Creation & Template

fineract-charge/src/main/java/org/apache/fineract/portfolio/charge/api/ChargesApiResource.java

@@ -33,6 +33,7 @@
 import jakarta.ws.rs.Path;
 import jakarta.ws.rs.PathParam;
 import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.QueryParam;
 import jakarta.ws.rs.core.Context;
 import jakarta.ws.rs.core.MediaType;
 import jakarta.ws.rs.core.UriInfo;
@@ -101,7 +102,8 @@ public ChargeData retrieveCharge(@PathParam("chargeId") @Parameter(description =
 
         ChargeData charge = readPlatformService.retrieveCharge(chargeId);
         if (settings.isTemplate()) {
-            final ChargeData templateData = readPlatformService.retrieveNewChargeDetails();
+            final ChargeData templateData = readPlatformService.retrieveNewChargeDetails(charge.getChargeAppliesTo().getId(),
+                    charge.getChargeTimeType().getId());
             charge = ChargeData.withTemplate(charge, templateData);
         }
         return charge;
@@ -119,9 +121,10 @@ public ChargeData retrieveCharge(@PathParam("chargeId") @Parameter(description =
 
             charges/template
             """)
-    public ChargeData retrieveNewChargeDetails() {
+    public ChargeData retrieveNewChargeDetails(@QueryParam("chargeAppliesTo") Long chargeAppliesTo,
+            @QueryParam("chargeTimeType") Long chargeTimeType) {
         context.authenticatedUser().validateHasReadPermission(RESOURCE_NAME_FOR_PERMISSIONS);
-        return readPlatformService.retrieveNewChargeDetails();
+        return readPlatformService.retrieveNewChargeDetails(chargeAppliesTo, chargeTimeType);
     }
 
     @POST

fineract-charge/src/main/java/org/apache/fineract/portfolio/charge/domain/Charge.java

@@ -174,7 +174,9 @@ public static Charge fromJson(final JsonCommand command, final GLAccount account
                 .fromInt(command.integerValueOfParameterNamed(CHARGE_CALCULATION_TYPE_PARAM_NAME));
         final Integer chargePaymentMode = command.integerValueOfParameterNamed("chargePaymentMode");
 
-        final ChargePaymentMode paymentMode = chargePaymentMode == null ? null : ChargePaymentMode.fromInt(chargePaymentMode);
+        final ChargePaymentMode paymentMode = chargePaymentMode == null
+                ? (chargeAppliesTo.isWorkingCapitalLoanCharge() ? ChargePaymentMode.REGULAR : null)
+                : ChargePaymentMode.fromInt(chargePaymentMode);
 
         final boolean penalty = command.booleanPrimitiveValueOfParameterNamed("penalty");
         final boolean active = command.booleanPrimitiveValueOfParameterNamed("active");
@@ -423,6 +425,17 @@ public Map<String, Object> update(final JsonCommand command) {
                     baseDataValidator.reset().parameter(CHARGE_TIME_PARAM_NAME).value(this.chargeTimeType)
                             .failWithCodeNoParameterAddedToErrorCode("not.allowed.charge.time.for.loan");
                 }
+            } else if (ChargeAppliesTo.WORKING_CAPITAL_LOAN.getValue().equals(this.chargeAppliesTo)) {
+                baseDataValidator.reset().parameter(CHARGE_TIME_PARAM_NAME).value(chargeTimeType).notNull()
+                        .isOneOfTheseValues(ChargeTimeType.validWorkingCapitalLoanValues());
+
+                Object[] validCalculationTypeValues = new Object[] {};
+                if (ChargeTimeType.SPECIFIED_DUE_DATE.getValue().equals(chargeTimeType)) {
+                    validCalculationTypeValues = ChargeCalculationType.validValuesForWorkingCapitalLoanSpecifiedDueDate();
+                }
+                baseDataValidator.reset().parameter(CHARGE_CALCULATION_TYPE_PARAM_NAME).value(chargeCalculation).notNull()
+                        .isOneOfTheseValues(validCalculationTypeValues);
+
             } else if (isClientCharge() && !isAllowedLoanChargeTime()) {
                 baseDataValidator.reset().parameter(CHARGE_TIME_PARAM_NAME).value(this.chargeTimeType)
                         .failWithCodeNoParameterAddedToErrorCode("not.allowed.charge.time.for.client");

fineract-charge/src/main/java/org/apache/fineract/portfolio/charge/domain/ChargeAppliesTo.java

@@ -24,7 +24,8 @@ public enum ChargeAppliesTo {
     LOAN(1, "chargeAppliesTo.loan"), //
     SAVINGS(2, "chargeAppliesTo.savings"), //
     CLIENT(3, "chargeAppliesTo.client"), //
-    SHARES(4, "chargeAppliesTo.shares"); //
+    SHARES(4, "chargeAppliesTo.shares"), //
+    WORKING_CAPITAL_LOAN(5, "chargeAppliesTo.workingCapitalLoan"); //
 
     private final Integer value;
     private final String code;
@@ -59,6 +60,9 @@ public static ChargeAppliesTo fromInt(final Integer chargeAppliesTo) {
                 case 4:
                     chargeAppliesToType = SHARES;
                 break;
+                case 5:
+                    chargeAppliesToType = WORKING_CAPITAL_LOAN;
+                break;
                 default:
                     chargeAppliesToType = INVALID;
                 break;
@@ -80,12 +84,16 @@ public boolean isClientCharge() {
         return this.value.equals(ChargeAppliesTo.CLIENT.getValue());
     }
 
+    public boolean isWorkingCapitalLoanCharge() {
+        return ChargeAppliesTo.WORKING_CAPITAL_LOAN.getValue().equals(value);
+    }
+
     public boolean isSharesCharge() {
         return this.value.equals(SHARES.getValue());
     }
 
     public static Object[] validValues() {
         return new Object[] { ChargeAppliesTo.LOAN.getValue(), ChargeAppliesTo.SAVINGS.getValue(), ChargeAppliesTo.CLIENT.getValue(),
-                ChargeAppliesTo.SHARES.getValue() };
+                ChargeAppliesTo.SHARES.getValue(), ChargeAppliesTo.WORKING_CAPITAL_LOAN.getValue() };
     }
 }

fineract-charge/src/main/java/org/apache/fineract/portfolio/charge/domain/ChargeCalculationType.java

@@ -18,6 +18,8 @@
  */
 package org.apache.fineract.portfolio.charge.domain;
 
+import java.util.List;
+
 public enum ChargeCalculationType {
 
     INVALID(0, "chargeCalculationType.invalid"), //
@@ -35,6 +37,18 @@ public enum ChargeCalculationType {
         this.code = code;
     }
 
+    public static List<ChargeCalculationType> validEnumsForWorkingCapitalLoan() {
+        return List.of(ChargeCalculationType.FLAT);
+    }
+
+    public static List<ChargeCalculationType> validEnumsForWorkingCapitalLoanSpecifiedDueDate() {
+        return List.of(ChargeCalculationType.FLAT);
+    }
+
+    public static Object[] validValuesForWorkingCapitalLoanSpecifiedDueDate() {
+        return validEnumsForWorkingCapitalLoanSpecifiedDueDate().stream().map(ChargeCalculationType::getValue).toArray();
+    }
+
     public Integer getValue() {
         return this.value;
     }

fineract-charge/src/main/java/org/apache/fineract/portfolio/charge/serialization/ChargeDefinitionCommandFromApiJsonDeserializer.java

@@ -255,6 +255,22 @@ public void validateForCreate(final String json) {
                 baseDataValidator.reset().parameter(CHARGE_CALCULATION_TYPE).value(chargeCalculationType)
                         .isOneOfTheseValues(ChargeCalculationType.validValuesForShareAccountActivation());
             }
+        } else if (appliesTo.isWorkingCapitalLoanCharge()) {
+            final Integer chargeTimeType = this.fromApiJsonHelper.extractIntegerSansLocaleNamed(CHARGE_TIME_TYPE, element);
+            baseDataValidator.reset().parameter(CHARGE_TIME_TYPE).value(chargeTimeType).notNull();
+
+            if (chargeTimeType != null) {
+                baseDataValidator.reset().parameter(CHARGE_TIME_TYPE).value(chargeTimeType)
+                        .isOneOfTheseValues(ChargeTimeType.validWorkingCapitalLoanValues());
+            }
+
+            if (chargeCalculationType != null) {
+                Object[] validValues = new Object[] {};
+                if (ChargeTimeType.SPECIFIED_DUE_DATE.getValue().equals(chargeTimeType)) {
+                    validValues = ChargeCalculationType.validValuesForWorkingCapitalLoanSpecifiedDueDate();
+                }
+                baseDataValidator.reset().parameter(CHARGE_CALCULATION_TYPE).value(chargeCalculationType).isOneOfTheseValues(validValues);
+            }
         }
 
         final String name = this.fromApiJsonHelper.extractStringNamed(NAME, element);

fineract-charge/src/main/java/org/apache/fineract/portfolio/charge/service/ChargeDropdownReadPlatformService.java

@@ -20,6 +20,8 @@
 
 import java.util.List;
 import org.apache.fineract.infrastructure.core.data.EnumOptionData;
+import org.apache.fineract.portfolio.charge.domain.ChargeAppliesTo;
+import org.apache.fineract.portfolio.charge.domain.ChargeTimeType;
 
 public interface ChargeDropdownReadPlatformService {
 
@@ -29,7 +31,7 @@ public interface ChargeDropdownReadPlatformService {
 
     List<EnumOptionData> retrieveCollectionTimeTypes();
 
-    List<EnumOptionData> retrivePaymentModes();
+    List<EnumOptionData> retrievePaymentModes();
 
     List<EnumOptionData> retrieveLoanCalculationTypes();
 
@@ -47,4 +49,9 @@ public interface ChargeDropdownReadPlatformService {
 
     List<EnumOptionData> retrieveSharesCollectionTimeTypes();
 
+    List<EnumOptionData> retrieveCalculationTypes(ChargeAppliesTo chargeAppliesTo, ChargeTimeType chargeTimeType);
+
+    List<EnumOptionData> retrieveCollectionTimeTypes(ChargeAppliesTo chargeAppliesTo);
+
+    List<EnumOptionData> retrievePaymentModes(ChargeAppliesTo chargeAppliesTo);
 }

fineract-charge/src/main/java/org/apache/fineract/portfolio/charge/service/ChargeDropdownReadPlatformServiceImpl.java

@@ -68,7 +68,7 @@ public List<EnumOptionData> retrieveCollectionTimeTypes() {
     }
 
     @Override
-    public List<EnumOptionData> retrivePaymentModes() {
+    public List<EnumOptionData> retrievePaymentModes() {
         return Arrays.asList(chargePaymentMode(ChargePaymentMode.REGULAR), chargePaymentMode(ChargePaymentMode.ACCOUNT_TRANSFER));
     }
 
@@ -124,4 +124,36 @@ public List<EnumOptionData> retrieveSharesCollectionTimeTypes() {
         return Arrays.asList(chargeTimeType(ChargeTimeType.SHAREACCOUNT_ACTIVATION), chargeTimeType(ChargeTimeType.SHARE_PURCHASE),
                 chargeTimeType(ChargeTimeType.SHARE_REDEEM));
     }
+
+    @Override
+    public List<EnumOptionData> retrieveCalculationTypes(ChargeAppliesTo chargeAppliesTo, ChargeTimeType chargeTimeType) {
+        if (ChargeAppliesTo.WORKING_CAPITAL_LOAN.equals(chargeAppliesTo)) {
+            if (chargeTimeType == null) {
+                return ChargeCalculationType.validEnumsForWorkingCapitalLoan().stream().map(ChargeEnumerations::chargeCalculationType)
+                        .toList();
+            }
+            if (ChargeTimeType.SPECIFIED_DUE_DATE.equals(chargeTimeType)) {
+                return ChargeCalculationType.validEnumsForWorkingCapitalLoanSpecifiedDueDate().stream()
+                        .map(ChargeEnumerations::chargeCalculationType).toList();
+            }
+            return null;
+        }
+        return retrieveCalculationTypes();
+    }
+
+    @Override
+    public List<EnumOptionData> retrieveCollectionTimeTypes(ChargeAppliesTo chargeAppliesTo) {
+        if (ChargeAppliesTo.WORKING_CAPITAL_LOAN.equals(chargeAppliesTo)) {
+            return ChargeTimeType.validWorkingCapitalLoan().stream().map(ChargeEnumerations::chargeTimeType).toList();
+        }
+        return retrieveCollectionTimeTypes();
+    }
+
+    @Override
+    public List<EnumOptionData> retrievePaymentModes(ChargeAppliesTo chargeAppliesTo) {
+        if (ChargeAppliesTo.WORKING_CAPITAL_LOAN.equals(chargeAppliesTo)) {
+            return List.of(chargePaymentMode(ChargePaymentMode.REGULAR));
+        }
+        return retrievePaymentModes();
+    }
 }

fineract-charge/src/main/java/org/apache/fineract/portfolio/charge/service/ChargeEnumerations.java

@@ -130,6 +130,10 @@ public static EnumOptionData chargeAppliesTo(final ChargeAppliesTo type) {
             case SHARES:
                 optionData = new EnumOptionData(ChargeAppliesTo.SHARES.getValue().longValue(), ChargeAppliesTo.SHARES.getCode(), "Shares");
             break;
+            case WORKING_CAPITAL_LOAN:
+                optionData = new EnumOptionData(ChargeAppliesTo.WORKING_CAPITAL_LOAN.getValue().longValue(),
+                        ChargeAppliesTo.WORKING_CAPITAL_LOAN.getCode(), "Working Capital Loan");
+            break;
             default:
                 optionData = new EnumOptionData(ChargeAppliesTo.INVALID.getValue().longValue(), ChargeAppliesTo.INVALID.getCode(),
                         "Invalid");

fineract-charge/src/main/java/org/apache/fineract/portfolio/charge/service/ChargeReadPlatformService.java

@@ -32,6 +32,8 @@ public interface ChargeReadPlatformService {
 
     ChargeData retrieveNewChargeDetails();
 
+    ChargeData retrieveNewChargeDetails(Long chargeAppliesTo, Long chargeTimeType);
+
     /**
      * Returns all charges that can be applied to Cients
      *

fineract-core/src/main/java/org/apache/fineract/portfolio/charge/domain/ChargeTimeType.java

@@ -18,6 +18,8 @@
  */
 package org.apache.fineract.portfolio.charge.domain;
 
+import java.util.List;
+
 public enum ChargeTimeType {
 
     INVALID(0, "chargeTimeType.invalid"), //
@@ -60,6 +62,14 @@ public static Object[] validLoanValues() {
                 ChargeTimeType.TRANCHE_DISBURSEMENT.getValue() };
     }
 
+    public static List<ChargeTimeType> validWorkingCapitalLoan() {
+        return List.of(ChargeTimeType.SPECIFIED_DUE_DATE);
+    }
+
+    public static Object[] validWorkingCapitalLoanValues() {
+        return validWorkingCapitalLoan().stream().map(ChargeTimeType::getValue).toArray();
+    }
+
     public static Object[] validLoanChargeValues() {
         return new Integer[] { ChargeTimeType.DISBURSEMENT.getValue(), ChargeTimeType.SPECIFIED_DUE_DATE.getValue(),
                 ChargeTimeType.INSTALMENT_FEE.getValue() };

fineract-doc/src/docs/en/chapters/features/charges-template-filters.adoc

@@ -0,0 +1,51 @@
+== Template API Filtering
+
+The charge template API is enhanced to support filtered responses for charge creation.
+
+Previously, the template endpoint returned every possible configuration option regardless of applicability. This behavior remains unchanged when no filter parameters are provided.
+
+With this enhancement, the API supports hierarchical filtering of template options to reduce irrelevant configuration values for Working Capital Loan charge products.
+
+=== Filtering Levels
+
+Filtering is applied in the following order:
+
+1. `chargeAppliesTo`
+ - filters and returns only applicable `chargeTimeType`s
+2. `chargeTimeType`
+ - filters and returns only applicable `chargeCalculationType`s
+
+Each filtering level depends on the previous level being provided.
+
+=== chargeAppliesTo Filter
+
+A new query parameter is introduced:
+
+[source,http]
+----
+GET /charges/template?chargeAppliesTo=<value>
+----
+
+When `chargeAppliesTo` is specified, the API returns only the template fields and dropdown options applicable to the selected entity type.
+
+Supported values include:
+* `Working Capital Loan`
+
+=== chargeTimeType Filter
+
+An additional filtering level is available when `chargeAppliesTo` is also provided:
+
+[source,http]
+----
+GET /charges/template?chargeAppliesTo=<value>&chargeTimeType=<value>
+----
+
+Supported values for WCP Loans:
+
+* `Specified due date`
+
+The API response filters the available `chargeCalculationType` options based on the selected charge time type.
+
+== Backward Compatibility
+
+If no query parameters are provided, the template API continues to return all available options to preserve legacy behavior.

fineract-doc/src/docs/en/chapters/features/index.adoc

@@ -17,7 +17,9 @@ include::re-ageing.adoc[leveloffset=+1]
 include::delayed-schedule-captures.adoc[leveloffset=+1]
 include::loan-origination-details.adoc[leveloffset=+1]
 include::taxes-on-loan-charges.adoc[leveloffset=+1]
+include::charges-template-filters.adoc[leveloffset=+1]
 include::working-capital-amortization-schedule.adoc[leveloffset=+1]
 include::working-capital-discount-fee-txn.adoc[leveloffset=+1]
+include::working-capital-charges.adoc[leveloffset=+1]
 include::working-capital-credit-balance-refund.adoc[leveloffset=+1]
 include::working-capital-goodwill-credit.adoc[leveloffset=+1]

fineract-doc/src/docs/en/chapters/features/working-capital-charges.adoc

@@ -0,0 +1,59 @@
+= Working Capital Loan Charges
+
+This documentation focuses on Working Capital Loan-related charge changes.
+
+== Create/Update Charge
+
+Creates or updates a charge product applicable to Working Capital Loans.
+
+=== Supported Fields
+
+==== Mandatory Fields
+
+* `chargeAppliesTo`
+** Must be set to `5`, as the `WorkingCapitalLoan` enum identifier is `5`.
+
+* `chargeTimeType`
+
+* `chargeCalculationType`
+
+* `name`
+** Must be unique across all charge products.
+
+* `amount`
+
+* `active`
+** Boolean value.
+
+* `currencyCode`
+** Refer to the template API for supported currency codes.
+
+* `locale`
+** Refer to the available platform locales.
+
+* `penalty`
+** Boolean value.
+
+==== Optional Fields
+
+* `chargePaymentMode`
+** Defaults to `regular` when not provided.
+
+=== Supported Values
+
+==== chargeAppliesTo
+
+* `WorkingCapitalLoan`
+
+[NOTE]
+====
+`Loan`, `Savings`, `Client`, and `Shares` charge entities are outside the scope of this documentation.
+====
+
+==== chargeTimeType
+
+* `specified due date`
+
+==== chargeCalculationType
+
+* `flat`