Cocoa-Puffs opened a new pull request, #6754:
URL: https://github.com/apache/fineract/pull/6754
## Description
Progressive loans using the advanced payment allocation strategy can
configure a credit allocation rule for chargebacks: an ordered list of
`PENALTY`, `FEE`, `INTEREST` and `PRINCIPAL` that decides which portions of the
original repayment are charged back. Without such a rule, the whole chargeback
amount is booked as principal.
This PR makes that choice explicit by adding a strategy to each credit
allocation entry:
- `RULE_BASED` (default): the existing behaviour. `creditAllocationOrder` is
required.
- `PRINCIPAL_ONLY` (new): the whole chargeback amount is allocated to
principal, using the same implementation that already applies when no rule is
configured. `creditAllocationOrder` must not be sent.
The strategy enum is designed to take further strategies.
### API
```json
"creditAllocation": [
{ "transactionType": "CHARGEBACK", "creditAllocationStrategy":
"PRINCIPAL_ONLY" }
]
```
```json
"creditAllocation": [
{
"transactionType": "CHARGEBACK",
"creditAllocationStrategy": "RULE_BASED",
"creditAllocationOrder": [
{ "creditAllocationRule": "PENALTY", "order": 1 },
{ "creditAllocationRule": "FEE", "order": 2 },
{ "creditAllocationRule": "INTEREST", "order": 3 },
{ "creditAllocationRule": "PRINCIPAL", "order": 4 }
]
}
]
```
- A missing `creditAllocationStrategy` means `RULE_BASED`, so existing
clients and payloads keep working unchanged.
- `GET /loanproducts/{id}` returns `creditAllocationStrategy` on each entry.
For `PRINCIPAL_ONLY`, `creditAllocationOrder` is an empty list.
- `GET /loanproducts/template` has a new `creditAllocationStrategyOptions`
list.
- New validation errors (400):
- `RULE_BASED` without `creditAllocationOrder`;
- `PRINCIPAL_ONLY` with `creditAllocationOrder`;
- an unknown or non-string strategy value.
These checks run after the existing "creditAllocation must not be
provided" check for products without the advanced payment allocation strategy,
so that error still takes precedence. An empty `creditAllocationOrder: []` is
treated as not provided.
### Database
Changeset `1036` in the loan module:
- `1036-1` adds `allocation_strategy` (NOT NULL, default `RULE_BASED`) to
`m_loan_product_credit_allocation_rule` and `m_loan_credit_allocation_rule`.
Existing rules become rule based, so their behaviour does not change.
- `1036-2` drops NOT NULL on `allocation_types`, because principal-only
rules have no order. It adds a CHECK constraint so `RULE_BASED` rows must still
have one.
### Behaviour change: credit balance refund outstanding balance
`LoanBalanceService` computes the running outstanding balance of overpaid
chargebacks and credit balance refunds in one branch.
- **Before:** it chose the formula by checking whether the loan had *any*
credit allocation rule. So a credit balance refund on a loan whose product has
a chargeback rule used the rule-based formula: principal minus principal paid
through schedule mappings.
- **Now:** the strategy is resolved by the transaction's own type. A refund
can never have a rule, so it always uses the formula for loans without a rule:
amount minus overpayment portion.
The stored `outstandingLoanBalance` of a refund changes only when **all** of
these hold:
- the loan's product has a chargeback credit allocation rule;
- the refund has both a principal portion and an overpayment portion above
zero. That happens when the refund exceeds the overpayment held at its date
after a replay, for example because an earlier repayment was undone. A refund
fully covered by overpayment gives the same result under both formulas.
The old formula subtracted the overpayment twice in that case. In the
scenario covered by
`creditBalanceRefundExceedingOverpaymentOnReplayDoesNotDependOnChargebackRule`,
it reported 50 instead of the correct 100. That test fails against the old code
and passes with this change. **Reprocessing such loans can therefore change the
stored outstanding balance of their refunds.**
## Checklist
Please make sure these boxes are checked before submitting your pull request
- thanks!
- [ ] Write the commit message as per [our
guidelines](https://github.com/apache/fineract/blob/develop/CONTRIBUTING.md#pull-requests)
- [ ] Acknowledge that we will not review PRs that are not passing the build
_("green")_ - it is your responsibility to get a proposed PR to pass the build,
not primarily the project's maintainers.
- [ ] Create/update [unit or integration
tests](https://fineract.apache.org/docs/current/#_testing) for verifying the
changes made.
- [ ] Follow our [coding
conventions](https://cwiki.apache.org/confluence/display/FINERACT/Coding+Conventions).
- [ ] Add required Swagger annotation and update API documentation at
fineract-provider/src/main/resources/static/legacy-docs/apiLive.htm with
details of any API changes
- [ ] [This PR must not be a "code
dump"](https://cwiki.apache.org/confluence/display/FINERACT/Pull+Request+Size+Limit).
Large changes can be made in a branch, with assistance. Ask for help on the
[developer mailing list](https://fineract.apache.org/#contribute).
- [ ] If merging this PR resolves a JIRA issue, I will mark that issue as
resolved and set "Fix Version/s" appropriately.
- [ ] I followed the [AI
Policy](https://github.com/apache/fineract/blob/develop/CONTRIBUTING.md#ai-policy).
Your assigned reviewer(s) will follow our [guidelines for code
reviews](https://cwiki.apache.org/confluence/display/FINERACT/Code+Review+Guide).
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
