FINERACT-2048: Make amount and recurrence fields optional for Dues-based Standing Instructions

[dr-fuch]

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!

• Write the commit message as per our guidelines
• 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 for verifying the changes made.
• Follow our 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". Large changes can be made in a branch, with assistance. Ask for help on the developer mailing list.

Your assigned reviewer(s) will follow our guidelines for code reviews.