FINERACT-2232: Capitalized income - Add Capitalized income to Loan

2025-04-30 10:23:55 +02:00
parent bb0bdb9670
commit e10542838e
18 changed files with 471 additions and 1 deletions
@@ -123,6 +123,47 @@ public class AccrualBasedAccountingProcessorForLoan implements AccountingProcess
            else if (transactionType.isInterestPaymentWaiver() || transactionType.isInterestRefund()) {
                createJournalEntriesForInterestPaymentWaiverOrInterestRefund(loanDTO, loanTransactionDTO, office);
            }
+            // Handle Capitalized Income
+            if (transactionType.isCapitalizedIncome()) {
+                createJournalEntriesForCapitalizedIncome(loanDTO, loanTransactionDTO, office);
+            }
+        }
+    }
+
+    private void createJournalEntriesForCapitalizedIncome(final LoanDTO loanDTO, final LoanTransactionDTO loanTransactionDTO,
+            final Office office) {
+        // loan properties
+        final Long loanProductId = loanDTO.getLoanProductId();
+        final Long loanId = loanDTO.getLoanId();
+        final String currencyCode = loanDTO.getCurrencyCode();
+        // transaction properties
+        final String transactionId = loanTransactionDTO.getTransactionId();
+        final LocalDate transactionDate = loanTransactionDTO.getTransactionDate();
+        final BigDecimal principalAmount = loanTransactionDTO.getPrincipal();
+        final Long paymentTypeId = loanTransactionDTO.getPaymentTypeId();
+        GLAccountBalanceHolder glAccountBalanceHolder = new GLAccountBalanceHolder();
+
+        if (MathUtil.isGreaterThanZero(principalAmount)) {
+            populateCreditDebitMaps(loanProductId, principalAmount, paymentTypeId,
+                    AccrualAccountsForLoan.DEFERRED_INCOME_LIABILITY.getValue(), AccrualAccountsForLoan.LOAN_PORTFOLIO.getValue(),
+                    glAccountBalanceHolder);
+        }
+
+        // create credit entries
+        for (Map.Entry<Long, BigDecimal> creditEntry : glAccountBalanceHolder.getCreditBalances().entrySet()) {
+            if (MathUtil.isGreaterThanZero(creditEntry.getValue())) {
+                GLAccount glAccount = glAccountBalanceHolder.getGlAccountMap().get(creditEntry.getKey());
+                this.helper.createCreditJournalEntryForLoan(office, currencyCode, loanId, transactionId, transactionDate,
+                        creditEntry.getValue(), glAccount);
+            }
+        }
+        // create debit entries
+        for (Map.Entry<Long, BigDecimal> debitEntry : glAccountBalanceHolder.getDebitBalances().entrySet()) {
+            if (MathUtil.isGreaterThanZero(debitEntry.getValue())) {
+                GLAccount glAccount = glAccountBalanceHolder.getGlAccountMap().get(debitEntry.getKey());
+                this.helper.createDebitJournalEntryForLoan(office, currencyCode, loanId, transactionId, transactionDate,
+                        debitEntry.getValue(), glAccount);
+            }
        }
    }

@@ -90,6 +90,7 @@ public class LoanTransactionsApiResource {
    public static final String REAGE = "reAge";
    public static final String REAMORTIZE = "reAmortize";
    public static final String UNDO_REAMORTIZE = "undoReAmortize";
+    public static final String CAPITALIZED_INCOME = "capitalizedIncome";
    private final Set<String> responseDataParameters = new HashSet<>(Arrays.asList("id", "type", "date", "currency", "amount", "externalId",
            LoanApiConstants.REVERSAL_EXTERNAL_ID_PARAMNAME, LoanApiConstants.REVERSED_ON_DATE_PARAMNAME));

@@ -526,6 +527,7 @@ public class LoanTransactionsApiResource {
            case accrualActivity -> LoanTransactionType.ACCRUAL_ACTIVITY;
            case interestRefund -> LoanTransactionType.INTEREST_REFUND;
            case accrualAdjustment -> LoanTransactionType.ACCRUAL_ADJUSTMENT;
+            case capitalizedIncome -> LoanTransactionType.CAPITALIZED_INCOME;
            default ->
                throw new InvalidLoanTransactionTypeException("transaction", transactionTypeParam.name(), "Unknown transaction type");
        };
@@ -583,6 +585,8 @@ public class LoanTransactionsApiResource {
            commandRequest = builder.reAmortize(resolvedLoanId).build();
        } else if (CommandParameterUtil.is(commandParam, UNDO_REAMORTIZE)) {
            commandRequest = builder.undoReAmortize(resolvedLoanId).build();
+        } else if (CommandParameterUtil.is(commandParam, CAPITALIZED_INCOME)) {
+            commandRequest = builder.addCapitalizedIncome(resolvedLoanId).build();
        }

        if (commandRequest == null) {
@@ -69,6 +69,8 @@ import org.apache.fineract.portfolio.loanaccount.api.LoanApiConstants;
 import org.apache.fineract.portfolio.loanaccount.data.HolidayDetailDTO;
 import org.apache.fineract.portfolio.loanaccount.data.ScheduleGeneratorDTO;
 import org.apache.fineract.portfolio.loanaccount.domain.Loan;
+import org.apache.fineract.portfolio.loanaccount.domain.LoanCapitalizedIncomeBalance;
+import org.apache.fineract.portfolio.loanaccount.domain.LoanCapitalizedIncomeBalanceRepository;
 import org.apache.fineract.portfolio.loanaccount.domain.LoanCollateralManagement;
 import org.apache.fineract.portfolio.loanaccount.domain.LoanDisbursementDetails;
 import org.apache.fineract.portfolio.loanaccount.domain.LoanEvent;
@@ -105,6 +107,7 @@ public final class LoanTransactionValidator {
    private final EntityDatatableChecksWritePlatformService entityDatatableChecksWritePlatformService;
    private final CalendarInstanceRepository calendarInstanceRepository;
    private final LoanDownPaymentTransactionValidator loanDownPaymentTransactionValidator;
+    private final LoanCapitalizedIncomeBalanceRepository loanCapitalizedIncomeBalanceRepository;

    private void throwExceptionIfValidationWarningsExist(final List<ApiParameterError> dataValidationErrors) {
        if (!dataValidationErrors.isEmpty()) {
@@ -1034,4 +1037,91 @@ public final class LoanTransactionValidator {
                    loan.getRescheduledOnDate());
        }
    }
+
+    public void validateCapitalizedIncome(final JsonCommand command, final Long loanId) {
+        final String json = command.json();
+        if (StringUtils.isBlank(json)) {
+            throw new InvalidJsonException();
+        }
+
+        final JsonElement element = this.fromApiJsonHelper.parse(json);
+        final Type typeOfMap = new TypeToken<Map<String, Object>>() {}.getType();
+        this.fromApiJsonHelper.checkForUnsupportedParameters(typeOfMap, json, getCapitalizedIncomeParameters());
+
+        LoanApplicationValidator.validateOrThrow("loan.capitalized.income", baseDataValidator -> {
+            final Loan loan = this.loanRepositoryWrapper.findOneWithNotFoundDetection(loanId, true);
+            validateLoanClientIsActive(loan);
+            validateLoanGroupIsActive(loan);
+
+            // Validate that loan is disbursed
+            if (!loan.isDisbursed()) {
+                baseDataValidator.reset().failWithCodeNoParameterAddedToErrorCode("capitalized.income.only.after.disbursement",
+                        "Capitalized income can be added to the loan only after Disbursement");
+            }
+
+            // Validate loan is progressive
+            if (!loan.isProgressiveSchedule()) {
+                baseDataValidator.reset().failWithCodeNoParameterAddedToErrorCode("not.progressive.loan");
+            }
+
+            // Validate income capitalization is enabled
+            if (!loan.getLoanProductRelatedDetail().isEnableIncomeCapitalization()) {
+                baseDataValidator.reset().failWithCodeNoParameterAddedToErrorCode("income.capitalization.not.enabled");
+            }
+
+            // Validate loan is active
+            if (!loan.getStatus().isActive()) {
+                baseDataValidator.reset().failWithCodeNoParameterAddedToErrorCode("not.active");
+            }
+
+            final LocalDate transactionDate = this.fromApiJsonHelper.extractLocalDateNamed("transactionDate", element);
+            baseDataValidator.reset().parameter("transactionDate").value(transactionDate).notNull();
+
+            // Validate transaction date is not before disbursement date
+            if (transactionDate != null && loan.getDisbursementDate() != null && transactionDate.isBefore(loan.getDisbursementDate())) {
+                baseDataValidator.reset().parameter("transactionDate").failWithCode("before.disbursement.date",
+                        "Transaction date cannot be before disbursement date");
+            }
+
+            final BigDecimal transactionAmount = this.fromApiJsonHelper.extractBigDecimalWithLocaleNamed("transactionAmount", element);
+            baseDataValidator.reset().parameter("transactionAmount").value(transactionAmount).notNull().positiveAmount();
+
+            // Validate total disbursement + capitalized income <= approved amount
+            if (transactionAmount != null) {
+                final BigDecimal totalDisbursed = loan.getDisbursedAmount();
+                final BigDecimal existingCapitalizedIncomeBalance = loanCapitalizedIncomeBalanceRepository.findAllByLoanId(loanId).stream()
+                        .map(LoanCapitalizedIncomeBalance::getAmount).reduce(BigDecimal.ZERO, BigDecimal::add);
+                final BigDecimal approvedAmount = loan.getApprovedPrincipal();
+                final BigDecimal newTotal = totalDisbursed.add(existingCapitalizedIncomeBalance).add(transactionAmount);
+
+                if (newTotal.compareTo(approvedAmount) > 0) {
+                    baseDataValidator.reset().parameter("transactionAmount").failWithCode("exceeds.approved.amount",
+                            "Sum of disbursed amount and capitalized income cannot exceed approved amount");
+                }
+            }
+
+            validatePaymentDetails(baseDataValidator, element);
+            validateNote(baseDataValidator, element);
+            validateExternalId(baseDataValidator, element);
+        });
+    }
+
+    private void validateNote(final DataValidatorBuilder baseDataValidator, final JsonElement element) {
+        final String note = this.fromApiJsonHelper.extractStringNamed("note", element);
+        if (StringUtils.isNotBlank(note)) {
+            baseDataValidator.reset().parameter("note").value(note).notExceedingLengthOf(1000);
+        }
+    }
+
+    private void validateExternalId(final DataValidatorBuilder baseDataValidator, final JsonElement element) {
+        final String externalId = this.fromApiJsonHelper.extractStringNamed("externalId", element);
+        if (StringUtils.isNotBlank(externalId)) {
+            baseDataValidator.reset().parameter("externalId").value(externalId).notExceedingLengthOf(100);
+        }
+    }
+
+    private Set<String> getCapitalizedIncomeParameters() {
+        return new HashSet<>(
+                Arrays.asList("transactionDate", "dateFormat", "locale", "transactionAmount", "paymentTypeId", "note", "externalId"));
+    }
 }
@@ -2996,6 +2996,53 @@ public class LoanWritePlatformServiceJpaRepositoryImpl implements LoanWritePlatf
                .build();
    }

+    @Transactional
+    @Override
+    public CommandProcessingResult addCapitalizedIncome(final Long loanId, final JsonCommand command) {
+        loanTransactionValidator.validateCapitalizedIncome(command, loanId);
+
+        final Loan loan = loanAssembler.assembleFrom(loanId);
+        final AppUser currentUser = getAppUserIfPresent();
+        final Map<String, Object> changes = new LinkedHashMap<>();
+
+        // Create payment details
+        final PaymentDetail paymentDetail = this.paymentDetailWritePlatformService.createAndPersistPaymentDetail(command, changes);
+
+        // Validate cash payment if applicable
+        if (paymentDetail != null && paymentDetail.getPaymentType() != null && paymentDetail.getPaymentType().getIsCashPayment()) {
+            BigDecimal transactionAmount = command.bigDecimalValueOfParameterNamed("transactionAmount");
+            this.cashierTransactionDataValidator.validateOnLoanDisbursal(currentUser, loan.getCurrencyCode(), transactionAmount);
+        }
+
+        // Extract transaction details
+        final LocalDate transactionDate = command.localDateValueOfParameterNamed("transactionDate");
+        final BigDecimal transactionAmount = command.bigDecimalValueOfParameterNamed("transactionAmount");
+        final ExternalId txnExternalId = externalIdFactory.createFromCommand(command, "externalId");
+
+        // Create capitalized income transaction
+        final Money capitalizedIncomeAmount = Money.of(loan.getCurrency(), transactionAmount);
+        final LoanTransaction capitalizedIncomeTransaction = LoanTransaction.capitalizedIncome(loan, capitalizedIncomeAmount, paymentDetail,
+                transactionDate, txnExternalId);
+
+        // Update loan with capitalized income
+        capitalizedIncomeTransaction.updateLoan(loan);
+        loan.addLoanTransaction(capitalizedIncomeTransaction);
+        loanTransactionRepository.saveAndFlush(capitalizedIncomeTransaction);
+
+        // Update loan counters and save
+        loan.updateLoanScheduleDependentDerivedFields();
+
+        // Create note if provided
+        createNote(loan, command, changes);
+
+        // Post journal entries
+        final List<Long> existingTransactionIds = new ArrayList<>(loan.findExistingTransactionIds());
+        final List<Long> existingReversedTransactionIds = new ArrayList<>(loan.findExistingReversedTransactionIds());
+        journalEntryPoster.postJournalEntries(loan, existingTransactionIds, existingReversedTransactionIds);
+
+        return new CommandProcessingResultBuilder().withEntityId(loan.getId()).withEntityExternalId(loan.getExternalId()).build();
+    }
+
    public void handleChargebackTransaction(final Loan loan, LoanTransaction chargebackTransaction) {
        loanTransactionValidator.validateIfTransactionIsChargeback(chargebackTransaction);