feat(api): implement notebook management CRUD endpoints

Implement Sprint 1: Notebook Management CRUD - Add NotebookService with full CRUD operations - Add POST /api/v1/notebooks (create notebook) - Add GET /api/v1/notebooks (list with pagination) - Add GET /api/v1/notebooks/{id} (get by ID) - Add PATCH /api/v1/notebooks/{id} (partial update) - Add DELETE /api/v1/notebooks/{id} (delete) - Add Pydantic models for requests/responses - Add custom exceptions (ValidationError, NotFoundError, NotebookLMError) - Add comprehensive unit tests (31 tests, 97% coverage) - Add API integration tests (26 tests) - Fix router prefix duplication - Fix JSON serialization in error responses BREAKING CHANGE: None
2026-04-06 01:13:13 +02:00
commit 4b7a419a98
65 changed files with 10507 additions and 0 deletions
--- a/.opencode/WORKFLOW.md
+++ b/.opencode/WORKFLOW.md
@@ -0,0 +1,254 @@
+# Flusso di Lavoro Obbligatorio - getNotebooklmPower
+
+> **Regola fondamentale:** *Safety first, little often, double check*
+
+## 1. Contesto (Prima di ogni task)
+
+**OBBLIGATORIO:** Prima di implementare qualsiasi funzionalità:
+
+1. **Leggi il PRD**: Leggi sempre `/home/google/Sources/LucaSacchiNet/getNotebooklmPower/prd.md` per capire i requisiti del task corrente
+2. **Non implementare mai funzionalità non esplicitamente richieste**
+3. **Scope check**: Verifica che il task rientri nello scope definito nel PRD
+
+## 2. TDD (Test-Driven Development)
+
+**Ciclo RED → GREEN → REFACTOR:**
+
+1. **RED**: Scrivi PRIMA il test fallimentare per la singola funzionalità
+2. **GREEN**: Scrivi il codice applicativo minimo necessario per far passare il test
+3. **REFACTOR**: Migliora il codice mantenendo i test verdi
+4. **Itera** finché la funzionalità non è completa e tutti i test passano
+
+**Regole TDD:**
+- Un test per singolo comportamento
+- Testare prima i casi limite (errori, input invalidi)
+- Coverage target: ≥90%
+- Usa AAA pattern: Arrange → Act → Assert
+
+## 3. Memoria e Logging
+
+**Documentazione obbligatoria:**
+
+| Evento | Azione | File |
+|--------|--------|------|
+| Bug complesso risolto | Descrivi il bug e la soluzione | `/home/google/Sources/LucaSacchiNet/getNotebooklmPower/docs/bug_ledger.md` |
+| Decisione di design | Documenta il pattern scelto | `/home/google/Sources/LucaSacchiNet/getNotebooklmPower/docs/architecture.md` |
+| Cambio architetturale | Aggiorna le scelte architetturali | `/home/google/Sources/LucaSacchiNet/getNotebooklmPower/docs/architecture.md` |
+| Inizio task | Aggiorna progresso corrente | `/home/google/Sources/LucaSacchiNet/getNotebooklmPower/export/progress.md` |
+| Fine task | Registra completamento | `/home/google/Sources/LucaSacchiNet/getNotebooklmPower/export/progress.md` |
+| Blocco riscontrato | Documenta problema e soluzione | `/home/google/Sources/LucaSacchiNet/getNotebooklmPower/export/progress.md` |
+
+**Formato bug_ledger.md:**
+```markdown
+## YYYY-MM-DD: [Titolo Bug]
+**Sintomo:** [Descrizione sintomo]
+**Causa:** [Root cause]
+**Soluzione:** [Fix applicato]
+**Prevenzione:** [Come evitare in futuro]
+```
+
+## 4. Git Flow (Commit)
+
+**Alla fine di ogni task completato con test verdi:**
+
+1. **Commit atomico**: Un commit per singola modifica funzionale
+2. **Conventional Commits** obbligatorio:
+   ```
+   <type>(<scope>): <description>
+   
+   [optional body]
+   
+   [optional footer]
+   ```
+3. **Tipi ammessi:**
+   - `feat:` - Nuova funzionalità
+   - `fix:` - Correzione bug
+   - `docs:` - Documentazione
+   - `test:` - Test
+   - `refactor:` - Refactoring
+   - `chore:` - Manutenzione
+4. **Scope**: api, webhook, skill, notebook, source, artifact, auth, core
+5. **Documenta il commit**: Aggiorna `/home/google/Sources/LucaSacchiNet/getNotebooklmPower/export/githistory.md` con contesto e spiegazione
+
+**Esempi:**
+```bash
+feat(api): add notebook creation endpoint
+
+- Implements POST /api/v1/notebooks
+- Validates title length (max 100 chars)
+- Returns 201 with notebook details
+
+Closes #123
+```
+
+**Formato githistory.md:**
+```markdown
+## 2026-04-05 14:30 - feat(api): add notebook creation endpoint
+
+**Hash:** `a1b2c3d`
+**Autore:** @tdd-developer
+**Branch:** main
+
+### Contesto
+Necessità di creare notebook programmaticamente via API per integrazione con altri agenti.
+
+### Cosa cambia
+- Aggiunto endpoint POST /api/v1/notebooks
+- Implementata validazione titolo (max 100 chars)
+- Aggiunto test coverage 95%
+
+### Perché
+Il PRD richiede CRUD operations su notebook. Questo è il primo endpoint implementato.
+
+### Impatto
+- [x] Nuova feature
+- [ ] Breaking change
+- [ ] Modifica API
+
+### File modificati
+- src/api/routes/notebooks.py - Nuovo endpoint
+- src/services/notebook_service.py - Logica creazione
+- tests/unit/test_notebook_service.py - Test unitari
+
+### Note
+Closes #42
+```
+
+## 5. Prompt Management (Gestione Prompt)
+
+**Ogni interazione con il team di agenti deve essere documentata come prompt.**
+
+### 5.1 Salvataggio Prompt
+
+**Regola**: Ogni prompt ricevuto dall'utente deve essere salvato nella cartella `prompts/`.
+
+**Convenzione naming**:
+```
+prompts/{NUMERO}-{descrizione}.md
+```
+
+- **NUMERO**: Progressivo crescente (1, 2, 3, ...)
+- **descrizione**: Nome descrittivo in kebab-case
+
+**Esempi**:
+- `prompts/1-avvio.md` - Primo prompt, avvio progetto
+- `prompts/2-implementazione-sources.md` - Sprint fonti
+- `prompts/3-bugfix-webhook-retry.md` - Fix bug webhook
+
+### 5.2 Struttura Prompt
+
+Ogni prompt salvato deve includere:
+
+```markdown
+# {Titolo}
+
+## 📋 Comando per @sprint-lead
+{Istruzione principale}
+
+---
+
+## 🎯 Obiettivo
+{Descrizione chiara}
+
+---
+
+## 📚 Contesto
+{Background e riferimenti}
+
+---
+
+## ✅ Scope
+### In Scope
+- {Task 1}
+
+### Out of Scope
+- {Task escluso}
+
+---
+
+## 🎯 Criteri di Accettazione
+- [ ] {Criterio 1}
+
+---
+
+## 🎬 Azioni
+1. {Azione 1}
+
+---
+
+*Data: YYYY-MM-DD*
+*Priority: P{0-3}*
+*Prompt File: prompts/{NUMERO}-{nome}.md*
+```
+
+### 5.3 Aggiornamento prompts/README.md
+
+Dopo aver salvato un nuovo prompt, aggiornare `prompts/README.md`:
+
+```markdown
+| File | Descrizione | Data |
+|------|-------------|------|
+| [1-avvio.md](./1-avvio.md) | Sprint kickoff - Core API | 2026-04-06 |
+| [2-xxx.md](./2-xxx.md) | Nuova descrizione | YYYY-MM-DD |
+```
+
+## 6. Spec-Driven Development (SDD)
+
+**Prima di scrivere codice, definisci le specifiche:**
+
+### 6.1 Analisi Profonda
+- Fai domande mirate per chiarire dubbi architetturali o di business
+- Non procedere con specifiche vaghe
+- Verifica vincoli tecnici e dipendenze
+
+### 6.2 Output Richiesti (cartella `/home/google/Sources/LucaSacchiNet/getNotebooklmPower/export/`)
+
+Tutto il lavoro di specifica si concretizza in questi file:
+
+| File | Contenuto |
+|------|-----------|
+| `/home/google/Sources/LucaSacchiNet/getNotebooklmPower/export/prd.md` | Product Requirements Document (obiettivi, user stories, requisiti tecnici) |
+| `/home/google/Sources/LucaSacchiNet/getNotebooklmPower/export/architecture.md` | Scelte architetturali, stack tecnologico, diagrammi di flusso |
+| `/home/google/Sources/LucaSacchiNet/getNotebooklmPower/export/kanban.md` | Scomposizione in task minimi e verificabili (regola "little often") |
+
+### 5.3 Principio "Little Often"
+- Scomporre in task il più piccoli possibile
+- Ogni task deve essere verificabile in modo indipendente
+- Progresso incrementale, mai "big bang"
+
+### 5.4 Rigore
+- **Sii diretto, conciso e tecnico**
+- **Se una richiesta è vaga, non inventare: chiedi di precisare**
+- Nessuna supposizione non verificata
+
+## Checklist Prompt Management (per ogni nuovo task)
+
+- [ ] Ho determinato il prossimo numero progressivo (controlla `prompts/`)
+- [ ] Ho creato il file `prompts/{NUMERO}-{descrizione}.md`
+- [ ] Ho incluso comando per @sprint-lead
+- [ ] Ho definito obiettivo chiaro e success criteria
+- [ ] Ho specificato scope (in/out)
+- [ ] Ho elencato criteri di accettazione
+- [ ] Ho aggiornato `prompts/README.md` con il nuovo prompt
+- [ ] Ho salvato il prompt prima di iniziare lo sviluppo
+
+## Checklist Pre-Implementazione
+
+- [ ] Ho letto il PRD in `/home/google/Sources/LucaSacchiNet/getNotebooklmPower/prd.md`
+- [ ] Ho letto il prompt corrente in `prompts/{NUMERO}-*.md`
+- [ ] Ho compreso lo scope del task
+- [ ] Ho scritto il test fallimentare (RED)
+- [ ] Ho implementato il codice minimo (GREEN)
+- [ ] Ho refactoring mantenendo test verdi
+- [ ] Ho aggiornato `bug_ledger.md` se necessario
+- [ ] Ho aggiornato `architecture.md` se necessario
+- [ ] Ho creato un commit atomico con conventional commit
+
+## Checklist Spec-Driven (per nuove feature)
+
+- [ ] Ho analizzato in profondità i requisiti
+- [ ] Ho chiesto chiarimenti sui punti vaghi
+- [ ] Ho creato/aggiornato `/home/google/Sources/LucaSacchiNet/getNotebooklmPower/export/prd.md`
+- [ ] Ho creato/aggiornato `/home/google/Sources/LucaSacchiNet/getNotebooklmPower/export/architecture.md`
+- [ ] Ho creato/aggiornato `/home/google/Sources/LucaSacchiNet/getNotebooklmPower/export/kanban.md`
+- [ ] I task sono scomposti secondo "little often"