# Prompt: Database & Models Implementation (T06-T11)

## 🎯 OBIETTIVO

Implementare la fase **Database & Models** del progetto OpenRouter API Key Monitor seguendo rigorosamente TDD (Test-Driven Development).

**Task da completare:** T06, T07, T08, T09, T10, T11

---

## 📋 CONTESTO

- **Repository:** `/home/google/Sources/LucaSacchiNet/openrouter-watcher`
- **Specifiche:** `/home/google/Sources/LucaSacchiNet/openrouter-watcher/export/architecture.md`
- **Kanban:** `/home/google/Sources/LucaSacchiNet/openrouter-watcher/export/kanban.md`
- **Stato Attuale:** Setup completato (T01-T05), 59 test passanti

---

## 🗄️ SCHEMA DATABASE (Da architecture.md)

### Tabelle

#### 1. users
```sql
CREATE TABLE users (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    email VARCHAR(255) NOT NULL UNIQUE,
    password_hash VARCHAR(255) NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    is_active BOOLEAN DEFAULT 1,
    CONSTRAINT chk_email_format CHECK (email LIKE '%_@__%.__%')
);
```

#### 2. api_keys
```sql
CREATE TABLE api_keys (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    user_id INTEGER NOT NULL,
    name VARCHAR(100) NOT NULL,
    key_encrypted TEXT NOT NULL,  -- AES-256-GCM encrypted
    is_active BOOLEAN DEFAULT 1,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    last_used_at TIMESTAMP,
    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
);
```

#### 3. usage_stats
```sql
CREATE TABLE usage_stats (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    api_key_id INTEGER NOT NULL,
    date DATE NOT NULL,
    model VARCHAR(100) NOT NULL,
    requests_count INTEGER DEFAULT 0,
    tokens_input INTEGER DEFAULT 0,
    tokens_output INTEGER DEFAULT 0,
    cost DECIMAL(10, 6) DEFAULT 0.0,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (api_key_id) REFERENCES api_keys(id) ON DELETE CASCADE,
    CONSTRAINT uniq_key_date_model UNIQUE (api_key_id, date, model)
);
```

#### 4. api_tokens
```sql
CREATE TABLE api_tokens (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    user_id INTEGER NOT NULL,
    token_hash VARCHAR(255) NOT NULL,
    name VARCHAR(100) NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    last_used_at TIMESTAMP,
    is_active BOOLEAN DEFAULT 1,
    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
);
```

---

## 🔧 TASK DETTAGLIATI

### T06: Creare database.py (connection & session)

**Requisiti:**
- Creare `src/openrouter_monitor/database.py`
- Implementare SQLAlchemy engine con SQLite
- Configurare session maker con expire_on_commit=False
- Implementare funzione `get_db()` per dependency injection FastAPI
- Implementare `init_db()` per creazione tabelle
- Usare `check_same_thread=False` per SQLite

**Test richiesti:**
- Test connessione database
- Test creazione engine
- Test session creation
- Test init_db crea tabelle

---

### T07: Creare model User (SQLAlchemy)

**Requisiti:**
- Creare `src/openrouter_monitor/models/user.py`
- Implementare class `User` con tutti i campi
- Configurare relationships con ApiKey e ApiToken
- Implementare `check_email_format` constraint
- Campi: id, email, password_hash, created_at, updated_at, is_active
- Index su email

**Test richiesti:**
- Test creazione utente
- Test vincolo email unique
- Test validazione email format
- Test relationship con api_keys
- Test relationship con api_tokens

---

### T08: Creare model ApiKey (SQLAlchemy)

**Requisiti:**
- Creare `src/openrouter_monitor/models/api_key.py`
- Implementare class `ApiKey`
- Configurare relationship con User e UsageStats
- Foreign key su user_id con ON DELETE CASCADE
- Campi: id, user_id, name, key_encrypted, is_active, created_at, last_used_at
- Index su user_id e is_active

**Test richiesti:**
- Test creazione API key
- Test relationship con user
- Test relationship con usage_stats
- Test cascade delete

---

### T09: Creare model UsageStats (SQLAlchemy)

**Requisiti:**
- Creare `src/openrouter_monitor/models/usage_stats.py`
- Implementare class `UsageStats`
- Configurare relationship con ApiKey
- Unique constraint: (api_key_id, date, model)
- Campi: id, api_key_id, date, model, requests_count, tokens_input, tokens_output, cost, created_at
- Index su api_key_id, date, model
- Usare Numeric(10, 6) per cost

**Test richiesti:**
- Test creazione usage stats
- Test unique constraint
- Test relationship con api_key
- Test valori default (0)

---

### T10: Creare model ApiToken (SQLAlchemy)

**Requisiti:**
- Creare `src/openrouter_monitor/models/api_token.py`
- Implementare class `ApiToken`
- Configurare relationship con User
- Foreign key su user_id con ON DELETE CASCADE
- Campi: id, user_id, token_hash, name, created_at, last_used_at, is_active
- Index su user_id, token_hash, is_active

**Test richiesti:**
- Test creazione API token
- Test relationship con user
- Test cascade delete

---

### T11: Setup Alembic e migrazione iniziale

**Requisiti:**
- Inizializzare Alembic: `alembic init alembic`
- Configurare `alembic.ini` con DATABASE_URL
- Configurare `alembic/env.py` con Base metadata
- Creare migrazione iniziale che crea tutte le tabelle
- Migrazione deve includere indici e constraints
- Testare upgrade/downgrade

**Test richiesti:**
- Test alembic init
- Test creazione migration file
- Test upgrade applica cambiamenti
- Test downgrade rimuove cambiamenti
- Test tutte le tabelle create correttamente

---

## 🔄 WORKFLOW TDD OBBLIGATORIO

Per OGNI task (T06-T11):

```
┌─────────────────────────────────────────┐
│  1. RED - Scrivi il test che fallisce   │
│     • Test prima del codice             │
│     • Pattern AAA (Arrange-Act-Assert)  │
│     • Nomi descrittivi                  │
└─────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────┐
│  2. GREEN - Implementa codice minimo    │
│     • Solo codice necessario per test   │
│     • Nessun refactoring ancora         │
└─────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────┐
│  3. REFACTOR - Migliora il codice       │
│     • Pulisci duplicazioni              │
│     • Migliora nomi variabili           │
│     • Test rimangono verdi              │
└─────────────────────────────────────────┘
```

---

## 📁 STRUTTURA FILE DA CREARE

```
src/openrouter_monitor/
├── database.py                    # T06
└── models/
    ├── __init__.py               # Esporta tutti i modelli
    ├── user.py                   # T07
    ├── api_key.py                # T08
    ├── usage_stats.py            # T09
    └── api_token.py              # T10

alembic/
├── alembic.ini                   # Configurazione
├── env.py                        # Configurato con metadata
└── versions/
    └── 001_initial_schema.py     # T11 - Migrazione iniziale

tests/unit/models/
├── test_database.py              # Test T06
├── test_user_model.py            # Test T07
├── test_api_key_model.py         # Test T08
├── test_usage_stats_model.py     # Test T09
├── test_api_token_model.py       # Test T10
└── test_migrations.py            # Test T11
```

---

## 🧪 REQUISITI TEST

### Pattern AAA (Arrange-Act-Assert)

```python
@pytest.mark.unit
async def test_create_user_valid_email_succeeds():
    # Arrange
    email = "test@example.com"
    password_hash = "hashed_password"
    
    # Act
    user = User(email=email, password_hash=password_hash)
    
    # Assert
    assert user.email == email
    assert user.password_hash == password_hash
    assert user.is_active is True
    assert user.created_at is not None
```

### Marker Pytest

```python
@pytest.mark.unit              # Logica pura
@pytest.mark.integration       # Con database
@pytest.mark.asyncio           # Funzioni async
```

### Fixtures Condivise (in conftest.py)

```python
@pytest.fixture
def db_session():
    # Sessione database per test
    
@pytest.fixture
def sample_user():
    # Utente di esempio
    
@pytest.fixture
def sample_api_key():
    # API key di esempio
```

---

## 🛡️ VINCOLI TECNICI

### SQLAlchemy Configuration

```python
from sqlalchemy import create_engine
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import sessionmaker, Session

Base = declarative_base()

engine = create_engine(
    DATABASE_URL,
    connect_args={"check_same_thread": False}  # Solo per SQLite
)

SessionLocal = sessionmaker(
    autocommit=False,
    autoflush=False,
    bind=engine,
    expire_on_commit=False
)
```

### Model Base Requirements

- Tutti i modelli ereditano da `Base`
- Usare type hints
- Configurare `__tablename__`
- Definire relationships esplicite
- Usare `ondelete="CASCADE"` per FK

### Alembic Requirements

- Importare `Base` da models in env.py
- Configurare `target_metadata = Base.metadata`
- Generare migration: `alembic revision --autogenerate -m "initial schema"`

---

## 📊 AGGIORNAMENTO PROGRESS

Dopo ogni task completato, aggiorna:
`/home/google/Sources/LucaSacchiNet/openrouter-watcher/export/progress.md`

Esempio:
```markdown
### 🗄️ Database & Models (T06-T11)

- [x] T06: Creare database.py - Completato [timestamp]
- [x] T07: Creare model User - Completato [timestamp]
- [ ] T08: Creare model ApiKey - In progress
- [ ] T09: Creare model UsageStats
- [ ] T10: Creare model ApiToken
- [ ] T11: Setup Alembic e migrazione

**Progresso sezione:** 33% (2/6 task)
```

---

## ✅ CRITERI DI ACCETTAZIONE

- [ ] T06: database.py con engine, session, get_db(), init_db()
- [ ] T07: Model User completo con relationships e constraints
- [ ] T08: Model ApiKey completo con relationships
- [ ] T09: Model UsageStats con unique constraint e defaults
- [ ] T10: Model ApiToken completo con relationships
- [ ] T11: Alembic inizializzato con migrazione funzionante
- [ ] Tutti i test passano (`pytest tests/unit/models/`)
- [ ] Coverage >= 90%
- [ ] 6 commit atomici (uno per task)
- [ ] progress.md aggiornato con tutti i task completati

---

## 🚀 COMANDO DI VERIFICA

Al termine, esegui:
```bash
cd /home/google/Sources/LucaSacchiNet/openrouter-watcher
pytest tests/unit/models/ -v --cov=src/openrouter_monitor/models
alembic upgrade head
alembic downgrade -1
alembic upgrade head
```

---

## 📝 NOTE

- Usa SEMPRE path assoluti: `/home/google/Sources/LucaSacchiNet/openrouter-watcher/`
- Segui le convenzioni in `.opencode/agents/tdd-developer.md`
- Task devono essere verificabili in < 2 ore
- Documenta bug complessi in `/docs/bug_ledger.md`
- Usa conventional commits: `feat(db): T06 create database connection`

**AGENTE:** @tdd-developer  
**INIZIA CON:** T06 - database.py