FINERACT-2455: WC - Introduce Loan OverpaidOnDate

[somasorosdpc]

Description

Describe the changes made and why they were made. (Ignore if these details are present on the associated Apache Fineract JIRA ticket.)

Checklist

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.
• If merging this PR resolves a JIRA issue, I will mark that issue as resolved and set "Fix Version/s" appropriately.

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

[galovics]

CI is red on this one (3 e2e failures in the new scenarios), and I think the failures are pointing at real gaps rather than flakes.

overpaidOnDate is only ever written at the moment of a status change, via WorkingCapitalLoanLifecycleStateMachine. Two consequences:

1. UC11 (backdated repayment that tips the loan into overpayment): the date gets stamped with the transaction date passed in, not the date the loan actually became overpaid - expected: "2026-01-06" but was: "2026-01-03".
2. UC12 (undoing one of two overpaying repayments, leaving the loan still OVERPAID): since determineAndTransition only acts when the status actually changes, and the loan stays OVERPAID after the undo, the date never gets recomputed and the stale value survives - expected: "2026-01-05" but was: "2026-01-03".

Core Loan's own lifecycle state machine (DefaultLoanLifecycleStateMachine.determineAndTransition) has an unconditional guard - if (isEmpty(totalOverpaid)) setOverpaidOnDate(null) - that runs independent of whether a transition fires. This WC version ties clearing exclusively to a transition, which is the root of both failures. Worth mirroring that guard, and deciding explicitly whether the semantics should be "date of the triggering transaction" (current impl) or "date first became overpaid, recomputed from history" (what the tests assert) - right now the code and the tests disagree.

3. UC13: the business event never carries the new field - WorkingCapitalLoanAccountDataMapper still has @Mapping(target = "overpaidOnDate", ignore = true), which predates this PR adding the field to WorkingCapitalLoanData. That ignore needs to go now that there's something to map. expected: "2026-01-04" but was: null.

Two more things worth fixing before merge:

• No backfill for loans that are already in OVERPAID status today - they'll report null forever since nothing will ever re-trigger a transition for them. The module has a precedent for add-column-plus-backfill in the same part file (0070_wc_loan_principal_balance_backfill.xml) - worth following that here.
• No unit test for WorkingCapitalLoanLifecycleStateMachine at all (core has one for its equivalent). Given the date semantics are non-trivial across a dozen transitions, that would catch this class of bug faster than a 25-minute e2e shard.

Recommendation: CHANGES_REQUESTED

[somasorosdpc]

Description

Describe the changes made and why they were made. (Ignore if these details are present on the associated Apache Fineract JIRA ticket.)

Checklist

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.
• If merging this PR resolves a JIRA issue, I will mark that issue as resolved and set "Fix Version/s" appropriately.

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

[galovics]

CI is red on this one (3 e2e failures in the new scenarios), and I think the failures are pointing at real gaps rather than flakes.

overpaidOnDate is only ever written at the moment of a status change, via WorkingCapitalLoanLifecycleStateMachine. Two consequences:

1. UC11 (backdated repayment that tips the loan into overpayment): the date gets stamped with the transaction date passed in, not the date the loan actually became overpaid - expected: "2026-01-06" but was: "2026-01-03".
2. UC12 (undoing one of two overpaying repayments, leaving the loan still OVERPAID): since determineAndTransition only acts when the status actually changes, and the loan stays OVERPAID after the undo, the date never gets recomputed and the stale value survives - expected: "2026-01-05" but was: "2026-01-03".

Core Loan's own lifecycle state machine (DefaultLoanLifecycleStateMachine.determineAndTransition) has an unconditional guard - if (isEmpty(totalOverpaid)) setOverpaidOnDate(null) - that runs independent of whether a transition fires. This WC version ties clearing exclusively to a transition, which is the root of both failures. Worth mirroring that guard, and deciding explicitly whether the semantics should be "date of the triggering transaction" (current impl) or "date first became overpaid, recomputed from history" (what the tests assert) - right now the code and the tests disagree.

3. UC13: the business event never carries the new field - WorkingCapitalLoanAccountDataMapper still has @Mapping(target = "overpaidOnDate", ignore = true), which predates this PR adding the field to WorkingCapitalLoanData. That ignore needs to go now that there's something to map. expected: "2026-01-04" but was: null.

Two more things worth fixing before merge:

• No backfill for loans that are already in OVERPAID status today - they'll report null forever since nothing will ever re-trigger a transition for them. The module has a precedent for add-column-plus-backfill in the same part file (0070_wc_loan_principal_balance_backfill.xml) - worth following that here.
• No unit test for WorkingCapitalLoanLifecycleStateMachine at all (core has one for its equivalent). Given the date semantics are non-trivial across a dozen transitions, that would catch this class of bug faster than a 25-minute e2e shard.

Recommendation: CHANGES_REQUESTED

[somasorosdpc]

Description

Describe the changes made and why they were made. (Ignore if these details are present on the associated Apache Fineract JIRA ticket.)

Checklist

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.
• If merging this PR resolves a JIRA issue, I will mark that issue as resolved and set "Fix Version/s" appropriately.

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

[galovics]

CI is red on this one (3 e2e failures in the new scenarios), and I think the failures are pointing at real gaps rather than flakes.

overpaidOnDate is only ever written at the moment of a status change, via WorkingCapitalLoanLifecycleStateMachine. Two consequences:

1. UC11 (backdated repayment that tips the loan into overpayment): the date gets stamped with the transaction date passed in, not the date the loan actually became overpaid - expected: "2026-01-06" but was: "2026-01-03".
2. UC12 (undoing one of two overpaying repayments, leaving the loan still OVERPAID): since determineAndTransition only acts when the status actually changes, and the loan stays OVERPAID after the undo, the date never gets recomputed and the stale value survives - expected: "2026-01-05" but was: "2026-01-03".

Core Loan's own lifecycle state machine (DefaultLoanLifecycleStateMachine.determineAndTransition) has an unconditional guard - if (isEmpty(totalOverpaid)) setOverpaidOnDate(null) - that runs independent of whether a transition fires. This WC version ties clearing exclusively to a transition, which is the root of both failures. Worth mirroring that guard, and deciding explicitly whether the semantics should be "date of the triggering transaction" (current impl) or "date first became overpaid, recomputed from history" (what the tests assert) - right now the code and the tests disagree.

3. UC13: the business event never carries the new field - WorkingCapitalLoanAccountDataMapper still has @Mapping(target = "overpaidOnDate", ignore = true), which predates this PR adding the field to WorkingCapitalLoanData. That ignore needs to go now that there's something to map. expected: "2026-01-04" but was: null.

Two more things worth fixing before merge:

• No backfill for loans that are already in OVERPAID status today - they'll report null forever since nothing will ever re-trigger a transition for them. The module has a precedent for add-column-plus-backfill in the same part file (0070_wc_loan_principal_balance_backfill.xml) - worth following that here.
• No unit test for WorkingCapitalLoanLifecycleStateMachine at all (core has one for its equivalent). Given the date semantics are non-trivial across a dozen transitions, that would catch this class of bug faster than a 25-minute e2e shard.

Recommendation: CHANGES_REQUESTED

[somasorosdpc]

Description

Describe the changes made and why they were made. (Ignore if these details are present on the associated Apache Fineract JIRA ticket.)

Checklist

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.
• If merging this PR resolves a JIRA issue, I will mark that issue as resolved and set "Fix Version/s" appropriately.

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

[galovics]

CI is red on this one (3 e2e failures in the new scenarios), and I think the failures are pointing at real gaps rather than flakes.

overpaidOnDate is only ever written at the moment of a status change, via WorkingCapitalLoanLifecycleStateMachine. Two consequences:

1. UC11 (backdated repayment that tips the loan into overpayment): the date gets stamped with the transaction date passed in, not the date the loan actually became overpaid - expected: "2026-01-06" but was: "2026-01-03".
2. UC12 (undoing one of two overpaying repayments, leaving the loan still OVERPAID): since determineAndTransition only acts when the status actually changes, and the loan stays OVERPAID after the undo, the date never gets recomputed and the stale value survives - expected: "2026-01-05" but was: "2026-01-03".

Core Loan's own lifecycle state machine (DefaultLoanLifecycleStateMachine.determineAndTransition) has an unconditional guard - if (isEmpty(totalOverpaid)) setOverpaidOnDate(null) - that runs independent of whether a transition fires. This WC version ties clearing exclusively to a transition, which is the root of both failures. Worth mirroring that guard, and deciding explicitly whether the semantics should be "date of the triggering transaction" (current impl) or "date first became overpaid, recomputed from history" (what the tests assert) - right now the code and the tests disagree.

3. UC13: the business event never carries the new field - WorkingCapitalLoanAccountDataMapper still has @Mapping(target = "overpaidOnDate", ignore = true), which predates this PR adding the field to WorkingCapitalLoanData. That ignore needs to go now that there's something to map. expected: "2026-01-04" but was: null.

Two more things worth fixing before merge:

• No backfill for loans that are already in OVERPAID status today - they'll report null forever since nothing will ever re-trigger a transition for them. The module has a precedent for add-column-plus-backfill in the same part file (0070_wc_loan_principal_balance_backfill.xml) - worth following that here.
• No unit test for WorkingCapitalLoanLifecycleStateMachine at all (core has one for its equivalent). Given the date semantics are non-trivial across a dozen transitions, that would catch this class of bug faster than a 25-minute e2e shard.

Recommendation: CHANGES_REQUESTED

[somasorosdpc]

Description

Describe the changes made and why they were made. (Ignore if these details are present on the associated Apache Fineract JIRA ticket.)

Checklist

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.
• If merging this PR resolves a JIRA issue, I will mark that issue as resolved and set "Fix Version/s" appropriately.

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

[galovics]

CI is red on this one (3 e2e failures in the new scenarios), and I think the failures are pointing at real gaps rather than flakes.

overpaidOnDate is only ever written at the moment of a status change, via WorkingCapitalLoanLifecycleStateMachine. Two consequences:

1. UC11 (backdated repayment that tips the loan into overpayment): the date gets stamped with the transaction date passed in, not the date the loan actually became overpaid - expected: "2026-01-06" but was: "2026-01-03".
2. UC12 (undoing one of two overpaying repayments, leaving the loan still OVERPAID): since determineAndTransition only acts when the status actually changes, and the loan stays OVERPAID after the undo, the date never gets recomputed and the stale value survives - expected: "2026-01-05" but was: "2026-01-03".

Core Loan's own lifecycle state machine (DefaultLoanLifecycleStateMachine.determineAndTransition) has an unconditional guard - if (isEmpty(totalOverpaid)) setOverpaidOnDate(null) - that runs independent of whether a transition fires. This WC version ties clearing exclusively to a transition, which is the root of both failures. Worth mirroring that guard, and deciding explicitly whether the semantics should be "date of the triggering transaction" (current impl) or "date first became overpaid, recomputed from history" (what the tests assert) - right now the code and the tests disagree.

3. UC13: the business event never carries the new field - WorkingCapitalLoanAccountDataMapper still has @Mapping(target = "overpaidOnDate", ignore = true), which predates this PR adding the field to WorkingCapitalLoanData. That ignore needs to go now that there's something to map. expected: "2026-01-04" but was: null.

Two more things worth fixing before merge:

• No backfill for loans that are already in OVERPAID status today - they'll report null forever since nothing will ever re-trigger a transition for them. The module has a precedent for add-column-plus-backfill in the same part file (0070_wc_loan_principal_balance_backfill.xml) - worth following that here.
• No unit test for WorkingCapitalLoanLifecycleStateMachine at all (core has one for its equivalent). Given the date semantics are non-trivial across a dozen transitions, that would catch this class of bug faster than a 25-minute e2e shard.

Recommendation: CHANGES_REQUESTED

[somasorosdpc]

Description

Describe the changes made and why they were made. (Ignore if these details are present on the associated Apache Fineract JIRA ticket.)

Checklist

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.
• If merging this PR resolves a JIRA issue, I will mark that issue as resolved and set "Fix Version/s" appropriately.

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

[galovics]

CI is red on this one (3 e2e failures in the new scenarios), and I think the failures are pointing at real gaps rather than flakes.

overpaidOnDate is only ever written at the moment of a status change, via WorkingCapitalLoanLifecycleStateMachine. Two consequences:

1. UC11 (backdated repayment that tips the loan into overpayment): the date gets stamped with the transaction date passed in, not the date the loan actually became overpaid - expected: "2026-01-06" but was: "2026-01-03".
2. UC12 (undoing one of two overpaying repayments, leaving the loan still OVERPAID): since determineAndTransition only acts when the status actually changes, and the loan stays OVERPAID after the undo, the date never gets recomputed and the stale value survives - expected: "2026-01-05" but was: "2026-01-03".

Core Loan's own lifecycle state machine (DefaultLoanLifecycleStateMachine.determineAndTransition) has an unconditional guard - if (isEmpty(totalOverpaid)) setOverpaidOnDate(null) - that runs independent of whether a transition fires. This WC version ties clearing exclusively to a transition, which is the root of both failures. Worth mirroring that guard, and deciding explicitly whether the semantics should be "date of the triggering transaction" (current impl) or "date first became overpaid, recomputed from history" (what the tests assert) - right now the code and the tests disagree.

3. UC13: the business event never carries the new field - WorkingCapitalLoanAccountDataMapper still has @Mapping(target = "overpaidOnDate", ignore = true), which predates this PR adding the field to WorkingCapitalLoanData. That ignore needs to go now that there's something to map. expected: "2026-01-04" but was: null.

Two more things worth fixing before merge:

• No backfill for loans that are already in OVERPAID status today - they'll report null forever since nothing will ever re-trigger a transition for them. The module has a precedent for add-column-plus-backfill in the same part file (0070_wc_loan_principal_balance_backfill.xml) - worth following that here.
• No unit test for WorkingCapitalLoanLifecycleStateMachine at all (core has one for its equivalent). Given the date semantics are non-trivial across a dozen transitions, that would catch this class of bug faster than a 25-minute e2e shard.

Recommendation: CHANGES_REQUESTED

[somasorosdpc]

Description

Describe the changes made and why they were made. (Ignore if these details are present on the associated Apache Fineract JIRA ticket.)

Checklist

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.
• If merging this PR resolves a JIRA issue, I will mark that issue as resolved and set "Fix Version/s" appropriately.

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

[galovics]

CI is red on this one (3 e2e failures in the new scenarios), and I think the failures are pointing at real gaps rather than flakes.

overpaidOnDate is only ever written at the moment of a status change, via WorkingCapitalLoanLifecycleStateMachine. Two consequences:

1. UC11 (backdated repayment that tips the loan into overpayment): the date gets stamped with the transaction date passed in, not the date the loan actually became overpaid - expected: "2026-01-06" but was: "2026-01-03".
2. UC12 (undoing one of two overpaying repayments, leaving the loan still OVERPAID): since determineAndTransition only acts when the status actually changes, and the loan stays OVERPAID after the undo, the date never gets recomputed and the stale value survives - expected: "2026-01-05" but was: "2026-01-03".

Core Loan's own lifecycle state machine (DefaultLoanLifecycleStateMachine.determineAndTransition) has an unconditional guard - if (isEmpty(totalOverpaid)) setOverpaidOnDate(null) - that runs independent of whether a transition fires. This WC version ties clearing exclusively to a transition, which is the root of both failures. Worth mirroring that guard, and deciding explicitly whether the semantics should be "date of the triggering transaction" (current impl) or "date first became overpaid, recomputed from history" (what the tests assert) - right now the code and the tests disagree.

3. UC13: the business event never carries the new field - WorkingCapitalLoanAccountDataMapper still has @Mapping(target = "overpaidOnDate", ignore = true), which predates this PR adding the field to WorkingCapitalLoanData. That ignore needs to go now that there's something to map. expected: "2026-01-04" but was: null.

Two more things worth fixing before merge:

• No backfill for loans that are already in OVERPAID status today - they'll report null forever since nothing will ever re-trigger a transition for them. The module has a precedent for add-column-plus-backfill in the same part file (0070_wc_loan_principal_balance_backfill.xml) - worth following that here.
• No unit test for WorkingCapitalLoanLifecycleStateMachine at all (core has one for its equivalent). Given the date semantics are non-trivial across a dozen transitions, that would catch this class of bug faster than a 25-minute e2e shard.

Recommendation: CHANGES_REQUESTED

[somasorosdpc]

Description

Describe the changes made and why they were made. (Ignore if these details are present on the associated Apache Fineract JIRA ticket.)

Checklist

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.
• If merging this PR resolves a JIRA issue, I will mark that issue as resolved and set "Fix Version/s" appropriately.

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

[galovics]

CI is red on this one (3 e2e failures in the new scenarios), and I think the failures are pointing at real gaps rather than flakes.

overpaidOnDate is only ever written at the moment of a status change, via WorkingCapitalLoanLifecycleStateMachine. Two consequences:

1. UC11 (backdated repayment that tips the loan into overpayment): the date gets stamped with the transaction date passed in, not the date the loan actually became overpaid - expected: "2026-01-06" but was: "2026-01-03".
2. UC12 (undoing one of two overpaying repayments, leaving the loan still OVERPAID): since determineAndTransition only acts when the status actually changes, and the loan stays OVERPAID after the undo, the date never gets recomputed and the stale value survives - expected: "2026-01-05" but was: "2026-01-03".

Core Loan's own lifecycle state machine (DefaultLoanLifecycleStateMachine.determineAndTransition) has an unconditional guard - if (isEmpty(totalOverpaid)) setOverpaidOnDate(null) - that runs independent of whether a transition fires. This WC version ties clearing exclusively to a transition, which is the root of both failures. Worth mirroring that guard, and deciding explicitly whether the semantics should be "date of the triggering transaction" (current impl) or "date first became overpaid, recomputed from history" (what the tests assert) - right now the code and the tests disagree.

3. UC13: the business event never carries the new field - WorkingCapitalLoanAccountDataMapper still has @Mapping(target = "overpaidOnDate", ignore = true), which predates this PR adding the field to WorkingCapitalLoanData. That ignore needs to go now that there's something to map. expected: "2026-01-04" but was: null.

Two more things worth fixing before merge:

• No backfill for loans that are already in OVERPAID status today - they'll report null forever since nothing will ever re-trigger a transition for them. The module has a precedent for add-column-plus-backfill in the same part file (0070_wc_loan_principal_balance_backfill.xml) - worth following that here.
• No unit test for WorkingCapitalLoanLifecycleStateMachine at all (core has one for its equivalent). Given the date semantics are non-trivial across a dozen transitions, that would catch this class of bug faster than a 25-minute e2e shard.

Recommendation: CHANGES_REQUESTED