lucasacchi/openrouter-watcher
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
abe9fc166b004f8b9b05e39a2430c01c49ce4683
openrouter-watcher/prd.md
Luca Sacchi Ricciardi 75f40acb17 feat(setup): T01 create project directory structure 
- Create src/openrouter_monitor/ package structure
- Create models/, routers/, services/, utils/ subpackages
- Create tests/unit/ and tests/integration/ structure
- Create alembic/, docs/, scripts/ directories
- Add test_project_structure.py with 13 unit tests
- All tests passing (13/13)

Refs: T01
2026-04-07 09:44:41 +02:00

8.7 KiB
Raw Blame History

Product Requirements Document (PRD)

OpenRouter API Key Monitor

1. Panoramica

1.1 Descrizione

OpenRouter API Key Monitor e un applicazione web multi-utente che permette agli utenti di monitorare l utilizzo delle loro API key della piattaforma OpenRouter. L applicazione raccoglie statistiche d uso, le persiste in un database SQLite e fornisce sia un interfaccia web che un API programmatica per l accesso ai dati.

1.2 Obiettivi

  • Fornire una dashboard centralizzata per il monitoraggio delle API key OpenRouter
  • Permettere a piu utenti di gestire le proprie chiavi in modo indipendente
  • Offrire API programmatica per integrazioni esterne
  • Persistere i dati storici per analisi nel tempo

1.3 Target Utenti

  • Sviluppatori che utilizzano API OpenRouter
  • Team che gestiscono multiple API key
  • Utenti che necessitano di reportistica sull utilizzo

2. Requisiti Funzionali

2.1 Gestione Utenti (Multi-utente)

2.1.1 Registrazione

  • F-001: Gli utenti devono potersi registrare con email e password
  • F-002: La password deve essere salvata in modo sicuro (hash)
  • F-003: Email deve essere univoca nel sistema
  • F-004: Validazione formato email

2.1.2 Autenticazione

  • F-005: Login con email e password
  • F-006: Gestione sessione utente (JWT o session-based)
  • F-007: Logout funzionante
  • F-008: Protezione route autenticate

2.1.3 Profilo Utente

  • F-009: Visualizzazione profilo personale
  • F-010: Modifica password
  • F-011: Eliminazione account con conferma

2.2 Gestione API Key

2.2.1 CRUD API Key

  • F-012: Aggiungere nuova API key OpenRouter
  • F-013: Visualizzare lista API key dell utente
  • F-014: Modificare nome/descrizione API key
  • F-015: Eliminare API key
  • F-016: API key devono essere cifrate nel database

2.2.2 Validazione

  • F-017: Verifica validita API key con chiamata test a OpenRouter
  • F-018: Visualizzare stato attivo/inattivo per ogni key

2.3 Monitoraggio e Statistiche

2.3.1 Raccolta Dati

  • F-019: Sincronizzazione automatica statistiche da OpenRouter API
  • F-020: Storico utilizzo (richieste, token, costi)
  • F-021: Aggregazione dati per modello LLM utilizzato

2.3.2 Dashboard

  • F-022: Vista panoramica utilizzo totale
  • F-023: Grafico utilizzo nel tempo (ultimi 30 giorni)
  • F-024: Distribuzione utilizzo per modello
  • F-025: Costi totali e medi
  • F-026: Numero richieste totali e giornaliere medie

2.3.3 Report Dettagliati

  • F-027: Filtraggio per intervallo date
  • F-028: Filtraggio per API key specifica
  • F-029: Filtraggio per modello
  • F-030: Esportazione dati (CSV/JSON)

2.4 API Pubblica

2.4.1 Autenticazione API

  • F-031: Generazione API token per accesso programmatico
  • F-032: Revoca API token
  • F-033: Autenticazione via Bearer token

2.4.2 Endpoint

  • F-034: GET /api/v1/stats - statistiche aggregate (solo lettura)
  • F-035: GET /api/v1/usage - dati di utilizzo dettagliati (solo lettura)
  • F-036: GET /api/v1/keys - lista API key con statistiche (solo lettura)
  • F-037: Rate limiting su API pubblica

2.4.3 Risposte

  • F-038: Formato JSON standardizzato
  • F-039: Gestione errori con codici HTTP appropriati
  • F-040: Paginazione per risultati grandi

3. Requisiti Non Funzionali

3.1 Performance

  • NF-001: Tempo di risposta web < 2 secondi
  • NF-002: API response time < 500ms
  • NF-003: Supporto per almeno 100 utenti concorrenti

3.2 Sicurezza

  • NF-004: Tutte le API key cifrate in database (AES-256)
  • NF-005: Password hash con bcrypt/Argon2
  • NF-006: HTTPS obbligatorio in produzione
  • NF-007: Protezione CSRF
  • NF-008: Rate limiting su endpoint di autenticazione
  • NF-009: SQL injection prevention (query parameterizzate)
  • NF-010: XSS prevention

3.3 Affidabilita

  • NF-011: Backup automatico database SQLite
  • NF-012: Gestione errori graceful degradation
  • NF-013: Logging operazioni critiche

3.4 Usabilita

  • NF-014: Interfaccia responsive (mobile-friendly)
  • NF-015: Tema chiaro/scuro
  • NF-016: Messaggi di errore chiari

3.5 Manutenibilita

  • NF-017: Codice documentato
  • NF-018: Test coverage >= 90%
  • NF-019: Struttura modulare

4. Architettura Tecnica

4.1 Stack Tecnologico

  • Backend: Python 3.11+ con FastAPI
  • Frontend: HTML + HTMX / React (opzionale)
  • Database: SQLite
  • ORM: SQLAlchemy
  • Autenticazione: JWT
  • Task Background: APScheduler / Celery (opzionale)

4.2 Struttura Database

Tabella: users

  • id (PK, INTEGER)
  • email (UNIQUE, TEXT)
  • password_hash (TEXT)
  • created_at (TIMESTAMP)
  • updated_at (TIMESTAMP)
  • is_active (BOOLEAN)

Tabella: api_keys

  • id (PK, INTEGER)
  • user_id (FK, INTEGER)
  • name (TEXT)
  • key_encrypted (TEXT)
  • is_active (BOOLEAN)
  • created_at (TIMESTAMP)
  • last_used_at (TIMESTAMP)

Tabella: usage_stats

  • id (PK, INTEGER)
  • api_key_id (FK, INTEGER)
  • date (DATE)
  • model (TEXT)
  • requests_count (INTEGER)
  • tokens_input (INTEGER)
  • tokens_output (INTEGER)
  • cost (DECIMAL)
  • created_at (TIMESTAMP)

Tabella: api_tokens

  • id (PK, INTEGER)
  • user_id (FK, INTEGER)
  • token_hash (TEXT)
  • name (TEXT)
  • last_used_at (TIMESTAMP)
  • created_at (TIMESTAMP)
  • is_active (BOOLEAN)

4.3 Integrazione OpenRouter

  • API Endpoint: https://openrouter.ai/api/v1/
  • Endpoint utilizzati:
    • /auth/key - per validazione key
    • /credits - per controllo crediti
    • (future estensioni per usage stats quando disponibili)

5. Interfaccia Utente

5.1 Pagine Web

5.1.1 Pubbliche

  • Login (/login) - Form di accesso
  • Registrazione (/register) - Form di registrazione

5.1.2 Autenticate

  • Dashboard (/dashboard) - Panoramica utilizzo
  • API Keys (/keys) - Gestione API key
  • Statistiche (/stats) - Report dettagliati
  • Profilo (/profile) - Gestione account
  • API Tokens (/tokens) - Gestione token API

5.2 Componenti UI

5.2.1 Dashboard

  • Card riepilogative (richieste totali, costi, etc.)
  • Grafici utilizzo temporale
  • Tabella modelli piu utilizzati

5.2.2 Gestione API Key

  • Tabella con nome, stato, ultimo utilizzo
  • Form aggiunta/modifica
  • Bottone test validita
  • Bottone eliminazione con conferma

5.2.3 Statistiche

  • Filtri per data, key, modello
  • Tabella dettagliata
  • Bottone esportazione

6. API Endpoints (Dettaglio)

6.1 Web Routes (HTML)

  • GET / - redirect a /dashboard o /login
  • GET/POST /login
  • GET/POST /register
  • GET /logout
  • GET /dashboard (protetta)
  • GET /keys (protetta)
  • GET /stats (protetta)
  • GET /profile (protetta)
  • GET /tokens (protetta)

6.2 API Routes (JSON)

  • POST /api/auth/login

  • POST /api/auth/register

  • POST /api/auth/logout

  • GET /api/v1/stats (auth: Bearer token)

  • GET /api/v1/usage (auth: Bearer token)

  • GET /api/v1/keys (auth: Bearer token)

7. Cron e Background Tasks

7.1 Sincronizzazione Dati

  • Task: Sync Usage Data
  • Frequenza: Ogni ora
  • Azione: Recupera statistiche da OpenRouter per ogni key attiva
  • Persistenza: Salva in usage_stats

7.2 Validazione API Key

  • Task: Validate Keys
  • Frequenza: Giornaliera
  • Azione: Verifica validita di ogni key, aggiorna stato

7.3 Cleanup

  • Task: Cleanup Old Data
  • Frequenza: Settimanale
  • Azione: Rimuove dati piu vecchi di 1 anno (configurabile)

8. Configurazione

8.1 Variabili d Ambiente

  • DATABASE_URL - path database SQLite
  • SECRET_KEY - chiave per JWT
  • ENCRYPTION_KEY - chiave per cifratura API key
  • OPENROUTER_API_URL - URL base API OpenRouter
  • SYNC_INTERVAL_MINUTES - intervallo sincronizzazione
  • MAX_API_KEYS_PER_USER - limite key per utente
  • RATE_LIMIT_REQUESTS - limite richieste API
  • RATE_LIMIT_WINDOW - finestra rate limit (secondi)

8.2 File Configurazione

  • config.yaml (opzionale) - override env vars

9. Deployment

9.1 Requisiti

  • Python 3.11+
  • SQLite
  • (Opzionale) Reverse proxy (nginx/traefik)

9.2 Installazione

  1. Clone repository
  2. pip install -r requirements.txt
  3. Configura variabili d ambiente
  4. Esegui migrazioni: alembic upgrade head
  5. Avvia: uvicorn main:app

9.3 Docker (Opzionale)

  • Dockerfile fornito
  • docker-compose.yml per stack completo

10. Roadmap

Fase 1 (MVP)

  • Autenticazione utenti
  • CRUD API key
  • Dashboard base
  • API lettura dati

Fase 2

  • Grafici avanzati
  • Esportazione dati
  • Notifiche (email)
  • Rate limiting avanzato

Fase 3

  • Supporto multi-team
  • RBAC (Ruoli)
  • Webhook
  • Mobile app

11. Note

  • L applicazione e progettata per essere self-hosted
  • I dati rimangono locali (SQLite)
  • L integrazione con OpenRouter richiede API key valide
  • Le API key degli utenti sono sempre cifrate nel database
Reference in New Issue View Git Blame Copy Permalink