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
This commit is contained in:
Luca Sacchi Ricciardi
224
prompts/1-avvio.md
Normal file
224
prompts/1-avvio.md
Normal file
@@ -0,0 +1,224 @@
|
||||
# Sprint Kickoff: Implementazione Core API - Notebook Management
|
||||
|
||||
## 📋 Comando per @sprint-lead
|
||||
|
||||
@sprint-lead Avvia il workflow completo per implementare la gestione notebook CRUD.
|
||||
Questo è lo sprint iniziale per rendere l'API funzionante.
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Obiettivo Sprint
|
||||
|
||||
**Implementare l'API REST completa per la gestione dei notebook NotebookLM**,
|
||||
permettendo agli utenti di creare, leggere, aggiornare ed eliminare notebook via API.
|
||||
|
||||
**Success Criteria**:
|
||||
- Endpoint CRUD `/api/v1/notebooks` funzionanti con test ≥90% coverage
|
||||
- Documentazione SKILL.md aggiornata con esempi curl funzionanti
|
||||
- CI/CD pipeline verde su GitHub Actions
|
||||
|
||||
---
|
||||
|
||||
## 📚 Contesto & Background
|
||||
|
||||
### Stato Attuale
|
||||
- ✅ Setup progetto completo (struttura, tooling, CI/CD)
|
||||
- ✅ API base funzionante (health check, dependencies)
|
||||
- ✅ Core package (config, exceptions, logging)
|
||||
- ✅ Squadra agenti configurata e pronta
|
||||
|
||||
### Documentazione Riferimento
|
||||
- **PRD**: `prd.md` - Sezione 4.1 (Requisiti Notebook Management)
|
||||
- **Workflow**: `.opencode/WORKFLOW.md`
|
||||
- **Skill**: `.opencode/skills/project-guidelines/SKILL.md`
|
||||
- **API Design**: Da definire (@api-designer)
|
||||
- **NotebookLM-py docs**: https://github.com/teng-lin/notebooklm-py
|
||||
|
||||
### Requisiti dal PRD (REQ-001)
|
||||
- `POST /api/v1/notebooks` - Creare notebook
|
||||
- `GET /api/v1/notebooks` - Listare notebook (con pagination)
|
||||
- `GET /api/v1/notebooks/{id}` - Ottenere dettagli notebook
|
||||
- `PATCH /api/v1/notebooks/{id}` - Aggiornare notebook
|
||||
- `DELETE /api/v1/notebooks/{id}` - Eliminare notebook
|
||||
|
||||
---
|
||||
|
||||
## ✅ Scope (Incluso)
|
||||
|
||||
### In Scope
|
||||
1. **API Design** (@api-designer)
|
||||
- Modelli Pydantic (NotebookCreate, NotebookUpdate, NotebookResponse)
|
||||
- Query parameters per pagination (limit, offset)
|
||||
- Error response standard
|
||||
|
||||
2. **Implementazione** (@tdd-developer + @qa-engineer)
|
||||
- Service layer: `NotebookService` con integrazione notebooklm-py
|
||||
- API routes: CRUD endpoints in `api/routes/notebooks.py`
|
||||
- Unit tests: ≥90% coverage
|
||||
- Integration tests: Mock HTTP client
|
||||
|
||||
3. **Security** (@security-auditor)
|
||||
- API key validation su tutti gli endpoint
|
||||
- Input validation (Pydantic)
|
||||
- Rate limiting headers
|
||||
|
||||
4. **Documentazione** (@docs-maintainer)
|
||||
- Aggiornare SKILL.md con esempi curl
|
||||
- Aggiornare CHANGELOG.md
|
||||
- Creare `docs/api/endpoints.md`
|
||||
|
||||
5. **Quality Gates** (@code-reviewer)
|
||||
- Code review completa
|
||||
- Type hints check
|
||||
- No code smells
|
||||
|
||||
### Out of Scope (Prossimi Sprint)
|
||||
- Gestione fonti (sources) - Sprint 2
|
||||
- Chat functionality - Sprint 3
|
||||
- Content generation - Sprint 4
|
||||
- Webhook system - Sprint 5
|
||||
- E2E tests con NotebookLM reale (richiede auth)
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ Vincoli & Constraints
|
||||
|
||||
1. **Tecnici**
|
||||
- Python 3.10+ con type hints obbligatori
|
||||
- FastAPI + Pydantic v2
|
||||
- Coverage ≥90%
|
||||
- Async/await per I/O bound operations
|
||||
|
||||
2. **Architetturali**
|
||||
- Layering: API → Service → Core
|
||||
- Dependency injection
|
||||
- Nessuna logica business nei router
|
||||
|
||||
3. **NotebookLM-py**
|
||||
- Usare `NotebookLMClient.from_storage()` per auth
|
||||
- Gestire rate limiting con retry
|
||||
- Wrappare eccezioni in custom exceptions
|
||||
|
||||
4. **Tempo**
|
||||
- Stima: 3-5 giorni (complexity: media)
|
||||
- Daily standup virtuale ogni mattina
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Criteri di Accettazione (Definition of Done)
|
||||
|
||||
### Per @sprint-lead - Checklist Finale:
|
||||
- [ ] **@spec-architect**: Specifiche in `export/prd.md` e `export/architecture.md`
|
||||
- [ ] **@api-designer**: Modelli Pydantic in `api/models/`, API docs in `docs/api/`
|
||||
- [ ] **@security-auditor**: Security review completata, no [BLOCKING] issues
|
||||
- [ ] **@tdd-developer**: Unit tests passanti, coverage ≥90%
|
||||
- [ ] **@qa-engineer**: Integration tests passanti
|
||||
- [ ] **@code-reviewer**: Review approvata, no [BLOCKING] issues
|
||||
- [ ] **@docs-maintainer**: SKILL.md e CHANGELOG.md aggiornati
|
||||
- [ ] **@git-manager**: Commit atomici con conventional commits
|
||||
- [ ] **CI/CD**: Pipeline verde su GitHub Actions
|
||||
|
||||
### Test Manuale di Verifica:
|
||||
```bash
|
||||
# Avvia server
|
||||
uv run fastapi dev src/notebooklm_agent/api/main.py
|
||||
|
||||
# Test CRUD
|
||||
curl -X POST http://localhost:8000/api/v1/notebooks \
|
||||
-H "X-API-Key: test-key" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"title": "Test Notebook"}'
|
||||
|
||||
curl http://localhost:8000/api/v1/notebooks \
|
||||
-H "X-API-Key: test-key"
|
||||
|
||||
curl http://localhost:8000/api/v1/notebooks/{id} \
|
||||
-H "X-API-Key: test-key"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 Metriche Target
|
||||
|
||||
| Metrica | Target | Attuale |
|
||||
|---------|--------|---------|
|
||||
| API Endpoints | 5 CRUD | 1 (health) |
|
||||
| Test Coverage | ≥90% | ~60% |
|
||||
| Lines of Code | ~500 | ~200 |
|
||||
| Docs Completeness | 100% | 20% |
|
||||
| CI/CD Status | 🟢 Green | 🟡 Partial |
|
||||
|
||||
---
|
||||
|
||||
## 🎬 Azioni Immediate per @sprint-lead
|
||||
|
||||
1. **Ora**: Attiva @spec-architect per analisi dettagliata
|
||||
- Leggere PRD sezione 4.1
|
||||
- Creare `export/kanban.md` con task breakdown
|
||||
- Definire interfacce NotebookService
|
||||
|
||||
2. **Quando @spec-architect completa**: Attiva @api-designer
|
||||
- Progettare modelli Pydantic
|
||||
- Definire schema OpenAPI
|
||||
- Documentare esempi
|
||||
|
||||
3. **Poi**: Attiva @tdd-developer + @qa-engineer in parallelo
|
||||
- RED: Scrivere test
|
||||
- GREEN: Implementare codice
|
||||
- REFACTOR: Migliorare
|
||||
|
||||
4. **Infine**: Quality gates e deploy
|
||||
- @code-reviewer → @docs-maintainer → @git-manager
|
||||
|
||||
---
|
||||
|
||||
## 📝 Note Aggiuntive
|
||||
|
||||
### Pattern da Seguire
|
||||
```python
|
||||
# Service Layer
|
||||
class NotebookService:
|
||||
async def create(self, data: NotebookCreate) -> Notebook:
|
||||
# Business logic qui
|
||||
pass
|
||||
|
||||
# API Layer
|
||||
@router.post("/")
|
||||
async def create_notebook(
|
||||
data: NotebookCreate,
|
||||
service: NotebookService = Depends(get_notebook_service)
|
||||
):
|
||||
return await service.create(data)
|
||||
```
|
||||
|
||||
### Gestione Errori
|
||||
Usare gerarchia eccezioni in `core/exceptions.py`:
|
||||
- `ValidationError` → HTTP 400
|
||||
- `NotFoundError` → HTTP 404
|
||||
- `AuthenticationError` → HTTP 401
|
||||
- `NotebookLMError` → HTTP 502 (bad gateway)
|
||||
|
||||
### Rate Limiting NotebookLM
|
||||
Il client notebooklm-py ha rate limiting aggressivo.
|
||||
Implementare retry con exponential backoff in service layer.
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Call to Action
|
||||
|
||||
**@sprint-lead**:
|
||||
1. Inizializza `export/progress.md` con questo sprint
|
||||
2. Attiva **@spec-architect** per la fase di analisi
|
||||
3. Programma daily standup per domani mattina
|
||||
4. Monitora progresso e gestisci blocchi
|
||||
|
||||
**Team**: Seguire il workflow in `.opencode/WORKFLOW.md` e le linee guida in `.opencode/skills/project-guidelines/SKILL.md`.
|
||||
|
||||
**Obiettivo**: Notebook CRUD API production-ready entro venerdì! 🚀
|
||||
|
||||
---
|
||||
|
||||
*Data Inizio Sprint: 2026-04-06*
|
||||
*Sprint Lead: @sprint-lead*
|
||||
*Priority: P0 (Foundation)*
|
||||
*Prompt File: prompts/1-avvio.md*
|
||||
Reference in New Issue
Block a user