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
parent 849a65d4d9
commit 75f40acb17
27 changed files with 3094 additions and 0 deletions
--- a/export/architecture.md
+++ b/export/architecture.md
--- a/export/kanban.md
+++ b/export/kanban.md
@@ -0,0 +1,242 @@
+# Kanban Board
+
+## OpenRouter API Key Monitor - Fase 1 (MVP)
+
+---
+
+## Legenda
+
+- **Complessità**: S (Small < 1h) | M (Medium 1-2h) | L (Large 2-4h, deve essere scomposto)
+- **Priorità**: P0 (Bloccante) | P1 (Alta) | P2 (Media) | P3 (Bassa)
+- **Dipendenze**: Task che devono essere completati prima
+
+---
+
+## 📋 BACKLOG / TODO
+
+### 🔧 Setup Progetto (Fondamentale)
+
+| ID | Task | Compl. | Priorità | Dipendenze | Note |
+|----|------|--------|----------|------------|------|
+| T01 | Creare struttura cartelle progetto | S | P0 | - | `app/`, `tests/`, `alembic/` |
+| T02 | Inizializzare virtual environment | S | P0 | - | Python 3.11+ |
+| T03 | Creare requirements.txt con dipendenze | S | P0 | T02 | FastAPI, SQLAlchemy, etc. |
+| T04 | Setup file configurazione (.env, config.py) | S | P0 | T03 | Variabili d'ambiente |
+| T05 | Configurare pytest e struttura test | S | P0 | T02 | pytest.ini, conftest.py |
+
+### 🗄️ Database & Models
+
+| ID | Task | Compl. | Priorità | Dipendenze | Note |
+|----|------|--------|----------|------------|------|
+| T06 | Creare database.py (connection & session) | S | P0 | T04 | SQLAlchemy engine |
+| T07 | Creare model User (SQLAlchemy) | M | P0 | T06 | Tabella users |
+| T08 | Creare model ApiKey (SQLAlchemy) | M | P0 | T07 | Tabella api_keys |
+| T09 | Creare model UsageStats (SQLAlchemy) | M | P1 | T08 | Tabella usage_stats |
+| T10 | Creare model ApiToken (SQLAlchemy) | M | P1 | T07 | Tabella api_tokens |
+| T11 | Setup Alembic e creare migrazione iniziale | M | P0 | T07-T10 | `alembic init` + revision |
+
+### 🔐 Servizi di Sicurezza
+
+| ID | Task | Compl. | Priorità | Dipendenze | Note |
+|----|------|--------|----------|------------|------|
+| T12 | Implementare EncryptionService (AES-256) | M | P0 | - | cryptography library |
+| T13 | Implementare password hashing (bcrypt) | S | P0 | - | passlib |
+| T14 | Implementare JWT utilities | S | P0 | T12 | python-jose |
+| T15 | Implementare API token generation | S | P1 | T13 | SHA-256 hash |
+| T16 | Scrivere test per servizi di encryption | M | P1 | T12-T15 | Unit tests |
+
+### 👤 Autenticazione Utenti
+
+| ID | Task | Compl. | Priorità | Dipendenze | Note |
+|----|------|--------|----------|------------|------|
+| T17 | Creare Pydantic schemas auth (register/login) | S | P0 | T07 | Validazione input |
+| T18 | Implementare endpoint POST /api/auth/register | M | P0 | T13, T17 | Creazione utente |
+| T19 | Implementare endpoint POST /api/auth/login | M | P0 | T14, T18 | JWT generation |
+| T20 | Implementare endpoint POST /api/auth/logout | S | P0 | T19 | Token invalidation |
+| T21 | Creare dipendenza get_current_user | S | P0 | T19 | FastAPI dependency |
+| T22 | Scrivere test per auth endpoints | M | P0 | T18-T21 | pytest |
+
+### 🔑 Gestione API Keys
+
+| ID | Task | Compl. | Priorità | Dipendenze | Note |
+|----|------|--------|----------|------------|------|
+| T23 | Creare Pydantic schemas per API keys | S | P0 | T08 | CRUD schemas |
+| T24 | Implementare POST /api/keys (create) | M | P0 | T12, T21, T23 | Con cifratura |
+| T25 | Implementare GET /api/keys (list) | S | P0 | T21, T23 | Lista key utente |
+| T26 | Implementare PUT /api/keys/{id} (update) | S | P0 | T21, T24 | Modifica nome/stato |
+| T27 | Implementare DELETE /api/keys/{id} | S | P0 | T21 | Eliminazione |
+| T28 | Implementare servizio validazione key | M | P1 | T24 | Chiamata a OpenRouter |
+| T29 | Scrivere test per API keys CRUD | M | P0 | T24-T27 | pytest |
+
+### 📊 Dashboard & Statistiche (Base)
+
+| ID | Task | Compl. | Priorità | Dipendenze | Note |
+|----|------|--------|----------|------------|------|
+| T30 | Creare Pydantic schemas per stats | S | P1 | T09 | Response models |
+| T31 | Implementare servizio aggregazione stats | M | P1 | T09 | Query SQL |
+| T32 | Implementare endpoint GET /api/stats | M | P1 | T21, T31 | Stats aggregate |
+| T33 | Implementare endpoint GET /api/usage | M | P1 | T21, T31 | Dettaglio usage |
+| T34 | Scrivere test per stats endpoints | M | P1 | T32, T33 | pytest |
+
+### 🌐 Public API v1 (Esterna)
+
+| ID | Task | Compl. | Priorità | Dipendenze | Note |
+|----|------|--------|----------|------------|------|
+| T35 | Creare dipendenza verify_api_token | S | P0 | T15 | Bearer token auth |
+| T36 | Implementare POST /api/tokens (generate) | M | P0 | T15, T21 | API token management |
+| T37 | Implementare GET /api/tokens (list) | S | P0 | T21 | Lista token utente |
+| T38 | Implementare DELETE /api/tokens/{id} | S | P0 | T21 | Revoca token |
+| T39 | Implementare GET /api/v1/stats | M | P0 | T31, T35 | Public endpoint |
+| T40 | Implementare GET /api/v1/usage | M | P0 | T33, T35 | Public endpoint |
+| T41 | Implementare GET /api/v1/keys | M | P0 | T25, T35 | Public endpoint |
+| T42 | Implementare rate limiting su public API | M | P1 | T35-T41 | slowapi |
+| T43 | Scrivere test per public API | M | P1 | T36-T42 | pytest |
+
+### 🎨 Frontend Web (HTMX)
+
+| ID | Task | Compl. | Priorità | Dipendenze | Note |
+|----|------|--------|----------|------------|------|
+| T44 | Setup Jinja2 templates e static files | S | P0 | - | Configurazione FastAPI |
+| T45 | Creare base.html (layout principale) | S | P0 | T44 | Template base |
+| T46 | Creare login.html | S | P0 | T45 | Form login |
+| T47 | Creare register.html | S | P0 | T45 | Form registrazione |
+| T48 | Implementare router /login (GET/POST) | M | P0 | T46 | Web endpoint |
+| T49 | Implementare router /register (GET/POST) | M | P0 | T47 | Web endpoint |
+| T50 | Creare dashboard.html | M | P1 | T45 | Panoramica |
+| T51 | Implementare router /dashboard | S | P1 | T50, T21 | Web endpoint |
+| T52 | Creare keys.html | M | P1 | T45 | Gestione API keys |
+| T53 | Implementare router /keys | S | P1 | T52, T24 | Web endpoint |
+| T54 | Aggiungere HTMX per azioni CRUD | M | P2 | T52 | AJAX senza reload |
+
+### ⚙️ Background Tasks
+
+| ID | Task | Compl. | Priorità | Dipendenze | Note |
+|----|------|--------|----------|------------|------|
+| T55 | Configurare APScheduler | S | P2 | - | Setup scheduler |
+| T56 | Implementare task sync usage stats | M | P2 | T09, T28 | Ogni ora |
+| T57 | Implementare task validazione key | M | P2 | T28 | Ogni giorno |
+| T58 | Integrare scheduler in startup app | S | P2 | T55-T57 | Lifespan event |
+
+### 🔒 Sicurezza & Hardening
+
+| ID | Task | Compl. | Priorità | Dipendenze | Note |
+|----|------|--------|----------|------------|------|
+| T59 | Implementare security headers middleware | S | P1 | - | XSS, CSRF protection |
+| T60 | Implementare rate limiting auth endpoints | S | P1 | T18, T19 | slowapi |
+| T61 | Implementare CORS policy | S | P1 | - | Configurazione |
+| T62 | Audit: verificare cifratura API keys | S | P1 | T12 | Verifica sicurezza |
+| T63 | Audit: verificare SQL injection prevention | S | P1 | T06 | Parameterized queries |
+
+### 🧪 Testing & QA
+
+| ID | Task | Compl. | Priorità | Dipendenze | Note |
+|----|------|--------|----------|------------|------|
+| T64 | Scrivere test unitari per models | S | P1 | T07-T10 | pytest |
+| T65 | Scrivere test integrazione auth flow | M | P1 | T18-T22 | End-to-end |
+| T66 | Scrivere test integrazione API keys | M | P1 | T24-T29 | End-to-end |
+| T67 | Verificare coverage >= 90% | S | P1 | T64-T66 | pytest-cov |
+| T68 | Eseguire security scan dipendenze | S | P2 | - | safety, pip-audit |
+
+### 📝 Documentazione
+
+| ID | Task | Compl. | Priorità | Dipendenze | Note |
+|----|------|--------|----------|------------|------|
+| T69 | Scrivere README.md completo | M | P2 | - | Setup, usage |
+| T70 | Documentare API con OpenAPI | S | P2 | - | FastAPI auto-docs |
+| T71 | Creare esempi curl per API | S | P3 | T39-T41 | Usage examples |
+
+### 🚀 Deployment
+
+| ID | Task | Compl. | Priorità | Dipendenze | Note |
+|----|------|--------|----------|------------|------|
+| T72 | Creare Dockerfile | M | P2 | - | Containerization |
+| T73 | Creare docker-compose.yml | S | P2 | T72 | Stack completo |
+| T74 | Scrivere script avvio produzione | S | P2 | T72 | Entry point |
+
+---
+
+## 🚧 IN PROGRESS
+
+*Task attualmente in lavorazione*
+
+| ID | Task | Assegnato | Iniziato | Note |
+|----|------|-----------|----------|------|
+| - | - | - | - | - |
+
+---
+
+## 👀 REVIEW
+
+*Task completati, in attesa di review*
+
+| ID | Task | Assegnato | Completato | Reviewer | Note |
+|----|------|-----------|------------|----------|------|
+| - | - | - | - | - | - |
+
+---
+
+## ✅ DONE
+
+*Task completati e verificati*
+
+| ID | Task | Assegnato | Completato | Note |
+|----|------|-----------|------------|------|
+| - | - | - | - | - |
+
+---
+
+## 📊 Statistiche
+
+| Stato | Conteggio | Percentuale |
+|-------|-----------|-------------|
+| TODO | 74 | 100% |
+| IN PROGRESS | 0 | 0% |
+| REVIEW | 0 | 0% |
+| DONE | 0 | 0% |
+| **Totale** | **74** | **0%** |
+
+---
+
+## 🎯 Milestone Fase 1 (MVP)
+
+### Blocker Tasks (Devono essere completati prima)
+- T01-T05: Setup progetto
+- T06-T11: Database setup
+- T12-T16: Servizi sicurezza
+
+### Core Features MVP
+- ✅ Autenticazione utenti (registrazione/login/logout JWT)
+- ✅ CRUD API key (cifrate AES-256)
+- ✅ Dashboard statistiche base (aggregazione)
+- ✅ API pubblica autenticata (sola lettura)
+
+### Definition of Done (DoD)
+- [ ] Tutti i test passano (`pytest`)
+- [ ] Coverage >= 90% (`pytest --cov`)
+- [ ] Security headers implementati
+- [ ] Rate limiting attivo
+- [ ] API documentate (OpenAPI)
+- [ ] README completo
+- [ ] Nessun errore linting (`ruff check`)
+
+---
+
+## 🔗 Dipendenze Chiave
+
+```
+T01-T05 (Setup)
+    └── T06-T11 (Database)
+            ├── T12-T16 (Security)
+            │       ├── T17-T22 (Auth)
+            │       ├── T23-T29 (API Keys)
+            │       │       └── T28 (Validation)
+            │       │               └── T55-T58 (Background Tasks)
+            │       └── T30-T34 (Stats)
+            │               └── T35-T43 (Public API)
+            └── T44-T54 (Frontend)
+```
+
+---
+
+*Ultimo aggiornamento: 2024-01-15*  
+*Versione: 1.0*
--- a/export/progress.md
+++ b/export/progress.md
@@ -0,0 +1,196 @@
+# Progress Tracking
+
+## Feature: Fase 1 - MVP OpenRouter API Key Monitor
+
+---
+
+## 📊 Stato Generale
+
+| Metrica | Valore |
+|---------|--------|
+| **Stato** | 🟡 In Progress |
+| **Progresso** | 1% |
+| **Data Inizio** | 2024-04-07 |
+| **Data Target** | TBD |
+| **Task Totali** | 74 |
+| **Task Completati** | 1 |
+| **Task In Progress** | 1 |
+
+---
+
+## 🎯 Obiettivi Fase 1 (MVP)
+
+### Core Features
+1. ✅ **Autenticazione utenti** (registrazione/login JWT)
+2. ✅ **CRUD API key** (cifrate AES-256)
+3. ✅ **Dashboard statistiche base** (aggregazione dati)
+4. ✅ **API pubblica autenticata** (sola lettura)
+
+### Requisiti Non Funzionali
+- [ ] Tempo di risposta web < 2 secondi
+- [ ] API response time < 500ms
+- [ ] Supporto 100+ utenti concorrenti
+- [ ] Test coverage >= 90%
+- [ ] Sicurezza: AES-256, bcrypt, JWT, rate limiting
+
+---
+
+## 📋 Task Pianificate
+
+### 🔧 Setup Progetto (T01-T05) - 1/5 completati
+- [x] T01: Creare struttura cartelle progetto (2024-04-07)
+- [ ] T02: Inizializzare virtual environment
+- [ ] T03: Creare requirements.txt con dipendenze
+- [ ] T04: Setup file configurazione (.env, config.py)
+- [ ] T05: Configurare pytest e struttura test
+
+### 🗄️ Database & Models (T06-T11) - 0/6 completati
+- [ ] T06: Creare database.py (connection & session)
+- [ ] T07: Creare model User (SQLAlchemy)
+- [ ] T08: Creare model ApiKey (SQLAlchemy)
+- [ ] T09: Creare model UsageStats (SQLAlchemy)
+- [ ] T10: Creare model ApiToken (SQLAlchemy)
+- [ ] T11: Setup Alembic e creare migrazione iniziale
+
+### 🔐 Servizi di Sicurezza (T12-T16) - 0/5 completati
+- [ ] T12: Implementare EncryptionService (AES-256)
+- [ ] T13: Implementare password hashing (bcrypt)
+- [ ] T14: Implementare JWT utilities
+- [ ] T15: Implementare API token generation
+- [ ] T16: Scrivere test per servizi di encryption
+
+### 👤 Autenticazione Utenti (T17-T22) - 0/6 completati
+- [ ] T17: Creare Pydantic schemas auth (register/login)
+- [ ] T18: Implementare endpoint POST /api/auth/register
+- [ ] T19: Implementare endpoint POST /api/auth/login
+- [ ] T20: Implementare endpoint POST /api/auth/logout
+- [ ] T21: Creare dipendenza get_current_user
+- [ ] T22: Scrivere test per auth endpoints
+
+### 🔑 Gestione API Keys (T23-T29) - 0/7 completati
+- [ ] T23: Creare Pydantic schemas per API keys
+- [ ] T24: Implementare POST /api/keys (create)
+- [ ] T25: Implementare GET /api/keys (list)
+- [ ] T26: Implementare PUT /api/keys/{id} (update)
+- [ ] T27: Implementare DELETE /api/keys/{id}
+- [ ] T28: Implementare servizio validazione key
+- [ ] T29: Scrivere test per API keys CRUD
+
+### 📊 Dashboard & Statistiche (T30-T34) - 0/5 completati
+- [ ] T30: Creare Pydantic schemas per stats
+- [ ] T31: Implementare servizio aggregazione stats
+- [ ] T32: Implementare endpoint GET /api/stats
+- [ ] T33: Implementare endpoint GET /api/usage
+- [ ] T34: Scrivere test per stats endpoints
+
+### 🌐 Public API v1 (T35-T43) - 0/9 completati
+- [ ] T35: Creare dipendenza verify_api_token
+- [ ] T36: Implementare POST /api/tokens (generate)
+- [ ] T37: Implementare GET /api/tokens (list)
+- [ ] T38: Implementare DELETE /api/tokens/{id}
+- [ ] T39: Implementare GET /api/v1/stats
+- [ ] T40: Implementare GET /api/v1/usage
+- [ ] T41: Implementare GET /api/v1/keys
+- [ ] T42: Implementare rate limiting su public API
+- [ ] T43: Scrivere test per public API
+
+### 🎨 Frontend Web (T44-T54) - 0/11 completati
+- [ ] T44: Setup Jinja2 templates e static files
+- [ ] T45: Creare base.html (layout principale)
+- [ ] T46: Creare login.html
+- [ ] T47: Creare register.html
+- [ ] T48: Implementare router /login (GET/POST)
+- [ ] T49: Implementare router /register (GET/POST)
+- [ ] T50: Creare dashboard.html
+- [ ] T51: Implementare router /dashboard
+- [ ] T52: Creare keys.html
+- [ ] T53: Implementare router /keys
+- [ ] T54: Aggiungere HTMX per azioni CRUD
+
+### ⚙️ Background Tasks (T55-T58) - 0/4 completati
+- [ ] T55: Configurare APScheduler
+- [ ] T56: Implementare task sync usage stats
+- [ ] T57: Implementare task validazione key
+- [ ] T58: Integrare scheduler in startup app
+
+### 🔒 Sicurezza & Hardening (T59-T63) - 0/5 completati
+- [ ] T59: Implementare security headers middleware
+- [ ] T60: Implementare rate limiting auth endpoints
+- [ ] T61: Implementare CORS policy
+- [ ] T62: Audit: verificare cifratura API keys
+- [ ] T63: Audit: verificare SQL injection prevention
+
+### 🧪 Testing & QA (T64-T68) - 0/5 completati
+- [ ] T64: Scrivere test unitari per models
+- [ ] T65: Scrivere test integrazione auth flow
+- [ ] T66: Scrivere test integrazione API keys
+- [ ] T67: Verificare coverage >= 90%
+- [ ] T68: Eseguire security scan dipendenze
+
+### 📝 Documentazione (T69-T71) - 0/3 completati
+- [ ] T69: Scrivere README.md completo
+- [ ] T70: Documentare API con OpenAPI
+- [ ] T71: Creare esempi curl per API
+
+### 🚀 Deployment (T72-T74) - 0/3 completati
+- [ ] T72: Creare Dockerfile
+- [ ] T73: Creare docker-compose.yml
+- [ ] T74: Scrivere script avvio produzione
+
+---
+
+## 📈 Grafico Progresso
+
+```
+Progresso MVP Fase 1
+
+TODO       [████████████████████████████████████████] 100%
+IN PROGRESS [                                        ] 0%
+REVIEW      [                                        ] 0%
+DONE        [                                        ] 0%
+
+0%        25%        50%        75%       100%
+```
+
+---
+
+## 🔥 Blockers
+
+*Nessun blocker attivo*
+
+| ID | Descrizione | Impatto | Data Apertura | Data Risoluzione |
+|----|-------------|---------|---------------|------------------|
+| - | - | - | - | - |
+
+---
+
+## 📝 Decisioni Log
+
+| Data | Decisione | Motivazione | Stato |
+|------|-----------|-------------|-------|
+| 2024-01-15 | Stack: FastAPI + SQLite + HTMX | MVP semplice, zero-config | ✅ Approvata |
+| 2024-01-15 | Cifratura: AES-256-GCM | Requisito sicurezza PRD | ✅ Approvata |
+| 2024-01-15 | Auth: JWT con cookie | Semplice per web + API | ✅ Approvata |
+
+---
+
+## 🐛 Issue Tracking
+
+*Issue riscontrati durante lo sviluppo*
+
+| ID | Descrizione | Severità | Stato | Assegnato | Note |
+|----|-------------|----------|-------|-----------|------|
+| - | - | - | - | - | - |
+
+---
+
+## 📚 Risorse
+
+- PRD: `/home/google/Sources/LucaSacchiNet/openrouter-watcher/prd.md`
+- Architettura: `/home/google/Sources/LucaSacchiNet/openrouter-watcher/export/architecture.md`
+- Kanban: `/home/google/Sources/LucaSacchiNet/openrouter-watcher/export/kanban.md`
+
+---
+
+*Ultimo aggiornamento: 2024-01-15*  
+*Prossimo aggiornamento: Alla fine del primo sprint*