CiC TEST — Advance RETURN flow (receipt↔advance fix)
Created: 2026-05-31  |  Custodian v7  (ALL in the Custodian PWA; no HR needed)

================ WHAT THIS TESTS ================
New in v7: when a custodian RECEIVES cash back from an employee/party/family,
they can apply it to one of THEIR outstanding advances. That must:
  - credit the receiving custodian's wallet exactly ONCE, and
  - reduce that advance's outstanding (no separate "receipt" double-count).
Also: the chooser must only offer advances the LOGGED-IN custodian gave
(the returned cash lands in their drawer), and over-application is blocked.

================ READ FIRST ================
  * FIRST: HARD-REFRESH the Custodian PWA (Ctrl/Cmd-Shift-R). The return chooser
    is v7 JS — confirm the cached SW is "custodian-v7" before starting.
  * UI only. DO NOT patch fetch(), call /db/rpc/* directly, or INSERT by hand.
    Only allowed non-UI action: the localStorage session bootstrap below.
  * If ANY step misbehaves, STOP and REPORT the exact error/request — do not
    work around it.

APP:  Custodian  https://srv1111289.hstgr.cloud/finance/custodian/
AUTH (DevTools console on srv1111289.hstgr.cloud, then reload):
  PRAMOD:  localStorage.setItem('lm360-session', JSON.stringify(
           {empId:'pramod',name:'Pramod Narang',role:'admin',loginAt:Date.now()}))
  HARISH:  localStorage.setItem('lm360-session', JSON.stringify(
           {empId:'harish',name:'Harish Kumar Lal',role:'admin',loginAt:Date.now()}))

================ FLOW ================
PART A — PRAMOD gives Mukesh an advance
  1. As PRAMOD. Note "My Balance" (P0; should be Rs.0).
  2. Transfer -> I'm Giving Funds -> Category: Employee -> Payee: "mukesh"
     -> Adv. against Salary -> Amount 5000 -> Cash
     -> Notes: CIC-TEST advance for return -> Record Transfer.
     EXPECT: "Recorded"; My Balance -> -Rs.5,000;
             Outstanding Advances shows Mukesh ... Rs.5,000.

PART B — PRAMOD records a partial cash RETURN  (the new flow)
  3. Transfer -> I'm Receiving Funds -> Category: Employee -> Payee: "mukesh" -> select.
     EXPECT: an "Apply this return to" section appears with:
               * a row "Adv. against Salary ... Rs.5,000" (selected by default)
               * a "General receipt" option
             (If you instead see only the plain "Receipt Purpose" box, the
              chooser failed to load — STOP and report.)
  4. OVER-APPLICATION guard: with the advance row selected, set Amount = 9999
     -> Record Transfer.
     EXPECT: BLOCKED with an error like "Return exceeds this advance's
             outstanding (Rs.5,000.00)". Nothing recorded.
  5. HAPPY PATH: set Amount = 2000, Mode = Cash -> Record Transfer.
     EXPECT: "Recorded" toast; back to Dashboard;
             My Balance = -Rs.3,000  (one credit: -5000 + 2000).

PART C — verify (as PRAMOD)
  6. Dashboard My Balance = -Rs.3,000.
  7. Ledger -> Advances tab: Mukesh advance = "Part. settled", remaining Rs.3,000.
  8. Ledger -> Account tab: a "+Rs.2,000" Recovery/settlement line is present and
     the running balance reads -Rs.3,000 (i.e. ledger ties to the wallet).
     There should be NO separate inward "Receipt" entry for this Rs.2,000
     (it is recorded as a settlement, not a receipt).

PART D — giver-only invariant  (as HARISH)
  9. Bootstrap HARISH, reload Custodian. Transfer -> I'm Receiving Funds ->
     Employee -> "mukesh" -> select.
     EXPECT: NO "Apply this return to" chooser for Pramod's advance (Harish did
             not give it) — only the plain "Receipt Purpose" box shows.
             This proves a return can only be recorded by the advance's giver.
     Do NOT submit anything as Harish.

================ PASS CRITERIA ================
  [ ] Receiving + Employee + Mukesh shows the advance chooser (Part B/3)
  [ ] Over-application (9999) is blocked (Part B/4)
  [ ] Rs.2,000 return -> Pramod wallet -3,000 (credited ONCE) (B/5, C/6)
  [ ] Advance now "Part. settled", outstanding Rs.3,000 (C/7)
  [ ] Account-tab running balance = wallet (-3,000); shown as settlement not
      a receipt (C/8)
  [ ] Harish does NOT see Pramod's advance in the chooser (D/9)

================ PREREQUISITE STATE (verified 2026-05-31) ================
Clean baseline: Mukesh 0 advances; Pramod wallet 0; Harish wallet -500 (real,
leave it). So Part A starts from P0 = 0.

================ CLEANUP (after the run) ================
NOTE: +3000 assumes the return COMPLETED (wallet -3000). If the run stops after
Part A (advance given, no return), use + 5000 instead.

  docker exec -i postgres psql -U lmadmin -d lm360 <<'EOSQL'
  BEGIN;
  DELETE FROM custodian.advance_settlements
    WHERE advance_id IN (SELECT advance_id FROM custodian.advances
                         WHERE to_employee_id='emp-mukesh'
                           AND purpose='CIC-TEST advance for return');
  DELETE FROM custodian.advances
    WHERE to_employee_id='emp-mukesh' AND purpose='CIC-TEST advance for return';
  UPDATE custodian.wallets SET balance = balance + 3000 WHERE custodian_id='pramod';
  SELECT custodian_id, balance FROM custodian.wallets WHERE custodian_id IN ('pramod','harish') ORDER BY custodian_id;
  COMMIT;
  EOSQL