# Portfolio Manager - Quick Start Guide

## Installazione (Prima Esecuzione)

```bash
# 1. Entra nella directory del progetto
cd /mnt/ssd/data/python-lab/portfolio-manager

# 2. Crea virtual environment
python3 -m venv .venv

# 3. Attiva venv
source .venv/bin/activate

# 4. Installa dipendenze
pip install --upgrade pip
pip install -r requirements.txt
```

## Avvio Applicazione

```bash
# Assicurati che venv sia attivo
source .venv/bin/activate

# Lancia l'applicazione
python main.py
```

## Workflow Tipico

### 1. Aggiungi Holdings Iniziali

**Tab Snapshot → Click "Add Holding"**

Esempi:
- **VWCE.MI** (Vanguard FTSE All-World)
  - Tipo: ETF
  - Quantità: 1200
  - Prezzo Medio: €95.50

- **MEUD.MI** (iShares Core MSCI Europe)
  - Tipo: ETF
  - Quantità: 450
  - Prezzo Medio: €75.20

- **AZM.MI** (Azimut)
  - Tipo: Stock
  - Quantità: 176
  - Prezzo Medio: €34.26

- **CASH** (Liquidità)
  - Tipo: Cash
  - Quantità: 12000
  - Prezzo Medio: €1.00

### 2. Aggiorna Prezzi

**Tab Snapshot → Click "🔄 Update Prices"**

- Fetcha prezzi da yfinance
- Mostra progress dialog
- Aggiorna tabella con prezzi correnti
- Calcola P&L automaticamente

### 3. Registra Transazioni

**Tab Transactions:**

- **Buy**: Acquisto nuove azioni (aggiorna qty e prezzo medio)
- **Sell**: Vendita azioni (calcola P&L realizzato)
- **Dividend**: Registra dividendi ricevuti

Esempio Buy:
```
Ticker: AZM.MI
Quantity: 50
Price: €32.00
Date: 2025-12-15
Notes: Accumulo trimestrale
```

### 4. Visualizza Analytics

**Tab Analytics:**

- **Performance**: Total Value, P&L, Dividends
- **Allocation**: By Type (ETF/Stock/Cash), By Geography
- **Risk Metrics**: Concentration warnings, Diversification score
- **Top 5 Holdings**: Migliori posizioni per valore

## Features Principali

### Snapshot Tab
- Visualizzazione real-time portafoglio
- Update prezzi (yfinance con smart cache 4h)
- P&L colorato (verde/rosso)
- Weight % per holding
- Context menu: Delete holding

### Transactions Tab
- Log completo transazioni (BUY/SELL/DIVIDEND)
- Filtri per Type e Ticker
- Color coding (Buy verde, Sell rosso, Dividend giallo)
- Context menu: Delete transaction

### Analytics Tab
- Performance summary (Total Return, P&L, Dividends)
- Allocation pie charts (Type, Geography)
- Risk warnings (concentration >40% yellow, >60% red)
- Diversification score (HHI-based)
- Top 5 holdings table

## Menu Bar

### File
- **Refresh All** (Ctrl+R): Ricarica tutti i tab
- **Backup Database**: Crea backup timestamped
- **Exit** (Ctrl+Q): Chiudi applicazione

### Help
- **About**: Info applicazione
- **Database Stats**: Statistiche DB (holdings count, transactions count, etc.)

## Auto-Refresh

- Timer automatico ogni 4 ore (6:00-23:00)
- Aggiorna prezzi in background
- Usa cache se refresh automatico

## Database

- **Location**: `data/portfolio.db`
- **Tabelle**: holdings, transactions, price_cache
- **Backup**: File → Backup Database
- **Formato**: SQLite (portable, no server needed)

## Logging

- **File**: `portfolio.log` (level DEBUG)
- Tutte le operazioni loggiate
- Error handling con stacktraces

## Tips & Tricks

1. **First Run**: Aggiungi cash position come holding separato (CASH, tipo Cash)
2. **Price Updates**: Manuale per forza refresh, automatico usa cache (più veloce)
3. **Concentration Warning**: >40% yellow, >60% red - diversifica!
4. **Realized P&L**: Visibile solo in transaction notes dopo SELL
5. **Delete Transaction**: NON reverse gli effetti - aggiusta holdings manualmente se serve

## Troubleshooting

### "Cannot fetch price for ticker"
- Verifica ticker su Yahoo Finance (es. VWCE.MI per Milano)
- Alcuni ETF/stocks potrebbero non essere su yfinance
- Usa prezzi manuali (avg_price) se necessario

### "Database locked"
- Chiudi tutte le istanze dell'app
- Verifica permissions su `data/portfolio.db`

### "PyQt6 import error"
- Verifica venv attivo: `which python` deve mostrare `.venv/bin/python`
- Re-install: `pip install --force-reinstall PyQt6`

## Roadmap Future Features

- [ ] Performance charts storici (matplotlib)
- [ ] Benchmark comparison (FTSE MIB, S&P 500)
- [ ] Export report (PDF/Excel)
- [ ] Multi-currency support
- [ ] Dark theme (QSS stylesheet)
- [ ] Keyboard shortcuts aggiuntivi

## Support

Per bug o feature requests:
- Controlla `portfolio.log` per dettagli errori
- Verifica database stats (Help → Database Stats)
- Crea backup prima di operazioni massive

---

**Target Portfolio**: 180k EUR (Core ETF 160k + Satellite Stock 20k)
**Version**: 1.0
**Tech**: Python 3.12 • PyQt6 • SQLite • yfinance