feat: Add Phase 4 advanced metrics and components
- Add advanced metrics dashboard with trade analytics - Add new trading components (EntryTypeAnalysis, MultiDayPositionTracker, NewsEventTracker, etc.) - Add strategy mode selector and trend confirmation - Add risk automation panel and slippage correlation analysis - Add daily trading plan enhancements with modal components - Add custom hooks (useApi, useLocalStorage, useAdvancedTradeMetrics) - Add broker service integration and trading API - Add test setup and vitest configuration - Include parquet data files for live market data - Add comprehensive documentation in docs/ folder
This commit is contained in:
Krikorios
@@ -0,0 +1,420 @@
|
||||
# 🛡️ Position Assistant - Companion Guide
|
||||
|
||||
## Overview
|
||||
|
||||
The **Position Assistant** is your intelligent companion for managing active trading positions. Instead of just relying on stop losses, it provides:
|
||||
|
||||
- 📊 **Real-time Health Assessment** - Know exactly how your position is doing
|
||||
- 🎯 **Mitigation Strategies** - Multiple exit plans beyond just stop loss
|
||||
- 🔮 **Reversal Predictions** - Where and when price might turn in your favor
|
||||
- ⏱️ **Time-based Plans** - Optimal timeframes to review and exit
|
||||
- 🚨 **Urgency Alerts** - Know when to act immediately
|
||||
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. **Enter Your Position**
|
||||
```
|
||||
Direction: SHORT/LONG
|
||||
Entry Price: 4070
|
||||
Current Price: 4085
|
||||
Stop Loss: 4109
|
||||
Quantity: 1.0
|
||||
```
|
||||
|
||||
### 2. **Click "Get Mitigation Plan"**
|
||||
The assistant analyzes your position using:
|
||||
- Technical indicators (ATR, Fibonacci)
|
||||
- Support/resistance levels
|
||||
- Historical price patterns
|
||||
- Risk/reward calculations
|
||||
|
||||
### 3. **Review Your Plan**
|
||||
You'll get:
|
||||
- Position health status (HEALTHY/AT_RISK/CRITICAL/WINNING)
|
||||
- Current P&L and distance to stop loss
|
||||
- Priority-ranked mitigation strategies
|
||||
- Predicted reversal zones with probabilities
|
||||
- Optimal exit plan
|
||||
|
||||
### 4. **Enable Auto-Refresh** (Optional)
|
||||
Toggle "Auto-refresh (10s)" to get real-time updates as price moves.
|
||||
|
||||
---
|
||||
|
||||
## Position Health Statuses
|
||||
|
||||
| Status | Meaning | Urgency | Action Required |
|
||||
|--------|---------|---------|----------------|
|
||||
| 🟢 **WINNING** | Position is profitable and moving favorably | LOW | Consider scaling out or trailing stop |
|
||||
| 🔵 **HEALTHY** | Position within acceptable risk, no immediate concern | LOW | Monitor normally |
|
||||
| 🟡 **AT_RISK** | Position moving against you, consider mitigation | MEDIUM | Review mitigation strategies |
|
||||
| 🔴 **CRITICAL** | Very close to stop loss, immediate action needed | URGENT | Execute emergency plan |
|
||||
|
||||
---
|
||||
|
||||
## Example: Managing a Losing SHORT Position
|
||||
|
||||
### Your Scenario
|
||||
```
|
||||
✅ You entered SHORT at $4070
|
||||
❌ Price is now $4085 (against you)
|
||||
🛑 Stop loss at $4109
|
||||
⏱️ You've been in the trade for 6.8 hours
|
||||
```
|
||||
|
||||
### What the Assistant Provides
|
||||
|
||||
#### 1. **Health Assessment**
|
||||
```
|
||||
Status: AT_RISK ⚠️
|
||||
Current P&L: -$15 (-0.37%)
|
||||
Distance to Stop Loss: $24 (0.59%)
|
||||
Urgency: MEDIUM
|
||||
Time in Trade: 6.8 hours
|
||||
|
||||
Recommendation: "Consider closing 50% at break-even to reduce risk"
|
||||
```
|
||||
|
||||
#### 2. **Mitigation Strategies** (Prioritized)
|
||||
|
||||
**Strategy 1: Break-Even Exit (LOW RISK)**
|
||||
```
|
||||
Action: Close 50% of position at $4070.00
|
||||
Reasoning: Reduces exposure while keeping upside potential
|
||||
Expected Benefit: Cuts risk by 50%, frees up margin
|
||||
```
|
||||
|
||||
**Strategy 2: Scale Out Gradually (MEDIUM RISK)**
|
||||
```
|
||||
Action: Close 25% now, 25% at $4070, keep 50% for reversal
|
||||
Reasoning: Balanced approach between risk reduction and profit potential
|
||||
Expected Benefit: Reduces emotional pressure, maintains upside
|
||||
```
|
||||
|
||||
**Strategy 3: Widen Stop Loss (HIGH RISK)**
|
||||
```
|
||||
Action: Move stop loss to $4115 if confident in reversal
|
||||
Reasoning: Gives trade more room if you have strong conviction
|
||||
Expected Benefit: Avoids premature stop-out on volatility
|
||||
⚠️ Warning: Increases maximum loss to $45
|
||||
```
|
||||
|
||||
**Strategy 4: Emergency Hedge (HIGH RISK)**
|
||||
```
|
||||
Action: Open small LONG position to protect against further loss
|
||||
Reasoning: Creates synthetic stop while maintaining short exposure
|
||||
Expected Benefit: Caps downside, complex to manage
|
||||
```
|
||||
|
||||
**Strategy 5: Hold for Reversal (HIGH RISK)**
|
||||
```
|
||||
Action: Wait for predicted reversal at $4008.95
|
||||
Reasoning: Technical analysis suggests support at this level
|
||||
Expected Benefit: Could turn losing trade into winner
|
||||
⚠️ Warning: Requires discipline, could hit stop loss first
|
||||
```
|
||||
|
||||
#### 3. **Reversal Zones**
|
||||
|
||||
**Zone 1: $4008.95** (🟢 70% probability)
|
||||
```
|
||||
Timeframe: End of day
|
||||
Reasoning: Estimated previous day low - strong support
|
||||
Confluences: ["Daily Support", "Psychological Level"]
|
||||
```
|
||||
|
||||
**Zone 2: $4079.27** (🟡 65% probability)
|
||||
```
|
||||
Timeframe: 2-4 hours
|
||||
Reasoning: 38.2% Fibonacci retracement
|
||||
Confluences: ["Fibonacci 38.2%"]
|
||||
```
|
||||
|
||||
**Zone 3: $3900** (🟠 55% probability)
|
||||
```
|
||||
Timeframe: End of week
|
||||
Reasoning: Major psychological support level
|
||||
Confluences: ["Psychological Level"]
|
||||
```
|
||||
|
||||
#### 4. **Optimal Exit Plan**
|
||||
|
||||
```
|
||||
Level 1: Close 100% at $4008.95 (70% probability)
|
||||
└─ Reason: Highest probability reversal zone
|
||||
└─ Potential: +$61.05 profit if hit
|
||||
|
||||
Level 2: Close 50% at $4079.27 (65% probability)
|
||||
└─ Reason: Quick profit-taking on Fibonacci bounce
|
||||
└─ Potential: +$9.27 profit on half position
|
||||
|
||||
Time-based Fallback:
|
||||
└─ If no reversal by end of session, reassess
|
||||
└─ Consider break-even exit if price approaches $4070
|
||||
```
|
||||
|
||||
#### 5. **Next Actions**
|
||||
```
|
||||
1. 📋 PRIMARY: Close 50% of position at $4070.00 (break-even)
|
||||
2. 🎯 WATCH: Set alert for $4008.95 (reversal zone)
|
||||
3. ⏰ TIME: Review position at market close if still open
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Understanding Mitigation Strategies
|
||||
|
||||
### Break-Even Exit
|
||||
**When to use**: Price is against you but not critical yet
|
||||
**Benefit**: Removes emotional pressure, frees capital, limits loss
|
||||
**Risk**: Might miss reversal if you close too early
|
||||
|
||||
### Scale Out Gradually
|
||||
**When to use**: Uncertain about direction, want to reduce but not eliminate exposure
|
||||
**Benefit**: Balanced risk management, flexibility
|
||||
**Risk**: More complex to track, multiple transactions
|
||||
|
||||
### Widen Stop Loss
|
||||
**When to use**: Strong conviction in analysis, confident in reversal
|
||||
**Benefit**: Avoids premature stop-out
|
||||
**Risk**: ⚠️ **INCREASES maximum loss** - only if analysis is very strong
|
||||
|
||||
### Emergency Hedge
|
||||
**When to use**: Can't exit but need protection
|
||||
**Benefit**: Caps further losses
|
||||
**Risk**: Complex management, double spread cost, ties up margin
|
||||
|
||||
### Hold for Reversal
|
||||
**When to use**: Technical setup remains valid, reversal zone approaching
|
||||
**Benefit**: Could turn loser into winner
|
||||
**Risk**: Might hit stop loss before reversal happens
|
||||
|
||||
---
|
||||
|
||||
## Reversal Zone Probability Guide
|
||||
|
||||
| Probability | Confidence | How to Use |
|
||||
|------------|------------|------------|
|
||||
| **70-100%** | 🟢 High | Set limit orders, plan full exits |
|
||||
| **50-70%** | 🟡 Medium | Watch closely, partial exits |
|
||||
| **30-50%** | 🟠 Low | Don't rely on, have backup plan |
|
||||
| **<30%** | 🔴 Very Low | Ignore, focus on higher probability zones |
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### ✅ DO
|
||||
- ✅ Use mitigation strategies **before** stop loss hits
|
||||
- ✅ Consider break-even exits for psychological relief
|
||||
- ✅ Set alerts at reversal zones
|
||||
- ✅ Review position health regularly
|
||||
- ✅ Combine multiple strategies (e.g., scale out + reversal watch)
|
||||
- ✅ Trust the urgency level - URGENT means act now
|
||||
|
||||
### ❌ DON'T
|
||||
- ❌ Widen stop loss without strong conviction
|
||||
- ❌ Ignore AT_RISK or CRITICAL status
|
||||
- ❌ Wait until last minute (when already CRITICAL)
|
||||
- ❌ Rely on single low-probability reversal zone
|
||||
- ❌ Add to losing position without mitigation plan
|
||||
- ❌ Turn off auto-refresh when position is AT_RISK
|
||||
|
||||
---
|
||||
|
||||
## Integration with Your App
|
||||
|
||||
### Add to App.tsx
|
||||
```tsx
|
||||
import PositionAssistant from './components/PositionAssistant';
|
||||
|
||||
function TradingView() {
|
||||
return (
|
||||
<div className="grid gap-4">
|
||||
{/* Your existing components */}
|
||||
<PositionAssistant refreshInterval={10000} />
|
||||
</div>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### Props
|
||||
- `refreshInterval` (optional): Auto-refresh frequency in milliseconds (default: 10000 = 10 seconds)
|
||||
|
||||
---
|
||||
|
||||
## API Endpoints
|
||||
|
||||
### POST `/api/position-assistant/analyze`
|
||||
|
||||
**Query Params:**
|
||||
- `current_price` (float): Current market price
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"symbol": "XAU/USD",
|
||||
"direction": "SHORT",
|
||||
"entry_price": 4070.0,
|
||||
"quantity": 1.0,
|
||||
"stop_loss": 4109.0,
|
||||
"entry_time": "2025-11-24T10:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"position": { ... },
|
||||
"current_price": 4085.0,
|
||||
"health": {
|
||||
"status": "AT_RISK",
|
||||
"current_pnl": -15.0,
|
||||
"current_pnl_percent": -0.37,
|
||||
"distance_to_stop_loss": 24.0,
|
||||
"urgency": "MEDIUM"
|
||||
},
|
||||
"mitigation_strategies": [ ... ],
|
||||
"reversal_zones": [ ... ],
|
||||
"exit_plan": { ... },
|
||||
"alerts": [ ... ],
|
||||
"next_actions": [ ... ]
|
||||
}
|
||||
```
|
||||
|
||||
### GET `/api/position-assistant/quick-status`
|
||||
|
||||
**Query Params:**
|
||||
- `entry_price` (float)
|
||||
- `current_price` (float)
|
||||
- `stop_loss` (float)
|
||||
- `direction` (str): "LONG" or "SHORT"
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"pnl": -15.0,
|
||||
"pnl_percent": -0.37,
|
||||
"distance_to_stop_loss": 24.0,
|
||||
"status": "AT_RISK"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Pro Tips
|
||||
|
||||
### 1. **Pre-Trade Planning**
|
||||
Before entering a position, run a hypothetical analysis:
|
||||
```
|
||||
Entry: 4070
|
||||
Current: 4070 (same as entry)
|
||||
Stop Loss: 4109
|
||||
```
|
||||
This shows you what to expect if price goes against you.
|
||||
|
||||
### 2. **Emergency Mode**
|
||||
If position becomes CRITICAL:
|
||||
1. Check "Next Actions" immediately
|
||||
2. Execute highest priority action (usually partial exit)
|
||||
3. Don't wait for perfect reversal
|
||||
|
||||
### 3. **Confluence Zones**
|
||||
Reversal zones with multiple confluences are stronger:
|
||||
```
|
||||
Level: $4008.95
|
||||
Confluences: ["Daily Support", "Fibonacci 61.8%", "Previous Week Low"]
|
||||
```
|
||||
This has 3x the probability of a simple zone.
|
||||
|
||||
### 4. **Time Management**
|
||||
Use timeframe estimates to plan your day:
|
||||
```
|
||||
Zone 1: 2-4 hours → Stay at desk
|
||||
Zone 2: End of day → Set mobile alert
|
||||
Zone 3: End of week → Don't stress short-term
|
||||
```
|
||||
|
||||
### 5. **Combine with Daily Plan**
|
||||
Position Assistant works WITH your daily trading plan:
|
||||
- Daily plan limits entries
|
||||
- Position Assistant manages active positions
|
||||
- Live Dashboard monitors overall account
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "Position shows HEALTHY but I feel stressed"
|
||||
→ Trust your gut. Use "Break-Even Exit" for psychological relief.
|
||||
|
||||
### "Reversal zone hit but price kept going"
|
||||
→ Probabilities are NOT guarantees. Have backup plan ready.
|
||||
|
||||
### "Too many strategies, can't decide"
|
||||
→ Start with lowest risk option (usually Break-Even Exit).
|
||||
|
||||
### "API returns error"
|
||||
→ Check:
|
||||
- Backend server running (`cd backend && ./start.sh`)
|
||||
- Valid price inputs (no negative numbers)
|
||||
- Network connection
|
||||
|
||||
### "Auto-refresh not working"
|
||||
→ Check:
|
||||
- Checkbox is enabled
|
||||
- Backend is responding
|
||||
- Browser console for errors
|
||||
|
||||
---
|
||||
|
||||
## Real-World Example: Success Story
|
||||
|
||||
### Initial State
|
||||
```
|
||||
SHORT at 4070, price moved to 4085 (-$15)
|
||||
Status: AT_RISK
|
||||
```
|
||||
|
||||
### Actions Taken
|
||||
1. ✅ Closed 50% at break-even ($4070) when price retraced briefly
|
||||
2. ✅ Set alert at $4008.95 (70% reversal zone)
|
||||
3. ✅ Kept 50% position with mental stop at $4109
|
||||
|
||||
### Outcome
|
||||
```
|
||||
Price reversed to $4010 after 8 hours
|
||||
Closed remaining 50% at $4010 (+$60)
|
||||
Total P&L: $0 (first half) + $60 (second half) = +$60
|
||||
```
|
||||
|
||||
**Without Position Assistant:** Would have held 100% and risked full stop loss ($-39) or closed at $4085 for full -$15 loss.
|
||||
|
||||
**With Position Assistant:** Turned potential -$15 loss into +$60 win using strategic partial exit + reversal watch.
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
The Position Assistant is NOT a crystal ball. It's a **decision support tool** that:
|
||||
- Removes emotion from position management
|
||||
- Provides data-driven mitigation options
|
||||
- Helps you act BEFORE hitting stop loss
|
||||
- Gives you confidence in your decisions
|
||||
- Turns "hope and pray" into systematic risk management
|
||||
|
||||
**Remember:** The best mitigation plan is the one you actually execute. Don't overthink - trust the priority ranking and act decisively.
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. ✅ Test with a current position
|
||||
2. ✅ Enable auto-refresh and watch it work
|
||||
3. ✅ Execute a mitigation strategy
|
||||
4. ✅ Compare results to "just hold until stop loss"
|
||||
5. ✅ Build confidence in the system
|
||||
|
||||
**Need Help?** Check `/docs` for additional guides or review PHASE4_QUICK_REFERENCE.md for overall system architecture.
|
||||
Reference in New Issue
Block a user