FFA

MCL/CPW has requested the ability to de-allocate (reverse) unused advance balances from one client and allow reallocation to another client.

This requirement arises from operational scenarios where advance payments are initially recorded under one client but later need to be reassigned due to changes in consignee details.

Business Scenario¶

1. An advance payment is recorded under Client X
2. Part of the advance is used for invoicing
3. A remaining balance exists under Client X
4. For a new consignment for same client:
   • A different consignee (Client Y) is declared
   • The invoice will be issued under Client Y
5. User requests:
   • De-allocation of the remaining balance from Client X
   • Reallocation via a new advance payment under Client Y

Current Behavior¶

• Advance payments:
  • Are tied to a specific client
  • Are reduced when used in receipting
• There is no functionality to reverse or de-allocate unused balances

Approach: Adjustment-Based De-allocation¶

Introduce a "De-allocate Balance" action within the existing Advance Payment screen modal.

Functional Behavior¶

1. De-allocation Action¶

• Add button: "De-allocate Balance" in Advance Payment view modal
• Visible only when available advance balance > 0

2. User Input¶

• De-allocation amount (≤ available balance)
• Mandatory: Reason / remarks

3. System Processing¶

• System will:
  • Deduct the entered amount from Client X’s advance balance
  • Record a negative adjustment transaction
  • Update the balance immediately

4. Reallocation Flow¶

• User will then:
  • Create a new advance payment under Client Y using existing functionality

UI/UX Requirements¶

• Add De-allocate Balance button in Advance Payment modal
• Confirmation dialog:
  • "Are you sure you want to de-allocate this amount from this client’s advance balance?"
• Keep consistency with current design system

Functional Requirements¶

• Validation:
  • De-allocation must apply only to unused balance. Amounts already consumed in receipting/invoicing must not be reversible through this function.
  • De-allocation amount must not exceed available balance
• Data integrity:
  • Already allocated/used amounts must remain unaffected
• Audit trail/Activity log
  • Log transaction as Advance De-allocation with:
    • Client reference
    • de-allocated amount and remaining balance after de-allocation
    • User who performed the action
    • Timestamp
    • Reason
• Permissions:
  • Restrict to authorized roles—authority-based (e.g., Finance/Admin)

Acceptance Criteria¶

• "De-allocate Balance" button is visible when balance > 0
• User can input a valid de-allocation amount
• System prevents over-deallocation
• Confirmation dialog is displayed
• Advance balance is reduced correctly
• Adjustment transaction is recorded for audit
• No impact on previously allocated invoice amounts
• User can subsequently create a new advance under another client