# FundCustodian UX Walkthrough — CiC Prompt

**URL**: https://srv1111289.hstgr.cloud/finance/custodian/

**Pre-condition**: Test data from `finance/custodian/test_data_custodian.sql` is loaded (wipe + reload).

---

## Background (read before testing)

FundCustodian is a mini-PWA for tracking internal cash flows between custodians. Three custodian types are live in test data:

| Person | Role | Expected balance | Notes |
|--------|------|-----------------|-------|
| **pramod** | Admin + Primary | ₹-43,767.19 | Negative because he's the source of all funds |
| **harish** | Admin + Secondary | ₹-6,000.00 | Has 2 PENDING transfers awaiting acceptance |
| **shambhu** | Non-admin + Secondary | ₹-2,800.00 | Has 3 outstanding advances + 1 pending (sent by shambhu) |
| **gurpreet** | Non-admin + Secondary | ₹+216.44 | Small positive balance |
| **mukesh** | NOT a custodian | n/a | Should see Access Restricted screen |

To log in as each person: Open Hub at `/hub/`, log in with their PIN (or for testing, use localStorage injection: `localStorage.setItem('lm360-session', JSON.stringify({empId:'pramod',name:'Pramod Narang',role:'admin',loginAt:Date.now()}))` in browser console, then navigate to the URL).

---

## Persona 1 — mukesh (Non-custodian, should be locked out)

1. Log in as mukesh (PIN 1234 via Hub, then navigate to `/finance/custodian/`)
2. **Expected**: "Access Restricted" full-screen message with 🔒 icon and "← Back to Hub" button.
3. **Check**: Does the button actually go back to `/hub/`? Does the page look clean on mobile?
4. **Verify**: No app content leaks before the lockout renders (timing issue check).

---

## Persona 2 — harish (Admin, 2 pending transfers)

1. Log in as harish, navigate to `/finance/custodian/`
2. **Dashboard — pending banner**:
   - Should show orange/amber banner: "🔔 2 pending transfers need your confirmation"
   - Two entries: Shambhu (₹3,000) and Gurpreet (₹800)
   - Each entry has ✓ Accept and ✕ Reject buttons
   - **Check**: Does the amount look right? Is the date shown correctly?
   - **Check**: What happens if you tap Accept on Shambhu's ₹3,000 transfer? Does the banner update to 1 pending? Does the balance card change?

3. **Dashboard — admin balance grid**:
   - Below pending banner, check "All Custodian Balances" section
   - Should show 4 tiles: Pramod (Primary badge, large negative), Harish, Shambhu, Gurpreet
   - **Check**: Are negative balances shown in red? Is the Primary badge amber/yellow on Pramod?

4. **Reject flow**:
   - Tap "✕ Reject" on Gurpreet's ₹800 transfer
   - Rejection modal should slide up from bottom
   - Type a reason or leave blank, tap Reject
   - **Check**: Does the modal close? Toast appear? Pending banner count drop?

5. **⚙ Manage button** (header, top right):
   - Tap the ⚙ icon — should open Manage Custodians screen
   - Should list all 4 custodians with their balances and type badges
   - Add Custodian form: try submitting empty ID or empty name — check error toasts
   - **Check**: "← Back to Dashboard" button works

6. **Ledger → Transfers**:
   - Tap 📒 Ledger in bottom nav
   - Custodian filter dropdown should appear (harish is admin)
   - Select "All custodians" — should show 15 transfers
   - Look for all status badges: ⏳ Pending, ✓ Auto-accepted, ✓ Accepted, ✕ Rejected
   - **Check**: The long notes on T11 (gurpreet→harish, field activation notes) — does it truncate cleanly?
   - **Check**: The decimal amount T5 (₹1,234.56) renders correctly

7. **Ledger → Advances**:
   - Switch to Advances tab
   - Filter by "Shambhu" — should show 3 advances (Mukesh, Sachin, Ranjit Singh)
   - **Check**: Sachin row shows "Part. settled" badge + outstanding ₹1,500.00
   - Filter by "All custodians" — should show 9 advances
   - **Check**: Narender row shows "Settled" badge (A3)
   - **Check**: Ranjit Singh (Contract) renders in parentheses correctly

---

## Persona 3 — shambhu (Non-admin, secondary custodian)

1. Log in as shambhu, navigate to `/finance/custodian/`
2. **Dashboard**:
   - Header shows "Shambhu" not "Fund Custodian"
   - Balance ₹-2,800.00 should be in RED (negative)
   - **Check**: Is there a pending banner? (There should NOT be — shambhu has no pending inbound transfers in test data. He *sent* T14 which is pending for harish, but that's not inbound to shambhu.)
   - Outstanding advances section should show Mukesh (₹5,000), Sachin (₹1,500 outstanding), Ranjit Singh (₹800)
   - **Check**: Sachin row shows "Part. settled" badge with ₹1,500 outstanding
   - **Check**: No "All Custodian Balances" grid (non-admin)
   - **Check**: No ⚙ manage button in header

3. **Transfer form** (💸 tab):
   - Tap 💸 Transfer in bottom nav
   - Default: "I'm Giving Funds" selected, Cash mode, "pending info" notice visible
   - "Other Custodian" dropdown should show pramod, harish, gurpreet — but NOT shambhu
   - Switch to "I'm Receiving Funds" — pending notice should disappear
   - Switch to UPI mode — Reference field should appear
   - Switch back to Cash — Reference field should disappear
   - Try to submit empty form — check error toasts in sequence

4. **Advance form** (💰 tab):
   - Tap 💰 Advance
   - Employee dropdown includes all employees + "Other (enter name)"
   - Select "Other (enter name)" — manual name field appears
   - Select "Mukesh" again — manual name field disappears
   - Try IMPS mode — reference field appears
   - Try to submit empty — check error toast

5. **Ledger** (📒 tab):
   - Transfers tab: should show only shambhu's transfers (no admin filter dropdown)
   - Should see T2, T4, T6, T8, T10, T12, T14 entries
   - T12 (shambhu→harish ₹7,500, REJECTED) should show ✕ Rejected badge + rejection reason
   - T14 (shambhu→harish ₹3,000, PENDING) should show ⏳ Pending badge
   - Advances tab: shambhu's advances — Mukesh (outstanding), Sachin (part. settled), Ranjit Singh

---

## Persona 4 — gurpreet (Non-admin, low activity, small positive balance)

1. Log in as gurpreet, navigate to `/finance/custodian/`
2. **Dashboard**:
   - Balance ₹+216.44 — should be in GREEN (positive)
   - No pending banner (gurpreet has T15 pending to harish — that's outbound, not inbound)
   - Outstanding advances: only ashok ₹750
   - Recent transfers: should show gurpreet's transfers

3. **Key edge case** — verify decimal amount display:
   - In Ledger → Transfers, find T5 (gurpreet→pramod ₹1,234.56)
   - Check that ₹1,234.56 renders with the decimal correctly (not ₹1235 or truncated)

4. **Bottom nav all tabs** — tap through each, verify screens load without errors

---

## Persona 5 — pramod (Admin + Primary, deeply negative balance)

1. Log in as pramod, navigate to `/finance/custodian/`
2. **Dashboard**:
   - Balance ₹-43,767.19 — should be in RED, large number formatted with commas
   - Check: does ₹43,767.19 display correctly (Indian number format)?
   - All custodian balances grid visible
   - Outstanding advances: Umashankar (₹20,000), Rakesh (₹6,000 outstanding of ₹10,000), Ramesh Thakur Vendor (₹5,000.75)
   - Check: Rakesh row shows "Part. settled" with ₹6,000 outstanding
   - Check: Ramesh Thakur (Vendor) name with parentheses renders cleanly

3. **Dashboard "View all →" link**:
   - Tap "View all →" next to "Recent Transfers" — should navigate to Ledger screen
   - Verify all filters show pramod-scoped transfers

4. **Advance for Vendor (edge case)**:
   - In Ledger → Advances, find "Ramesh Thakur (Vendor)" row — decimal ₹5,000.75
   - Verify decimal renders correctly

---

## Cross-cutting UX checks (note any issues for each persona)

| Check | Expected |
|-------|----------|
| Hub button on every screen | Visible always, navigates to `/hub/` |
| Toast messages | Slide up from bottom, auto-dismiss ~3s, green for success, red for error |
| Empty states | Descriptive icon + text (not blank area) |
| Loading state | Spinner visible while API loads, not just blank |
| App update banner | Should NOT appear on fresh load (no version change) |
| Scroll to top on screen switch | Each screen should scroll to top on nav tap |
| Date format | `DD Mon YYYY` format (e.g., 20 May 2026), not ISO |
| Amount format | Indian format: ₹1,00,000.00 (not ₹100000) |
| Long notes truncation | Ellipsis in ledger rows, readable in tooltip or expand |