Cash Management Functional Specification

Executive Summary

Purpose & Scope

• Manage the end-to-end lifecycle of cash processing, from initial bank deposit entry to final GL posting.
• Scope includes: Deposit entry/management, Cash Receipt creation, Worksheet allocation (to receivables/ledger), Approval workflows, and GL integration.
• Primary Objective: Ensure all cash is accurately recorded, controlled via "Control Totals", and applied to open receivables with a transparent audit trail.

Process Overview

flowchart LR
    Deposit[Bank Deposit] -->|Contains| Receipts[Cash Receipts]
    Receipts -->|Processed via| Worksheet[Cash Worksheet]
    Worksheet -->|Allocates to| App[Applications]
    App -->|Clears| AR[Receivables]
    App -->|Posts to| GL[General Ledger]

1. Deposits

1.1 Process Description

The Deposit is the container for all incoming cash. It represents a physical bank deposit or batch. Users effectively "declare" the total amount they expect to process (the Control Total) before entering individual checks or wires.

1.2 Core Rules & Requirements

Control Total Validation

• The user must enter a Deposit Gross Amount (Control Total).
• The system validates that this total significantly matches the sum of all entered Cash Receipts.
• Rule: Deposit Total must equal Sum(Receipt Amounts) (within $0.01 tolerance).
• Enforcement: Validation check occurs before a deposit is considered "Balanced" or ready for final reconciliation.

Editing Restrictions (Locking)

To maintain data integrity, a Deposit becomes locked based on the state of its contents:

Field	Lock Condition	Reason
Currency	ANY Cash Receipts exist (even Draft).	Changing currency would invalidate all child receipt amounts and exchange rates.
Bank Account	Non-Draft Receipts exist.	Once a receipt is processed (Ready/Confirmed), its bank association is fixed.
Deposit Date	Non-Draft Receipts exist.	processed receipts rely on the deposit date for GL posting periods.
Deposit Ref	Non-Draft Receipts exist.	Reference used in downstream reporting.

Deletion Rules

• A Deposit can only be deleted if it is "empty" or "safe".
• Allowed: No Cash Receipts exist.
• Allowed: All associated Cash Receipts are in DRAFT status (cascading delete logic may apply or require manual receipt deletion first).
• Blocked: If any Cash Receipt is READY, CONFIRMED, or VOIDED.

1.3 User Interface Specifications

Deposit Screen

• List View:
  • Displays standard grid of deposits.
  • Status indicators showing if the deposit is "Balanced" (Total matches Receipts).
  • Actions: Create, Edit, Delete (if eligible).

Deposit Detail / Edit Dialog

• Fields:
  • Bank Account (Dropdown, filtered by user access).
  • Deposit Date (Date Picker).
  • Reference (Free text).
  • Currency (Dropdown).
  • Gross Amount (Numeric, the "Control Total").
• Real-Time Validation:
  • If user attempts to edit a locked field (e.g., Currency on a deposit with receipts), the field should be disabled or show a tooltip explaining the lock.

2. Cash Receipts

2.1 Process Description

A Cash Receipt represents a distinct payment (e.g., a single check, wire, or adjustment) within a Deposit. It creates the "pool" of funds that can be applied to Receivables. A single Deposit can contain multiple Cash Receipts.

2.2 Core Rules & Requirements

Status Lifecycle

Status	Code	Description	Transitions Allowed
Draft	D	Initial state. Editable. Not ready for posting.	-> Confirmed
Confirmed	C	Validated and locked. Available for Worksheet processing.	-> Voided
Voided	V	Negated/Cancelled. Cannot be used. Reverses GL if previously posted.	Terminal State

Currency Operations

• Dual-Currency Tracking: The system tracks both the Original Amount/Currency (what was on the check) and the Converted Amount/Currency (what is deposited).
• FX Rate Logic:
  • If Original Currency ≠ Deposit Currency, an FX Rate is required.
  • Receipt Amount is automatically calculated as: Original Amount * FX Rate.
  • If currencies match, FX Rate defaults to 1.0.

Editing Restrictions

• Draft Status: All fields are editable.
• Confirmed Status:
  • Locked: Amounts, Currency, FX Rates.
  • Editable: Only Reference and Internal Comments.
  • Logic: To change financial data, user must Void and re-create, or "Unconfirm" (if no worksheet exists - Note: Unconfirm logic not explicitly found in service, assuming Void/Re-create workflow based on code).
• Voided Status: Read-only.

Deletion & Voiding Rules

• Delete: Allowed only if no Worksheet applications exist.
• Void:
  • Allowed only for Confirmed receipts.
  • Blocked if specific "Payout" applications exist (requires manual intervention).
  • Effect: Sets status to V, marks any associated Worksheets as "Non-Current".

2.3 User Interface Specifications

Cash Receipt Dialog (Create/Edit)

• Header: Linked Deposit (ReadOnly)
• Financial Inputs:
  • Original Amount & Currency (User Input).
  • Target Currency (ReadOnly, inherited from Deposit).
  • FX Rate (Input, visible only if currencies differ).
  • Converted Amount (Calculated, ReadOnly).
• Meta Data: Reference, Comment, Payment Type (check, wire, etc.).

Actions

• Locking: When a user opens a Receipt for Worksheets, the system "Locks" the record (lockedByUserId). This prevents concurrent editing. The UI must show a "Locked by [User]" banner if accessed by another.
• Void: Dedicated action available on Confirmed receipts.

3. Cash Worksheets

3.1 Process Description

The Worksheet is the core processing engine where a Confirmed Cash Receipt is allocated to specific Receivables. It provides a temporary staging area to "build" the application without permanently impacting the General Ledger until final approval.

3.2 Core Rules & Requirements

Lifecycle & State Machine

Status	Code	Description	Role Required
Draft	D	Worksheet created. Apps are being built. No GL impact.	Submitter
Submitted	S	Locked for review. Pending approval.	Submitter
Approved	A	Finalized. Real cash_receipt_application records created. GL Posted.	Approver
Rejected	D*	Transitions back to Draft. Logic: Keeps applications but unlocks for editing.	Approver

Application Logic

• Pending vs. Real: While in Draft/Submitted, applications exist only as pending items (JSONB or temp linkage). They do not reduce the Receivable Balance until Approval.
• Equality Rule:
  • Total Applications MUST equal Receipt Amount (within $0.005) to Submit or Approve.
  • Partial application of a Check is NOT allowed (the Check amount is fixed). If the check pays only part of an invoice, that is allowed, as long as the entire check is used.

Return / Reversal Workflow

Scenario: An Approved worksheet was incorrect (applied to wrong invoice). Action: Return WorksheetSystem Behavior:

1. Strict Audit: The original "Approved" worksheet remains in history (Status A), marked as Non-Current.
2. Reversal Entries: System creates Negative Applications linked to the original applications (reversalOfApplicationId). This "zeros out" the GL impact.
3. New Draft: A NEW Draft worksheet (replacedByWorksheetId) is automatically created.
   • Copy Logic: It pre-populates the new draft with the positive values from the old worksheet so the user can just fix the mistake (e.g., change Invoice A to Invoice B) without starting from scratch.
   • Read-Only Payouts: If 'Payouts' were involved and already cleared, they are copied as Read-Only to prevent double-paying.

3.3 User Interface Specifications

Worksheet View

• Top Panel:
  • Cash Receipt Summary (Amount, Payer, Reference).
  • Balance Indicator: Shows Unapplied Amount. Must be $0.00 to Submit.
• Applications Grid:
  • List of invoices being paid.
  • Editable Applied Amount column.
  • Row-Level Action Menu: (See Line-Item Actions below)
• Tabs/Sections:
  • Receivables: Billing items being paid
  • Client Ledger: On-account applications
  • Settlements: Agent/participant commission splits
  • Payouts: Outbound payments generated

Line-Item Actions (Row Action Menu)

Each row in the Applications Grid has an action menu with the following options:

Action	Description	Availability
Edit Amount	Change the applied amount inline	Draft only
Remove	Delete the application row	Draft only
Split Billing	Divide a single billing item application into multiple lines with different amounts. Opens SplitBillingDialog.	Draft only, Billing Items only
Create Settlement	Define how the cash from this receivable will be split among participants (agents). Opens SettlementDialog.	Draft only, when receivable has PAY components
Add Deduction	Add a deduction (short-pay reason) to this application. Opens DeductionDialog.	Draft only
View Details	Opens a read-only view of the application details	Always

Workflow Actions

• Submit: Enabled only when Balance = $0.
• Approve: Enabled only for Approver role (and Balance = $0).
• Reject: (If Submitted) Returns to Draft. Requires Comment.
• Abandon: (If Draft) Deletes the worksheet entirely. Releases lock on Cash Receipt.
• Return: (If Approved) Initiates the Reversal Workflow. Requires Reason.

4. Application Types

4.1 Billing Item Applications (Receivables)

An Application links a specific dollar amount from the Cash Receipt to a target Billing Item (Invoice).

• Validation: Applied Amount cannot exceed the Outstanding Balance of the invoice (unless explicitly allowed by configuration).
• Reversals: If a worksheet is Returned, the system creates a "Reversal Application" with a negative amount (-100.00).
• Currency Matching: Application currency must match the Cash Receipt currency.

4.2 Client Ledger Applications ("On Account")

A Client Ledger Application applies cash to an "On Account" balance rather than a specific invoice.

Client Ledger Type	Code	Description
On Account	OA	General prepayment or credit balance for a client
Loan	LOAN	Loan advance to a client

Use Cases:

• Client sends payment without specifying which invoice(s) to pay
• Prepayment before invoice is issued
• Loan disbursement that will later be offset against commissions

Required Fields:

• Client Ledger ID (references the on-account record)
• Applied Amount
• Deal ID (optional, for deal-specific OA balances)
• UTA Entity and Department (for GL routing)

4.3 Deductions ("Short Pays")

A Deduction explains why an invoice wasn't paid in full (e.g., "Diff/Damage", "Wire Fee").

• Relationship: Valid only as a child of an Application. You cannot have a "floating" deduction.
• Net Effect: Deductions reduce the Receivable Balance just like Cash.
  • Example: Invoice $1000. Cash Applied $950. Deduction $50 (Fee). -> Invoice Balance = $0.
• Data Requirement:
  • Billing Item Deduction Type (Reason Code)
  • Deduction Amount
  • Notes (Optional)

5. Settlements (Participant Payments)

5.1 Process Description

When a receivable is paid, some portion of the revenue may need to be paid out to participants (agents, talent, etc.). A Settlement defines how the cash from a specific receivable is split among participants.

5.2 Settlement Lifecycle

Status	Code	Description
Draft	D	Settlement being configured. Not yet finalized.
Submitted	S	Locked with the worksheet. Pending approval.
Approved	A	Finalized. Payout records created.

5.3 Core Rules

Settlement Creation

Settlements are created from the Worksheet when applying cash to a "PAY" type billing item detail (commission payable).

Settlement Defaults Calculation:

1. System resolves selected REV billing items to their parent Billing Items
2. Finds the sibling PAY Billing Item Details
3. Fetches Deal Party information (agent, commission %)
4. Pre-populates commission amounts based on deal terms

Settlement Items

Each settlement contains one or more Settlement Items (one per participant):

Field	Description
Payment Party ID	The agent/participant receiving payment
Payment Party Bank ID	Bank account for payment (optional)
Commission Flat Ind	If true, amount is flat; if false, calculated from percentage
Commission Percentage	e.g., 10%
Commission Amount	Calculated or entered flat amount
Calc Level Code	DNI (Do Not Ignore Deduction) or IGN (Ignore Deduction)
Payment Date	Target date for payment

5.4 User Interface

Settlement Dialog

• Opened via "Create Settlement" or "Edit Settlement" action on a receivable row
• Header: Shows Deal Name, Revenue Item, and total amounts
• Participants Grid: List of parties with editable commission fields
• Actions: Save, Cancel

6. Payouts & Payment Items

6.1 Process Description

A Payout is an intermediate record linking a Worksheet to a Payment Item. When a settlement is approved, the system generates Payment Items representing the actual outbound payments.

6.2 Payout Types

Type Code	Description
S	Settlement-based payout (from participant settlement items)
P	Pass-through payment
L	Loan payment
R	Refund

6.3 Payment Item Generation

On Worksheet Approval:

1. System iterates through all Settlement Items
2. For each item, creates a Payment Item record
3. Links via CashReceiptPayout join table

Payment Item Fields:

Field	Description
Payment Item Type	P, L, R, S, etc.
Payment Party ID	Who receives the payment
Payment Party Bank ID	Bank account details
Payment Item Amount	Amount to pay
Payment Item Currency	Currency of payment
Posting Status	U (Unposted), P (Posted), X (Skipped)
Clearing Status Ind	Whether payment has cleared the bank

6.4 Read-Only Payouts (Return Scenario)

When a worksheet is Returned after approval:

• Payouts that are NOT type S are copied to the new draft as Read-Only
• Payouts where Payment Clearing Status = TRUE are copied as Read-Only
• This prevents double-payment of already-cleared items

6.5 User Interface

Payouts Tab (Worksheet View)

• Displays all payouts linked to the worksheet
• Columns: Party, Amount, Type, Status, Payment Date
• Add Payout: Opens dialog to create ad-hoc payment (Pass-through, Refund, etc.)

Split Payment Item Dialog

• Allows splitting a single payment into multiple payments to different parties/banks

7. Data Requirements

7.1 Core Tables

Table	Purpose
deposit	Bank deposit container
cash_receipt	Individual payment within a deposit
cash_receipt_worksheet	Processing stage for cash application
cash_receipt_application	Line-item linking receipt to billing item
cash_receipt_application_deduction	Deduction against an application
cash_receipt_client_ledger	Application to on-account balance
cash_receipt_payout	Link between worksheet and payment item
participant_settlement	Settlement header
participant_settlement_item	Settlement line items per participant
payment_item	Outbound payment record
client_ledger	On-account balance tracking

8. Audit & History

Every action in the Cash Management module is immutable. Users cannot "edit" history; they can only append new transactions.

• Status History: The system tracks every status change (Draft -> Submitted -> Approved) with:

  • Timestamp
  • User
  • Action (e.g., "Submit")
  • Comment (Required for Rejection/Return)

• Worksheet Linking: Returned worksheets maintain links to their replacements via:

  • previousWorksheetId (on new draft)
  • replacedByWorksheetId (on returned original)

9. Gherkin Scenarios

Scenario: Deposit Control Total Validation

Feature: Deposit Control Total Management

  Scenario: Deposit becomes balanced when receipts match control total
    Given I have created a Deposit with a Gross Amount of $10,000
    And the Deposit currently has no Cash Receipts
    
    When I add a Cash Receipt of $6,000
    And I add a Cash Receipt of $4,000
    
    Then the Deposit status should show "Balanced"
    And the sum of Cash Receipts should equal $10,000

  Scenario: Deposit shows imbalance when receipts do not match
    Given I have a Deposit with a Gross Amount of $10,000
    And I have added Cash Receipts totaling $9,500
    
    Then the Deposit status should show "Unbalanced"
    And the variance should be $500

Scenario: Cash Receipt Confirmation and Locking

Feature: Cash Receipt Lifecycle

  Scenario: Confirm a draft cash receipt
    Given I have a Cash Receipt in "Draft" status
    And the receipt amount is $5,000
    
    When I click "Confirm"
    
    Then the Cash Receipt status should be "Confirmed"
    And the Amount field should be locked
    And the Currency field should be locked
    And the FX Rate field should be locked
    And the Reference field should remain editable

  Scenario: Attempt to edit locked fields on confirmed receipt
    Given I have a Cash Receipt in "Confirmed" status
    
    When I attempt to edit the Amount field
    
    Then the system should prevent the edit
    And display a message "Amount cannot be changed on a confirmed receipt"

Scenario: Worksheet Submission and Approval

Feature: Cash Worksheet Processing

  Scenario: Submit a balanced worksheet for approval
    Given I am a "Submitter" user
    And I have a Cash Worksheet in "Draft" status
    And the Receipt Amount is $1,000
    And Total Applications equal $1,000
    
    When I click "Submit"
    
    Then the Worksheet status should be "Submitted"
    And the applications should be locked for editing
    And the Approver should be notified

  Scenario: Approve a submitted worksheet
    Given I am an "Approver" user
    And I have a Cash Worksheet in "Submitted" status
    And Total Applications equal the Receipt Amount
    
    When I click "Approve"
    
    Then the Worksheet status should be "Approved"
    And cash_receipt_application records should be created
    And the Receivable balances should be reduced by the applied amounts
    And GL entries should be posted

  Scenario: Reject a submitted worksheet with comments
    Given I am an "Approver" user
    And I have a Cash Worksheet in "Submitted" status
    
    When I click "Reject"
    And I enter the comment "Applied to incorrect invoice"
    
    Then the Worksheet status should be "Draft"
    And the rejection reason should be recorded in the status history
    And the Submitter should be notified

Scenario: Worksheet Return and Reversal

Feature: Worksheet Return Workflow

  Scenario: Return an approved worksheet creates reversal
    Given I have a Cash Worksheet in "Approved" status
    And the worksheet has applications to Invoice "INV-001" for $1,000
    
    When I click "Return"
    And I enter the reason "Applied to wrong client invoice"
    
    Then the original worksheet should be marked as "Non-Current"
    And a reversal application of -$1,000 should be created for Invoice "INV-001"
    And a new Draft worksheet should be created
    And the new Draft should be pre-populated with the original application amounts
    And the Invoice "INV-001" balance should be restored

  Scenario: Read-only payouts on returned worksheet
    Given I have an Approved worksheet with a cleared Payout of $500
    
    When I return the worksheet
    
    Then the new Draft worksheet should include the $500 Payout as Read-Only
    And I should not be able to delete or modify the cleared Payout

Scenario: Settlement Processing

Feature: Participant Settlement

  Scenario: Create settlement for receivable with participant splits
    Given I have a Draft worksheet
    And I am applying $10,000 to a Billing Item with a 10% agent commission
    
    When I click "Create Settlement" on the receivable row
    
    Then the Settlement dialog should open
    And the Agent should be pre-populated from Deal Party information
    And the Commission Amount should default to $1,000 (10% of $10,000)

  Scenario: Settlement approval generates payment items
    Given I have an Approved worksheet
    And the worksheet has a Settlement with:
      | Agent         | Commission Amount |
      | John Smith    | $1,000            |
      | Jane Doe      | $500              |
    
    Then Payment Items should be created:
      | Payment Party | Amount  |
      | John Smith    | $1,000  |
      | Jane Doe      | $500    |
    And the Payment Items Posting Status should be "Unposted"

Scenario: Validation Failures

Feature: Worksheet Validation

  Scenario: Cannot submit unbalanced worksheet
    Given I have a Draft worksheet
    And the Receipt Amount is $1,000
    And Total Applications equal $800
    
    When I attempt to click "Submit"
    
    Then the Submit button should be disabled
    And the Unapplied Amount should show $200

  Scenario: Cannot apply more than receivable balance
    Given I have a Draft worksheet
    And I am applying cash to Invoice "INV-002" with an Outstanding Balance of $500
    
    When I attempt to enter an Applied Amount of $600
    
    Then the system should display an error "Applied amount cannot exceed outstanding balance"
    And the application should not be saved

  Scenario: Cannot void receipt with approved worksheet
    Given I have a Cash Receipt in "Confirmed" status
    And the receipt has an Approved worksheet
    
    When I attempt to void the Cash Receipt
    
    Then the system should prevent the void
    And display a message "Cannot void receipt with approved applications"

---

End of Functional Specification