dr-fuch opened a new pull request, #5895:
URL: https://github.com/apache/fineract/pull/5895
## Description
### 📋 Overview
This PR introduces significant improvements to the **Standing Instructions
(SI)** module, specifically to support instructions based on loan dues
(**Dues-based instructions**).
Previously, the system enforced fixed amounts and periodic recurrence for
all types of instructions. These changes allow for more flexible automated loan
repayments where the transaction amount and timing are dictated by the **loan
schedule** rather than a fixed calendar.
---
### 🛠 Key Changes
#### 1. API Constants & Error Handling
Added specific error codes in `StandingInstructionApiConstants` to provide
granular feedback for invalid configurations and ensure data integrity:
* **Dues & Amount Validations:**
* `not.allowed.for.dues.instruction`: Thrown when an amount is provided
for a "Dues" type instruction (where the amount must be derived from the loan).
* `as.per.dues.not.allowed.with.fixed.amount`: Prevents "As Per Dues"
recurrence when a fixed amount is defined.
* **Account & Transfer Constraints:**
* `dues.not.allowed.for.account.transfer`: Prevents Dues-based
instructions for standard peer-to-peer account transfers.
* `as.per.dues.not.allowed.for.account.transfer`: Prevents Dues-based
recurrence when the target is a Savings account.
* `transfer.to.same.account.not.allowed`: Ensures the source and
destination accounts are different.
* `account.transfer.is.not.allowed.for.loan.accounts` &
`is.not.a.valid.loan.repayment`: Validation for incorrect account type mappings.
* **Scheduling & Date Integrity:**
* `invalid.month.day.format`: Handles incorrect formatting for
recurrence date parameters.
* `must.not.be.before.first.execution.date`: Ensures `validTill` doesn't
cut off the first scheduled run.
* `must.be.before.existing.valid.till` &
`cannot.be.before.last.run.date`: Critical checks for maintaining consistency
during instruction updates.
#### 2. Data Validation Layer
Heavily refactored `StandingInstructionDataValidator` to implement a
**Business Decision Matrix**:
* **Dues Support:** Amount is now optional/prohibited when `instructionType`
is `DUES`.
* **Recurrence Logic:** Added support for **"As per Dues"** recurrence,
bypassing traditional frequency/interval requirements.
* **Enhanced Update Validation:** `validateForUpdate` now performs
cross-field validation between incoming changes and the current entity state.
#### 3. Domain & Entity Integrity
* **Automatic Field Cleanup:** Modified `AccountTransferStandingInstruction`
to ensure consistency. Updating to "Dues" automatically clears fixed amounts
and periodic recurrence fields (`frequency`, `interval`, `monthDay`) to prevent
"data noise".
* **Null-Safe Comparisons:** Implemented `java.util.Objects.equals` to
handle transitions between null/non-null states, preventing
`NullPointerExceptions`.
* **Lombok Integration:** Standardized the use of `@Getter` for cleaner,
more readable code.
---
### 🧪 Automated Testing
Introduced a robust unit test suite: `StandingInstructionDataValidatorTest`
using **Parameterized Tests** and **Nested Classes** to cover:
1. ✅ Successful creation/update of Dues-based instructions.
2. ✅ Validation of mandatory fields for **Periodic** vs. **Dues** recurrence.
3. ✅ Cross-validation between transfer types (**Account Transfer** vs.
**Loan Repayment**).
---
## Checking
Please make sure these boxes are checked before submitting your pull request
- thanks!
- [X] Write the commit message as per [our
guidelines](https://github.com/apache/fineract/blob/develop/CONTRIBUTING.md#pull-requests)
- [X] 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.
- [X] Create/update [unit or integration
tests](https://fineract.apache.org/docs/current/#_testing) for verifying the
changes made.
- [X] Follow our [coding
conventions](https://cwiki.apache.org/confluence/display/FINERACT/Coding+Conventions).
- [X] 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
- [X] [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).
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]
