# Premium Trading Feature - Implementation Guide

## 🎯 Overview

This premium trading feature helps you identify cheap option premiums and generate buy signals for profitable trades. It's designed specifically for Indian stock market beginners learning option trading.

### Key Features:
- ✅ Dashboard showing all available option premiums by expiry
- ✅ Identify cheap premiums using statistical indicators (Z-Score, Percentile)
- ✅ Open Interest (OI) analysis for liquidity assessment
- ✅ Automatic buy signal generation with profit targets
- ✅ Trade entry and P&L tracking
- ✅ Performance statistics and win rate analysis

---

## 📁 File Structure

```
app/
├── Models/
│   ├── TradeSignal.php           # Buy signal model
│   ├── TradeEntry.php            # Trade entry and P&L tracking
│   └── PremiumMetric.php          # (existing) Premium metrics data
├── Services/
│   └── PremiumDashboardService.php # Business logic for dashboard
├── Http/Controllers/
│   └── PremiumController.php       # (updated) Added new endpoints
├── Events/
│   └── PremiumComputeFinished.php # (existing) Events for signals
└── Jobs/
    └── ComputePremiumMetricsJob.php # (existing) Job to compute metrics

database/
├── migrations/
│   ├── 2025_12_18_211243_create_trade_signals_table.php
│   ├── 2025_12_18_211245_create_trade_entries_table.php
│   └── ... (existing premium migrations)

resources/views/premium/
├── dashboard.blade.php  # Main dashboard with metrics
├── trades.blade.php     # Trade entries and P&L tracking
└── stats.blade.php      # Performance statistics
```

---

## 🚀 Quick Start

### 1. **Access the Dashboard**
```
URL: /premium/dashboard
Filters: Cheap, Expensive, Spikes, Active Alerts
Sort: By cheapness, OI, Price Spikes
```

### 2. **Generate a Buy Signal**
- Click "Signal" button on any cheap premium (Z-Score ≤ -2.0)
- Review expected profit calculation
- Confirm quantity and target/stop loss prices
- System creates a buy signal record

### 3. **Create Trade Entry**
- From the signal, click "Create Trade"
- Enter actual entry price and contract quantity
- Set target price and stop loss
- Add optional notes
- Track trade from "Trades" page

### 4. **Manage Open Trades**
- View all open trades in real-time
- Monitor P&L (profit/loss)
- Close trade manually or wait for target/SL
- Detailed exit reason tracking

### 5. **Review Performance**
- Stats page shows win rate and total P&L
- Recent trade details with ROI
- Identify what's working with your strategy

---

## 📊 Database Schema

### `trade_signals` Table
Stores generated buy signals from premium metrics.

| Column | Type | Purpose |
|--------|------|---------|
| id | bigint | Primary key |
| premium_metric_id | bigint FK | Links to PremiumMetric |
| user_id | bigint FK | User who generated signal |
| symbol | varchar | Base symbol (NIFTY, BANKNIFTY) |
| strike_value | int | Strike price |
| side | enum | CE (Call) or PE (Put) |
| entry_price | decimal | Recommended entry price |
| expected_price | decimal | Expected fair value |
| profit_points | decimal | Expected profit per contract |
| profit_percentage | decimal | Expected profit % |
| z_score | decimal | How cheap the premium is |
| signal_status | enum | active, traded, expired, cancelled |
| signal_triggered_at | timestamp | When signal was created |
| valid_until | timestamp | Signal expiration time |

### `trade_entries` Table
Tracks actual trade executions and P&L.

| Column | Type | Purpose |
|--------|------|---------|
| id | bigint | Primary key |
| trade_signal_id | bigint FK | Associated signal |
| user_id | bigint FK | User who traded |
| entry_price | decimal | Actual entry price paid |
| current_price | decimal | Latest market price |
| exit_price | decimal | Exit price if closed |
| target_price | decimal | Target exit price |
| stop_loss_price | decimal | Stop loss price |
| trade_status | enum | open, partial, closed, cancelled |
| exit_reason | enum | target_hit, stop_loss, manual, expiry |
| unrealized_pnl | decimal | Current P&L if open |
| realized_pnl | decimal | Final P&L if closed |
| pnl_percentage | decimal | P&L as percentage |
| roi | decimal | Return on Investment % |
| entered_at | timestamp | Entry time |
| exited_at | timestamp | Exit time |

---

## 🔌 API Endpoints

### Dashboard Routes

**GET /premium/dashboard**
- Shows clean dashboard with cheap premiums grouped by expiry
- Query params: filter, sort, side
- Returns: Metrics grouped by expiry, summary stats, trade stats

**POST /premium/signal/generate**
- Generates a buy signal from a premium metric
- Params: metric_id
- Returns: Signal with expected profit calculation

**POST /premium/trade/create**
- Creates trade entry from a signal
- Params: signal_id, quantity, entry_price, target_price, stop_loss_price, notes
- Returns: Trade entry with P&L tracking setup

**GET /premium/trades**
- Lists all trades (open, closed, or all)
- Query params: status (open|closed|all)
- Paginated: 20 per page

**POST /premium/trade/{id}/close**
- Closes an open trade with exit price
- Params: exit_price, reason (target_hit|stop_loss|manual|expiry)
- Returns: Updated trade with realized P&L

**GET /premium/stats**
- Performance statistics and recent trades
- Returns: Win rate, total profit, trade metrics

---

## 🎓 Understanding the Metrics

### Z-Score Interpretation

Z-Score shows how many standard deviations away from mean:

```
Z-Score ≤ -3.0  →  🟢 EXTREMELY CHEAP      (Top 0.1% of lows)
Z-Score ≤ -2.0  →  🟢 VERY CHEAP           (Top 2.3% of lows)  ← BEST FOR BUY
Z-Score ≤ -1.0  →  🟡 MODERATELY CHEAP    (Top 15.9% of lows)
Z-Score 0 to 1  →  ⚪ FAIR VALUE           (Average)
Z-Score ≥ 2.0   →  🔴 EXPENSIVE            (Top 2.3% of highs)   ← AVOID LONG
Z-Score ≥ 3.0   →  🔴 EXTREMELY EXPENSIVE (Top 0.1% of highs)
```

### Expected Price Calculation

```
Expected Price = Mean Historical Premium ± (Z-Score × Std Deviation)

If Current < Expected:
  → Opportunity to buy with upside potential
  → Profit Points = Expected - Current
  → Profit % = (Profit Points / Current) × 100
```

### OI (Open Interest) Classification

```
OI < 10,000   →  ⚠️  LOW (Avoid - spreads too wide)
OI 10K-50K    →  🟡 MODERATE (OK - use tighter SL)
OI 50K+       →  🟢 HIGH (Excellent - tight spreads)
```

---

## 💡 Usage Examples

### Example 1: Trading a Cheap Call Option

**Scenario:**
- NIFTY 50 Strike Call
- Current Premium: ₹15
- Expected Fair Value: ₹25
- Z-Score: -2.5 (Very Cheap)
- OI: 75,000 (Excellent)

**Action:**
1. Dashboard shows this strike highlighted in green
2. Click "Signal" → System calculates ₹10 profit potential (66% profit)
3. Valid signal for 24 hours
4. Create trade with:
   - Entry: ₹15
   - Target: ₹22 (90% of expected)
   - SL: ₹10.50 (30% below entry)
5. If premium moves to ₹22 by end of day, close for ₹7 profit
6. P&L shown automatically: +₹700 (47% ROI)

### Example 2: Comparing Two Puts

**Strike 1 (Cheap):**
- Premium: ₹8 (Z: -2.1)
- Expected: ₹14
- Profit Potential: ₹6 (75%)

**Strike 2 (Fair):**
- Premium: ₹12 (Z: -0.1)
- Expected: ₹13
- Profit Potential: ₹1 (8%)

**Decision:**
Choose Strike 1 - Much better reward:risk ratio

### Example 3: Failed Trade & Learning

**Trade:**
- Bought Call at ₹15
- Target: ₹22
- SL: ₹10.50

**Outcome:**
- Premium fell to ₹11 (hit SL)
- Loss: ₹4 (-27%)

**Stats Show:**
- Win Rate: 60% (6 winners, 4 losers)
- This loss acceptable - stay disciplined

---

## 🛠️ Development Notes

### Service: PremiumDashboardService

Key methods:

```php
// Get dashboard metrics with filtering
getDashboardMetrics(array $filters): array

// Generate buy signal from metric
generateBuySignal(PremiumMetric $metric): TradeSignal

// Create trade entry from signal
createTradeEntry(TradeSignal $signal, array $data): TradeEntry

// Get statistics
getTradeStats(?int $userId): array
```

### Models: Relationships

```php
// TradeSignal relationships
$signal->premiumMetric()    // The metric it came from
$signal->user()             // User who created signal
$signal->tradeEntries()     // All trade executions

// TradeEntry relationships
$entry->signal()            // The signal it came from
$entry->user()              // User who entered trade

// Methods
$entry->calculateUnrealizedPnl()    // Auto-calculate P&L
$entry->closeWith($price, $reason)  // Close and calculate final P&L
$entry->hasHitTarget()              // Check if target reached
$entry->hasHitStopLoss()            // Check if SL reached
```

---

## ⚙️ Configuration

Add to your `.env` file:

```env
# Premium metrics thresholds
PREMIUM_Z_THRESHOLD=2.0              # Z-score threshold for cheap
PREMIUM_PERCENTILE_LOW=5.0          # Low percentile threshold
PREMIUM_PERCENTILE_HIGH=95.0        # High percentile threshold
PREMIUM_MIN_SAMPLES=30              # Minimum samples for signal

# Spike score thresholds
SPIKE_SCORE_HIGH=0.7                # High spike score threshold
```

---

## 🔄 Integration with Existing Features

### Premium Metrics Computation
- Existing `ComputePremiumMetricsJob` runs periodically
- Calculates Z-Score, Percentile, Cheap Score, etc.
- New dashboard uses these metrics

### Signals & Events
- Existing `premium_extreme` signals detected separately
- New signals are user-generated from dashboard
- Both types tracked independently

### Quote Collection
- Existing `TrackedQuote` table captures tick data
- Trade entries use current prices for P&L
- Historical quotes available for backtesting

---

## 📈 Future Enhancements

- [ ] Charts: Win rate trends, profit distribution
- [ ] Real-time price updates for open trades
- [ ] Automated exit on target/SL
- [ ] Multiple strategy configurations
- [ ] Backtest feature: Test signals on historical data
- [ ] Mobile app for on-the-go trading
- [ ] Alert notifications for signals and exits
- [ ] Export trade journal to CSV

---

## ✅ Checklist for Deployment

- [x] Database migrations created
- [x] Models created with relationships
- [x] Service class with business logic
- [x] Controller endpoints added
- [x] Views/templates created
- [x] Routes registered
- [ ] Testing completed
- [ ] User acceptance testing
- [ ] Production deployment

---

## 🆘 Troubleshooting

### Migrations Failed?
```bash
php artisan migrate:rollback
php artisan migrate
```

### No Signals Generated?
1. Ensure `premium_metrics` table has data
2. Run `ComputePremiumMetricsJob` manually
3. Check Z-Score thresholds in config

### Can't Create Trade?
1. Signal must be in 'active' status
2. Entry price must be > 0
3. Target price > Entry price
4. SL price < Entry price

---

## 📞 Support

For issues or questions:
1. Check PREMIUM_TRADING_GUIDE.md for concepts
2. Review controller methods for API usage
3. Check model relationships
4. Review service methods for business logic

---

**Last Updated:** December 18, 2025
**Version:** 1.0.0