Bank Receivables

What This System Does

The Bank Receivables module provides a controlled, auditable interface for recording and approving bank receivable entries. Each entry captures a title, narration, entry date, credit value, and optional debit value. Entries move through a mandatory three-stage approval pipeline before being considered final.

The frontend page (bank-receivables) fetches all data from receivables_api via standard fetch() calls. All filtering, sorting, and pagination are performed server-side in MySQL — the client only holds the current page of results. A parallel immutable audit table (bank_receivables_audit) records every status change permanently.

Approval Workflow

Every receivable entry follows a strict four-state lifecycle enforced at the API level. Status transitions are guarded — the server rejects any out-of-order move and records each valid transition in the audit log.

Page Structure

The page is built from six logical sections inside the main content area, plus four modal overlays that sit at the end of the document outside the layout flow.

API Endpoints

All requests go to receivables_api. Every response uses the standard envelope {"success": bool, "message": "...", "data": ...}. The API always returns JSON — PHP errors are caught by the global exception handler and converted to JSON 500 responses.

A GET List — Query Parameters

Stats Dashboard

Five KPI cards are displayed above the toolbar. Their values come from the stats key of every list API response. The renderStats() function updates them after each load() call — no separate API request is made.

The Approved card additionally shows the total credit value of all approved entries via stats.approved_credit_total, formatted with fMoneyShort() (e.g. ₦142.6M credited). The filter pill counts in the toolbar are also updated from the same stats object on every load.

Entry Listing

The listing renders from the current page of results (viewList). Identical data is written into both the desktop HTML table and the mobile card container on every render() call.

A Table Columns

B Action Buttons per Status

C Skeleton + Empty + Error States

While a fetch is in progress, showSkeleton() replaces the table body with three shimmer rows using the .sk animation class. A _loading flag prevents overlapping fetches. If the response is empty the table renders a centred empty-state message. If the fetch fails, a dismissible error banner appears above the table with a Retry button wired to load().

Server-side Pagination

All pagination is performed in SQL at the API level. The client only receives the current page of rows. On every filter, search, or page change the full load() cycle runs with the appropriate page and per_page parameters.

A Smart Page Range

The desktop pagination bar renders a smart page-number range with ellipsis via buildPageRange(). It always shows the first page, the last page, the current page, and one page either side of the current — with … gaps where the sequence is non-contiguous.

// 20 pages, current = 1  →  [1, 2, '...', 20]
// 20 pages, current = 10 →  [1, '...', 9, 10, 11, '...', 20]
// 20 pages, current = 20 →  [1, '...', 19, 20]
// 5 pages,  current = 3  →  [1, 2, 3, 4, 5]  (no ellipsis needed)

B Pagination State Variables

C Pagination API Response Keys

{
  "total":        150,   // total matching rows (not just this page)
  "per_page":     20,
  "current_page": 3,
  "last_page":    8,
  "from":         41,    // 1-based row number of first result on this page
  "to":           60,    // 1-based row number of last result on this page
  "has_prev":     true,
  "has_next":     true
}

Add / Edit Modal

The same #formModal is reused for both create and update. The modal title ("New Entry" vs "Edit Entry") and the editId variable (null for add, integer for edit) distinguish the mode. Saving calls saveEntry() which POSTs or PUTs based on editId.

A Form Fields

B UID Generation

function genUID() {
  const yr  = new Date().getFullYear();
  const ts  = Date.now().toString(36).toUpperCase().slice(-4);
  const rnd = String(Math.floor(Math.random() * 9000) + 1000);
  return `RCV-${yr}-${ts}${rnd}`;
}

The server independently regenerates the UID if the client-provided one already exists (generateUID() in PHP). The client-side function is for display preview only — the authoritative UID is always confirmed by the server's 201 response.

View Modal

Opens when the eye icon is clicked. If the entry is in viewList (current page) it renders immediately from the in-memory array — no API call. If for any reason it isn't found locally (e.g. navigating directly), openView() falls back to a GET ?id=N request which also returns the full audit trail in the trail array.

The approval trail renders all rows from bank_receivables_audit for this entry in chronological order. Each trail item shows the action type (created / edited / posted / approved / rejected / deleted), the actor's name, and the timestamp. For rejections the rejection reason is shown beneath the meta line.

Workflow Confirm Modals

Three separate confirm dialogs handle the workflow transitions. Each shows a preview of the target entry and a confirmation message before the action is sent to the API.

Database Schema

Two tables power the system: the main entries table and the immutable audit log.

A bank_receivables

B bank_receivables_audit

API Payload

A Create Entry (POST)

{
  "uid":           "RCV-2025-XK3F1284",  // optional — server regenerates on collision
  "title":         "IPPIS Collections March",
  "narration":     "Bank statement matching entry...",
  "entry_date":    "2025-03-15",             // YYYY-MM-DD required
  "credit_value":  4250000.00,              // must be > 0
  "debit_value":   320000.00                // optional, defaults to 0
  // company_fk + created_by + status set server-side — never sent by client
}

B Update Entry (PUT)

Identical body to POST. URL must include ?id=N. Only draft and rejected entries can be updated — any other status returns 409 Conflict.

C Reject Entry

{
  "reason": "Credit value does not match bank statement. Please verify figure."
}

D Payload Field Reference

API Responses

A List Response

{
  "success": true,
  "data": [
    {
      "id": 42, "uid": "RCV-2025-XK3F1284", "title": "IPPIS Collections March",
      "narration": "...", "entry_date": "2025-03-15",
      "credit_value": "4250000.00", "debit_value": "320000.00",
      "net_value": "3930000.00",   // computed in SQL
      "status": "draft",
      "created_by": 7, "created_by_name": "Amaka Okonkwo", "created_at": "2025-03-15 09:12:00",
      "posted_by": null, "posted_by_name": null, "posted_at": null,
      "approved_by": null, "approved_by_name": null, "approved_at": null,
      "reject_reason": null, "updated_at": "2025-03-15 09:12:00"
    }
  ],
  "pagination": { "total": 150, "per_page": 20, "current_page": 1,
                    "last_page": 8, "from": 1, "to": 20, "has_prev": false, "has_next": true },
  "stats": { "total": 47, "draft": 12, "posted": 8, "approved": 24,
              "rejected": 3, "approved_credit_total": "142600000.00" }
}

B HTTP Status Codes

JavaScript State Variables

Functions

Validation Rules

Client-side validation runs inside saveEntry() before the API call. The server independently re-validates all fields and returns 422 if any are missing or malformed.

A Form Validation

B Reject Validation

Error Handling

Both the PHP API and the JavaScript frontend have layered error handling to ensure failures are always communicated clearly, never silently swallowed, and never corrupt the UI state.

A API Layer (PHP)

B Frontend Layer (JavaScript)