102: EMC Perps: show liquidation risk and account health

2026-10-25 16:35:17 +01:00
parent 2f30712004
commit b4c7fe87d9
30 changed files with 1070 additions and 48 deletions
@@ -0,0 +1,40 @@
+## MODIFIED Requirements
+
+### Requirement: Perps overview displays a collapsible position hierarchy
+The Perps tab SHALL display Position, Risk, Direction, Margin, Collateral, Leverage, Exposure, Value, uPnL and TWAP beneath the visible Perpetual Contracts root. Isolated hierarchy SHALL be wallet → venue → position; each Phoenix Cross account SHALL add a Cross group above its positions. Groups SHALL show applicable totals and risk summaries, leave direction/aggregate ratios and TWAP blank, and be expanded by default.
+
+#### Scenario: Open either environment's Perps tab
+- **WHEN** the owner opens Perps in Production or Test
+- **THEN** all ten columns and the account-aware hierarchy are available with Risk near the position name
+
+#### Scenario: Collapse and expand groups
+- **WHEN** the owner collapses a wallet, venue or Cross account
+- **THEN** the group still shows its worst known risk and incomplete-observation counts without changing totals
+
+### Requirement: Polling preserves Perps view state
+The Perps table SHALL retain matching wallet, venue and position identities across snapshots. Repeated unchanged snapshots SHALL leave retained rows, expansion, selection and formatting untouched except when risk freshness changes, without flicker or table rebuild. New groups SHALL be expanded by default, and added or removed positions SHALL be reconciled by identity without resetting retained groups.
+
+#### Scenario: Poll unchanged positions
+- **WHEN** a user collapses a group or selects a position and repeated snapshots are unchanged
+- **THEN** the same rows remain with the same expansion and selection
+- **AND** only a changed risk freshness indication requires a row-value update
+
+## ADDED Requirements
+
+### Requirement: Risk cells distinguish distance and account health
+Risk cells SHALL show neutral isolated distance and red reached/crossed boundaries, while Phoenix tiers use their own severity colors. Cross account cells SHALL label MM utilization; their children SHALL indicate Shared scope. Missing risk SHALL be Unknown. Text, indicators and tooltips SHALL explain units, reference/liquidation prices, account scope, thresholds, original observation time and limitations without changing direction backgrounds.
+
+#### Scenario: Safe account without liquidation estimate
+- **WHEN** Phoenix reports a valid Safe account but a nonpositive liquidation-price sentinel
+- **THEN** account health remains available while the position price estimate is unavailable
+
+### Requirement: Risk freshness expires unchanged snapshots
+EMC SHALL mark risk stale after five minutes from its original observation, on read failure or for future timestamps. Existing UI polling SHALL update freshness even when the snapshot is unchanged, without additional venue calls/timers. Old critical states SHALL remain prominent with uncertainty; stale or incomplete noncritical observations SHALL NOT appear fresh green. Reconciliation SHALL preserve row identity, selection, expansion and TWAP state.
+
+#### Scenario: Unchanged successful snapshot grows old
+- **WHEN** time passes the five-minute risk age limit without new data or errors
+- **THEN** existing UI polling changes its freshness indication without resetting the tree
+
+#### Scenario: Retained critical risk
+- **WHEN** a previously critical observation fails to refresh
+- **THEN** its critical state and original time remain visible with stale/retained indication