Field	Value
BA in Charge	Trang Nguyen
Date Created	2026-08-12
Version	v1.1
Document References	RFQ_ Website and Dashboard Implementation V7.pdf (§Part C: Trader Dashboard Implementation, Key Features) · Zapier Integration V7.pdf (§3.4 Table F — Defense Configuration Matrix, L787-793 · Table A/B — Per-Level`Profit_Target`/`Market_Loss_When_Stopped`, L2952-3005) · `docs/BA/UC_4.1-4.17/dashboard_live/UC_4.12.2/QnA_init_docs.md` (QN-4.12.2-01..04) · UC_4.8.1 (SIM sibling — dial formula reused 100%)

UC_4.12.2 — PnL Gauge (LIVE)

1. Overview

Field	Content
ID	UC_4.12.2
Use Case	PnL Gauge (LIVE)
Description	The same streaming risk/reward dial widget as the SIM sibling (UC_4.8.1) — spanning from the trader's Hard Stop Loss threshold (left end) to their Profit Target (right end), with a live needle at current Net PnL — reused 100% verbatim in formula and endpoint (Ref: QN-4.12.2-01); the only difference is that the two dial-end values are looked up per the trader's current LIVE level (1-24, Table A Forex / Table B Futures) instead of a fixed SIM value. Requires the same 4 visual states as SIM (Starting point, Drawdown defense enabled, Breached/Account Disabled, Level Up) — but unlike SIM, "Drawdown defense enabled" is a real, reachable state on LIVE (Level 9+, after the Defense Protocol activates), and when it activates the dial's left/right ends are recalculated to Defense-specific values and displayed throughout the 48h cooling-off period (Ref: BR_4.12.2.3). This UC owns only the gauge's display behavior; the Defense Protocol's business logic (trigger condition, 48h cooling-off timer, unlock flow) is owned entirely by UC_4.15.4 — Defense Protocol (not yet documented in this repo) — not repeated here (Ref: QN-4.12.2-03).
Zapier Flow	—
Zapier Table	Table A (Forex per-level) · Table B (Futures per-level) · Table F (Defense Configuration Matrix)
3rd Party	—

References/Wireframe/Stage 2/Dashboard/Dashboard.png PnL Gauge, "Starting point" state (shared visual reference with SIM). References/Wireframe/Stage 2/Dashboard/Level Up.png PnL Gauge, "Level Up" state (shared visual reference with SIM). References/Wireframe/Stage 2/Dashboard/Drawdown defense (level 9+).png PnL Gauge, "Drawdown defense enabled" state — this is the LIVE-only reachable state referenced as N/A on the SIM SRS (Ref: UC_4.8.1 BR_4.8.1.1); on this UC it is a real, fully-reachable state. References/Wireframe/Stage 2/Dashboard/Dashboard - Hard breach (T+0 - T+10).png PnL Gauge, "Breached (Account Disabled)" state (shared visual reference with SIM).

🎬 Motion reference: PnL Gauge state-transition animations (Google Drive) (shared with SIM). 🎬 Motion reference — Hard Breach state: PnL Gauge motion status at Hard Breach (Google Drive) (Source: client-supplied link, relayed by user, BA session, 2026-08-19).

2. Trigger

The screen hosting this widget (Ref: UC_4.1.1) has rendered.
An ACCOUNT_METRICS WebSocket event arrives while the user is on the screen (Ref: BR_4.12.2.2).
A LEVEL_STOP_BREACH or LEVEL_PROMOTION WebSocket event arrives (Ref: BR_4.12.2.1).
A Defense Protocol activation event arrives, owned by UC_4.15.4 (not yet documented in this repo) (Ref: BR_4.12.2.3).

3. Pre-conditions

User is on the screen (Ref: UC_4.1.1 §1 Overview) with an active LIVE account.

4. Post-conditions

The dial displays the trader's current risk/reward position (Hard Stop Loss ↔ Profit Target for their current level, needle at current Net PnL) and continues to update live for the remainder of the session, including correctly reflecting the Defense Protocol state — scale ends recalculated (New_Limit) immediately server-side, but displayed only after the 48h cooling-off countdown completes (Ref: BR_4.12.2.3); if the account becomes frosted/Hard Breached, the dial freezes at its last-shown data instead of continuing to update (Ref: BR_4.12.2.3).

5. Basic Flow

On screen load, frontend calls the same endpoint as SIM to obtain the trader's Market_Loss_When_Stopped and Profit_Target — for LIVE, these values are looked up for the trader's current level (Table A/B) rather than a fixed value (Ref: BR_4.12.2.2).
Frontend renders the dial scale: left end (minimum) = -Market_Loss_When_Stopped, right end (maximum) = +Profit_Target, both per current level (Ref: BR_4.12.2.2).
Frontend subscribes to the ACCOUNT_METRICS WebSocket channel; on each update, the needle position and the live dollar value below it are set to the current Net PnL (Unrealized + Realized) — same mechanism as SIM (Ref: UC_4.8.1 BR_4.8.1.3).

State-transition handling for LEVEL_STOP_BREACH, LEVEL_PROMOTION, and Defense Protocol activation events is governed by Business Rules, not repeated here (Ref: BR_4.12.2.1, BR_4.12.2.3, BR_4.12.2.4).

6. Alternative Flow

None beyond the state-transition boundary cases covered in Basic Flow steps 4-6.

7. Exceptional Flow

WebSocket/API connection drops: the dial retains its last-known values (stale data) while the client applies exponential backoff and automatically reconnects, per CR-14 — same as SIM.
Defense Protocol trigger/cooling-off/unlock mechanics: out of scope for this UC; owned entirely by UC_4.15.4 (not yet documented in this repo) — not repeated here (Ref: BR_4.12.2.3).

8. Business Rules

BR_4.12.2.1: Four Dial States — All Reachable on LIVE

The dial requires frontend state management for the same 4 visual states as SIM: Starting point, Drawdown defense enabled, Breached (Account Disabled), and Level Up (Ref: UC_4.8.1 BR_4.8.1.1). Unlike SIM, where "Drawdown defense enabled" never triggers, all 4 states are reachable on LIVE — the Defense Protocol applies to Level 9+ traders per Table F (Defense Configuration Matrix).

BR_4.12.2.2: Dial Scale — Same Formula as SIM, Per-Level Values

The dial scale uses the exact same formula and endpoint mechanism confirmed for SIM (UC_4.8.1 BR_4.8.1.2):

Left end (minimum): −Market_Loss_When_Stopped, looked up for the trader's current level (Table A Forex / Table B Futures).
Right end (maximum): +Profit_Target, looked up for the trader's current level.

Arc rendering/scaling mechanics for these two endpoints (physical zero anchor, dual-domain needle mapping, tick marks, absolute end labels) — same rule as SIM, reused verbatim — are defined in UC_4.8.1 BR_4.8.1.6, not repeated here. This applies to the currently-displayed scale ends regardless of state — pre-Defense per-level values, or the recalculated New_Limit Defense values once displayed (Ref: BR_4.12.2.3).

BR_4.12.2.3: Drawdown Defense Enabled State — `New_Limit` Recalculated Immediately, Display Deferred Until 48h Countdown Completes

Trigger: Defense Protocol activates — current level 9+ (per Table F) and Defense_Used = False.
New_Limit (dial's left/right scale ends, replacing Market_Loss_When_Stopped/Profit_Target): recalculated immediately, from Defense-specific values (Defense_Profit_Target_Percent/Defense_Stop_Loss_Percent applied against the level's base values per Table F, e.g. New_Limit = Floor(Original_Limit × Defense_Notional_Multiplier)).
Display timing: the dial keeps rendering the pre-Defense scale ends throughout the 48h cooling-off period; it switches over to New_Limit only once the 48h countdown completes — data (recalculated immediately) and display (deferred) are no longer updated in lockstep for this transition.

Frosted state — screen freezes at last data: if the account transitions to a "frosted" state (Hard Breach lockout, UC_4.15.2) — whether from this same drawdown threshold or from Stagnation (UC_4.12.1 BR_4.12.1.3) — the dial does not continue updating; it retains and displays whatever data (scale ends, needle position, Net PnL) was last shown at the exact moment the account became frosted or Hard Breached, for the duration of the frosted/blurred state (Ref: UC_4.15.2 §4 Post-conditions — static snapshot at failure_timestamp, not live data, not reset to blank).

The trigger condition, 48h cooling-off timer, and unlock flow for the Defense state are owned entirely by UC_4.15.4 (not yet documented in this repo) — this UC only owns the gauge's display reaction to that state, including the deferred scale switch-over and the frosted-state freeze. (Source: QN-4.12.2-03; display-timing update Source: user/BA directive, 2026-08-19)

BR_4.12.2.4: State Labels (Left & Right) — Text Per State, Level Band, and Defense-Credit Condition

The dial shows two 2-line labels — left and right — that change per dial state (Ref: BR_4.12.2.1) and, for the Defense-related states, per two further conditions: the trader's level band (9–17 vs. 18+) and whether they currently hold an unused Defense credit (Defense_Used = False) or have already spent it (Defense_Used = True)

#	State	Condition	Left — Text / Subtext	Right — Text / Subtext
1	Starting point (Defense not yet unlocked)	Current level< 9	`"Stop Loss Breach"` / `"Defense unlocked at Lvl. 9"`	`"Promotion: Level [N]"` / `"Est. Bonus $[amount]"`
2	Starting point — Drawdown Defense Enabled (initial)	Current level≥ 9 (Level 9+) AND`Defense_Used = False` (trader holds an unused Defense credit)	`"Drawdown Defense Enabled"` / `"Floor Locked"`	`"Promotion: Level [N]"` / `"Est. Bonus $[amount]"`
3	Breached (Drawdown Defense Enabled)	Needle hits the level's max-loss end while state 2's condition holds. Triggers the Defense Protocol modal + 48h cooling-off countdown (Ref:UC_4.15.4)	`"Breached (Drawdown Defense Enabled)"` / live 48h countdown (mobile: `"Drawdown Defense Enabled"` / hh:mm only, no seconds)	`"Promotion: Level [N]"` / `"Est. Bonus $[amount]"`
4	Drawdown Defense Enabled — PIP (recovery)	48h countdown has completed; dial now displays the recalculated`New_Limit` scale ends (Ref: BR_4.12.2.3); `Defense_Used = True` (credit already spent, no protection remaining)	Levels 9–17: `"Stop Loss Breach"` / `"Defence Recharges after 2 Promotions"`. Levels 18+: `"Stop Loss Breach"` / `"Defence Recharges after 6 Months"`	`"Required PIP Target"` / `"Restore Level [X] status"` — `[X]` is the trader's level as of the Defense trigger (the level being restored, not a level-up)
5	PIP Target Reached	Needle hits the recalculated (reduced) profit target while in state 4	unchanged from state 4	`"PIP Target Reached"` / `"Returning to Level [X]"`
6a	Stop Loss Breached (Account Disabled) — no Defense credit spent	Account is disabled while`Defense_Used = False` — either current level < 9, or Level 9+ with an unused Defense credit (disabled by a mechanism other than this dial's own max-loss end, e.g. Stagnation Hard Breach, UC_4.12.1 BR_4.12.1.3)	`"Stop Loss Breached"` / `"Account Disabled"`	unchanged from state 1 —`"Promotion: Level [N]"` / `"Est. Bonus $[amount]"`
6b	Stop Loss Breached (Account Disabled) — Defense credit already spent	Needle hits the max-loss end (recalculated`New_Limit`) while in state 4, i.e. `Defense_Used = True` — no credit left to re-trigger protection	`"Stop Loss Breached"` / `"Account Disabled"`	unchanged from state 4 —`"Required PIP Target"` / `"Restore Level [X] status"`

9. Screen Description

No.	Field Name	Field Type	Displaying rule / Behaviour rule
1	PnL dial	Label	Displaying rule:- Gauge scale from `−Market_Loss_When_Stopped` (left) to `+Profit_Target` (right), both per current level, full precision (no abbreviation). 4 states per BR_4.12.2.1; on "Drawdown defense enabled", `New_Limit` is recalculated immediately but the scale display keeps showing the pre-Defense ends until the 48h cooling-off countdown completes, then switches to `New_Limit` (Ref: BR_4.12.2.3). On frosted/Hard Breach, the dial freezes at its last-shown data (Ref: BR_4.12.2.3). Ref: BR_4.12.2.2. Physical `$0` anchor + color split, dual-domain needle mapping, dynamic tick rendering (4 → 3 per side), absolute end-label bounds — same rule as SIM, Ref: UC_4.8.1 BR_4.8.1.6.Behaviour rule:- Read-only. State transitions are animated — Ref: motion reference, Section 1, incl. Hard Breach motion status (Google Drive).
2	Needle	Label	Displaying rule:- Position tracks current Net PnL along the dial scale, using the two separate interpolation domains (negative half / positive half). Same mechanism as SIM — Ref: UC_4.8.1 BR_4.8.1.6.Behaviour rule:- Read-only. Updates live via `ACCOUNT_METRICS`.
3	Net PnL value	Label	Displaying rule:- Live dollar amount below the needle, equal to Unrealized + Realized PnL. Full precision (whole dollars, comma separators, no abbreviation), dynamic font scaling down to 50% on overflow — same rule as SIM, Ref: UC_4.8.1 BR_4.8.1.6 (exception to CR-11's 2-decimal rule; CR-11's separator/tooltip rules still apply).Behaviour rule:- Read-only. Updates live via `ACCOUNT_METRICS`.
4	State label (left)	Label	Displaying rule:- 2-line label, text per state per BR_4.12.2.4. Mobile/small-screen variant for the "Breached (Drawdown Defense Enabled)" state shows hours-and-minutes-only countdown (Ref: BR_4.12.2.4). Live countdown value itself is owned by UC_4.15.4, not repeated here.
5	State label (right)	Label	Displaying rule:- 2-line label, content per state per BR_4.12.2.4. Next-level number and bonus amount (states 1-2) are direct lookups from Table A/B (per current asset class and current level) for the next level — displayed as-is, no tooltip shown for either value. Monetary value display for the bonus line: Ref: CR-11. PIP-recovery states (4-5) show target/restore text instead of promotion text. On account termination (states 6a/6b), the right label does not change further — it freezes at whichever of the above it was last showing — Ref: BR_4.12.2.4.

Changelog

Date	Version	Updated item	Before	After	Notes
2026-08-31	v1 → v1.1	BR_4.12.2.2 and Screen Description rows 1-3 — cross-ref new arc-rendering/center-value rule (defined once, on the SIM sibling)	Dial scale/needle/center-value rendering mechanics (zero anchor, dual-domain interpolation, tick rendering, abbreviation, font scaling) were unspecified on both SIM and LIVE.	Cross-referenced UC_4.8.1 BR_4.8.1.6 (rule authored there, reused verbatim here — consistent with this UC's existing "dial formula reused 100% from SIM" pattern): full-precision whole-dollar center value with CR-11 decimal-rule exception, dynamic font scaling to a 50% floor, physical `$0` anchor + color split independent of the two endpoints' asymmetric magnitudes, dual-domain needle interpolation, dynamic tick rendering (4 → 3 per side), absolute end-label bounds. Applies to whichever scale ends are currently displayed (pre-Defense per-level values, or post-cooling-off `New_Limit` — Ref: BR_4.12.2.3).	Source: Client description, relayed by user, BA session, 2026-08-31.

SRS: UC_4.12.2 — PnL Gauge (LIVE)