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/skills/project-guidelines/SKILL.md
+++ b/.opencode/skills/project-guidelines/SKILL.md
@@ -0,0 +1,268 @@
+---
+name: project-guidelines
+description: Linee guida per lo sviluppo del progetto getNotebooklmPower. Usa questa skill per comprendere l'architettura, le convenzioni di codice e il workflow di sviluppo del progetto.
+---
+
+# Project Guidelines - getNotebooklmPower
+
+## Panoramica del Progetto
+
+**getNotebooklmPower** è un'API REST che fornisce accesso programmatico a Google NotebookLM tramite interfaccia webhook.
+
+## Quick Start
+
+### Leggere Prima
+1. **Workflow**: `.opencode/WORKFLOW.md` - Flusso di lavoro obbligatorio
+2. **PRD**: `prd.md` - Requisiti prodotto
+3. **AGENTS.md**: Linee guida generali del progetto
+
+### Squadra Agenti (in `.opencode/agents/`)
+
+**Entry Point**: `@sprint-lead` (coordinatore)
+
+| Agente | Ruolo | Quando Usare |
+|--------|-------|--------------|
+| `@sprint-lead` | Coordina il team di agenti | Sempre, entry point per ogni task |
+| `@spec-architect` | Definisce specifiche e architettura | Prima di nuove feature |
+| `@api-designer` | Progetta API e modelli Pydantic | Dopo spec, prima di implementazione |
+| `@security-auditor` | Security review | Feature auth/webhook, periodicamente |
+| `@tdd-developer` | Implementazione TDD | Durante sviluppo (unit tests) |
+| `@qa-engineer` | Integration e E2E tests | Parallelo a tdd-developer |
+| `@code-reviewer` | Review qualità codice | Dopo implementazione, prima di commit |
+| `@docs-maintainer` | Aggiorna documentazione | Dopo ogni feature |
+| `@git-manager` | Gestione commit Git | A fine task |
+| `@devops-engineer` | CI/CD e deployment | Setup iniziale, quando serve |
+| `@refactoring-agent` | Miglioramento codice | Debito tecnico, manutenzione |
+
+## Flusso di Lavoro (OBBLIGATORIO)
+
+### Per Nuove Feature (Workflow Completo)
+
+```
+@sprint-lead (coordinatore)
+    ↓
+1. @spec-architect → Legge PRD, definisce specifiche
+    ↓ Crea/aggiorna: /export/prd.md, architecture.md, kanban.md
+    ↓
+2. @api-designer → Progetta API e modelli Pydantic
+    ↓ Definisce: api/models/, docs/api/endpoints.md
+    ↓
+3. @security-auditor (se auth/webhook) → Security review architettura
+    ↓ Verifica: OWASP, input validation, secrets management
+    ↓
+4. @tdd-developer (unit tests) + @qa-engineer (integration)
+    ↓ Implementa: RED → GREEN → REFACTOR
+    ↓ Coverage target: ≥90%
+    ↓
+5. @code-reviewer → Review qualità codice
+    ↓ Verifica: clean code, SOLID, type hints, docstrings
+    ↓ Output: review.md con [BLOCKING], [WARNING], [SUGGESTION]
+    ↓
+6. @docs-maintainer → Aggiorna documentazione
+    ↓ Aggiorna: README.md, SKILL.md, CHANGELOG.md
+    ↓
+7. @git-manager → Commit atomico
+    ↓ Conventional Commit + githistory.md
+    ↓
+8. @devops-engineer (se necessario) → Deploy, monitoring
+```
+
+### Per Bug Fix Rapido
+
+```
+@sprint-lead
+    ↓
+1. Leggi bug_ledger.md per pattern simili
+2. @tdd-developer → Scrive test che riproduce il bug
+3. @tdd-developer → Implementa fix
+4. @qa-engineer → Integration test
+5. @code-reviewer → Review rapida
+6. @git-manager → Commit con tipo "fix:"
+```
+
+### Per Refactoring
+
+```
+@sprint-lead
+    ↓
+1. @refactoring-agent → Identifica debito tecnico
+    ↓ Analizza: complessità, duplicazione, coverage
+    ↓
+2. @refactoring-agent + @tdd-developer → Esegue refactoring
+    ↓ Vincolo: test esistenti devono passare
+    ↓
+3. @code-reviewer → Review qualità
+4. @git-manager → Commit con tipo "refactor:"
+```
+
+## Regole Fondamentali
+
+### 1. TDD (Test-Driven Development)
+- **RED**: Scrivi test fallimentare PRIMA
+- **GREEN**: Scrivi codice minimo per passare
+- **REFACTOR**: Migliora mantenendo test verdi
+
+### 2. Spec-Driven
+- Leggi sempre `prd.md` prima di implementare
+- Non implementare funzionalità non richieste
+- Output specifiche in `/export/`
+
+### 3. Little Often
+- Task piccoli e verificabili
+- Progresso incrementale
+- Commit atomici
+
+### 4. Memoria
+- Bug complessi → `docs/bug_ledger.md`
+- Decisioni design → `docs/architecture.md`
+- Progresso task → `export/progress.md` (aggiorna inizio/fine task)
+
+### 5. Git
+- Conventional commits obbligatori
+- Commit atomici
+- Test verdi prima del commit
+
+### 6. Prompt Management (Nuovo)
+- **Ogni prompt salvato** in `prompts/{NUMERO}-{descrizione}.md`
+- **Numerazione progressiva**: 1, 2, 3, ...
+- **Template standard**: Obiettivo, Scope, Accettazione
+- **README aggiornato**: Lista tutti i prompt in `prompts/README.md`
+
+## Struttura Progetto
+
+```
+getNotebooklmPower/
+├── prompts/                      # PROMPT ARCHIVE - Tutti i prompt salvati
+│   ├── README.md                # Indice e convenzioni
+│   ├── 1-avvio.md               # Primo prompt: avvio progetto
+│   └── {N}-{descrizione}.md     # Prompt successivi (2, 3, 4...)
+├── src/                          # Codice sorgente
+│   └── notebooklm_agent/
+│       ├── api/                  # FastAPI routes
+│       │   ├── main.py          # Entry point
+│       │   ├── dependencies.py  # DI container
+│       │   ├── routes/          # Endpoint handlers
+│       │   └── models/          # Pydantic models
+│       ├── services/             # Business logic
+│       ├── core/                 # Utilities (config, exceptions, logging)
+│       ├── webhooks/             # Webhook system
+│       └── skill/                # AI Skill interface
+├── tests/                        # Test suite
+│   ├── unit/
+│   ├── integration/
+│   └── e2e/
+├── docs/                         # Documentazione utente
+│   ├── api/
+│   └── examples/
+├── .opencode/                    # Configurazione OpenCode
+│   ├── WORKFLOW.md              # Flusso di lavoro
+│   ├── agents/                  # Configurazioni agenti (11 agenti)
+│   ├── skills/                  # Skill condivise
+│   └── templates/               # Template per spec-driven workflow
+├── prd.md                        # Product Requirements
+├── AGENTS.md                     # Linee guida generali
+├── SKILL.md                      # Skill definizione
+├── CHANGELOG.md                  # Release notes
+└── CONTRIBUTING.md               # Guida contribuzione
+```
+
+## Convenzioni di Codice
+
+### Python
+- Python 3.10+
+- PEP 8
+- Type hints obbligatori
+- Docstrings Google-style
+- Line length: 100 caratteri
+
+### Testing
+- pytest
+- Coverage ≥90%
+- AAA pattern (Arrange-Act-Assert)
+- Mock per dipendenze esterne
+
+### Commit
+```
+<type>(<scope>): <description>
+
+[body]
+
+[footer]
+```
+
+**Tipi:** feat, fix, docs, test, refactor, chore, ci, style
+**Scope:** api, webhook, skill, notebook, source, artifact, auth, core
+
+## Risorse
+
+| File/Directory | Scopo |
+|----------------|-------|
+| `prompts/` | **ARCHIVIO PROMPT** - Tutti i prompt salvati con numerazione progressiva |
+| `prompts/README.md` | Indice e convenzioni per la gestione prompt |
+| `prd.md` | Requisiti prodotto |
+| `AGENTS.md` | Linee guida progetto |
+| `.opencode/WORKFLOW.md` | Flusso di lavoro dettagliato |
+| `.opencode/agents/` | Configurazioni agenti (11 agenti) |
+| `docs/bug_ledger.md` | Log bug risolti |
+| `docs/architecture.md` | Decisioni architetturali |
+| `export/progress.md` | Tracciamento progresso task |
+| `export/githistory.md` | Storico commit con contesto |
+| `CHANGELOG.md` | Changelog |
+| `CONTRIBUTING.md` | Guida contribuzione |
+
+## Comandi Utili
+
+```bash
+# Test
+uv run pytest                    # Tutti i test
+uv run pytest --cov             # Con coverage
+uv run pytest tests/unit/        # Solo unit test
+
+# Qualità
+uv run ruff check src/          # Linting
+uv run ruff format src/         # Formattazione
+uv run mypy src/                # Type checking
+
+# Pre-commit
+uv run pre-commit run --all-files
+
+# Server
+uv run fastapi dev src/notebooklm_agent/api/main.py
+```
+
+## Checklist
+
+### Per Nuovi Prompt (prima di iniziare)
+- [ ] Ho determinato il prossimo numero (controlla `ls prompts/`)
+- [ ] Ho creato `prompts/{NUMERO}-{descrizione}.md` con template standard
+- [ ] Ho incluso comando per @sprint-lead
+- [ ] Ho definito obiettivo chiaro e criteri successo
+- [ ] Ho aggiornato `prompts/README.md` con il nuovo prompt
+
+### Pre-Implementazione (coordinato da @sprint-lead)
+- [ ] @sprint-lead ha attivato il workflow corretto
+- [ ] Ho letto il prompt corrente in `prompts/{NUMERO}-*.md`
+- [ ] @spec-architect ha definito specifiche in `/export/`
+- [ ] Ho letto `prd.md` e `export/architecture.md`
+- [ ] Ho compreso lo scope e accettazione criteria
+
+### Durante Implementazione
+- [ ] @api-designer ha definito contratti API (se applicabile)
+- [ ] @security-auditor ha approvato design (se auth/webhook)
+- [ ] Test scritto prima (RED)
+- [ ] Codice minimo (GREEN)
+- [ ] Refactoring (REFACTOR)
+- [ ] @qa-engineer ha scritto integration tests (parallelo)
+
+### Post-Implementazione
+- [ ] Tutti i test passano (unit + integration)
+- [ ] Coverage ≥90%
+- [ ] @code-reviewer ha approvato (no [BLOCKING])
+- [ ] @docs-maintainer ha aggiornato documentazione
+- [ ] `CHANGELOG.md` aggiornato
+- [ ] @git-manager ha creato commit con conventional commits
+- [ ] @sprint-lead ha aggiornato `export/progress.md`
+
+---
+
+*Per dettagli su flusso di lavoro, vedere `.opencode/WORKFLOW.md`*