5.1 KiB
evelyn-perps-overview Specification
Purpose
Let the owner inspect Evelyn perpetual positions grouped by wallet and venue in Mission Control, with stable row identities across service snapshot updates.
Requirements
Requirement: Perps overview displays a collapsible position hierarchy
The Perps tab SHALL display Position, Direction, Margin, Collateral, Leverage, Exposure, Value and uPnL in that order 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, leave direction/aggregate ratios blank, and be expanded by default.
Scenario: Open either environment's Perps tab
- WHEN the owner opens Perps in Production or Test
- THEN all eight columns, root totals and the account-aware hierarchy are visible
Scenario: Collapse and expand groups
- WHEN the owner collapses and expands a wallet, venue or Cross account
- THEN descendants hide and return without changing totals
Requirement: Asynchronous polling follows window visibility
EMC SHALL request the current Perps snapshot from each environment's own service immediately on opening and every three seconds while visible, without blocking the UI thread. UI updates SHALL occur only on the JavaFX thread. Hiding the window SHALL stop polling; reopening SHALL create only one active polling loop and ignore results belonging to an earlier window session. Poll failures SHALL preserve the current view and allow subsequent attempts.
Scenario: Read takes time or fails
- WHEN a snapshot read is delayed or fails
- THEN the UI remains responsive and the existing view is retained
- AND later polling remains possible without overlapping scheduled reads
Scenario: Hide and reopen
- WHEN the owner hides and reopens EMC repeatedly
- THEN each visible session has only one polling loop and obsolete results cannot update its views
Scenario: Environment data stays separate
- WHEN TEST and PROD return different snapshots
- THEN each tab displays only its own service's data
- AND a failure reading one service does not prevent attempting the other service
Requirement: Polling preserves Perps view state
The Perps table SHALL retain matching wallet, venue and position identities across snapshots. Repeated unchanged snapshots SHALL leave existing rows, expansion, selection and formatting untouched without flicker. New groups SHALL be expanded by default, and future 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 no rebuild or refresh
Requirement: Jupiter positions communicate direction and USD size
Positions SHALL show readable Long/Short direction and Isolated/Cross margin text. USD amounts SHALL use grouping and two decimals; leverage SHALL use a multiplication sign. Signed uPnL SHALL be green for positive, red for negative and neutral for rounded zero without negative zero. Existing faint direction backgrounds SHALL remain; groups SHALL have distinct weight and no direction color. Numeric columns SHALL be right-aligned with useful widths and tooltips.
Scenario: Small or unavailable PnL
- WHEN PnL rounds to zero or is unavailable
- THEN zero has no negative sign/color and unavailable values show an em dash with an explanation
Scenario: Inspect real positions
- WHEN real Jupiter positions are displayed
- THEN direction appears as readable text and background color, with formatted gross USD exposure and applicable valuation metrics
Requirement: EMC presents service data without sample notices
EMC SHALL obtain positions only from its environment's in-memory service snapshot and SHALL contain no sample positions, sample notices, illustrative-Phoenix notices, or Refresh button. EMC SHALL own UI components, colors and formatting; integration reads SHALL belong to the service.
Scenario: Snapshot changes
- WHEN positions are added or removed after refresh
- THEN EMC reconciles rows by identity while preserving retained selections and expansion state
- AND no sample labels or Phoenix examples appear
Requirement: Definitions distinguish owned collateral and margin requirements
Tooltips SHALL explain isolated collateral, exposure-based leverage, collateral-based ROI, estimated net Value and excluded slippage/swaps/rent. Cross position collateral SHALL be identified as initial margin required against shared collateral. Cross position Value SHALL be unavailable; unsupported Cross ROI/leverage SHALL be explained. Cross account leverage SHALL identify undiscounted equity before exit fees as its denominator.
Scenario: Inspect a Cross position
- WHEN the owner inspects a Cross row and its account group
- THEN the position shows a USD margin requirement and the account shows shared capital once
- AND no position-only metric is labeled account utilization