c85ec644d1
Phase 3 verified: 5/5 must-haves passed - SwipeService CRUD on data/swipe_file.json - 5 REST endpoints for Swipe File management - SwipeFile UI page with add/edit/delete/filter - topic_overrides in CalendarRequest + pipeline wiring - Swipe File picker in Genera Calendario form Requirements completed: SWP-01, SWP-02, SWP-03, SWP-04, UI-06
7.7 KiB
7.7 KiB
Requirements: PostGenerator
Defined: 2026-03-07 Core Value: Generare un calendario editoriale completo di caroselli Instagram strategicamente orchestrati, pronti per Canva Bulk Create, con un click dalla Web UI.
v1 Requirements
Calendar & Campaign Engine
- CAL-01: Sistema genera ciclo di 13 post con distribuzione Persuasion Nurturing (4 valore, 2 storytelling, 2 news, 3 riprova sociale, 1 coinvolgimento, 1 promo)
- CAL-02: Ogni post ha livello Schwartz assegnato secondo distribuzione (L5+L4=6, L3=4, L2=2, L1=1)
- CAL-03: Rotazione nicchie B2B: 50% generico, 50% verticali in rotazione configurabile
- CAL-04: Campaign Planner distribuisce post nelle 4 fasi (attira/cattura/coinvolgi/converti) nell'ordine corretto
- CAL-05: Date di pubblicazione suggerite calcolate automaticamente (configurabile frequenza)
- CAL-06: Topic generation ibrida: LLM auto-genera topic per ogni slot dato l'obiettivo campagna
- CAL-07: Override manuale topic per singoli slot prima della generazione contenuti
Format Selection
- FMT-01: Mapping automatico tipo_contenuto x livello_schwartz -> formato narrativo (PAS, AIDA, BAB, Listicle, Storytelling, Dato+Implicazione, Obiezione+Risposta)
- FMT-02: Tabella di mapping configurabile via file JSON (data/format_mapping.json)
LLM Content Generation
- LLM-01: Genera contenuto carosello completo (8 slide) tramite Claude API in formato JSON strutturato
- LLM-02: Validazione JSON output: verifica struttura, conteggio slide, campi non vuoti
- LLM-03: Retry automatico (1 tentativo) con istruzione correttiva se JSON non valido
- LLM-04: Rate limiting e backoff rispettando limiti API Claude (Tier 1)
- LLM-05: Per-item error isolation: fallimento di un singolo post non blocca il batch
- LLM-06: Provider LLM configurabile da .env (Claude come default)
Prompt System
- PRM-01: Prompt esternalizzati in file .txt nella directory /prompts/ con struttura SYSTEM/USER/OUTPUT_SCHEMA
- PRM-02: Prompt Manager carica, lista e compila prompt con variabili ({formato}, {tipo_contenuto}, {livello_schwartz}, ecc.)
- PRM-03: Almeno 5 prompt base per MVP: PAS valore, Listicle valore, BAB storytelling, AIDA promozione, Dato news
- PRM-04: System prompt scritto IN italiano (non "scrivi in italiano" dall'inglese)
- PRM-05: Prompt Editor nella Web UI: visualizza, modifica e salva file prompt
CSV & Export
- CSV-01: CSV con header completo compatibile Canva Bulk Create (33 colonne: 8 metadati + 24 slide (8 slide x 3 campi) + 1 caption_instagram)
- CSV-02: Encoding utf-8-sig (BOM) per compatibilita' Excel/Windows
- CSV-03: Campi metadato (campagna, fase, tipo, formato, funzione, livello, nicchia, data) inclusi per analisi
- CSV-04: Download CSV dalla Web UI
Image Keywords
- IMG-01: Genera keyword immagine per ogni slide come parte dell'output LLM
- IMG-02: Fetch immagini da Unsplash API (opzionale, attivo solo se API key configurata)
- IMG-03: Cache locale per evitare hit ripetuti su Unsplash (50 req/h limite free tier)
- IMG-04: Fallback: URL placeholder se Unsplash non disponibile o non configurato
Swipe File
- SWP-01: CRUD per cattura rapida topic/idee (topic, nicchia, note, data)
- SWP-02: Storage in file JSON (data/swipe_file.json)
- SWP-03: Gestione Swipe File dalla Web UI (aggiungi, lista, elimina)
- SWP-04: Possibilita' di usare topic dallo swipe file come override nella generazione calendario
Web UI
- UI-01: Dashboard con stato campagne e ultimi CSV generati
- UI-02: Form "Genera Calendario": N settimane + obiettivo campagna + nicchie -> genera ciclo completo
- UI-03: Form "Genera Singolo Post": topic + parametri manuali -> genera 1 carosello
- UI-04: Output Review: anteprima caroselli generati prima dell'export (visualizzazione slide-by-slide)
- UI-05: Prompt Editor: lista, visualizza, modifica e salva prompt
- UI-06: Swipe File Manager: aggiungi/lista/elimina idee topic
- UI-07: Pagina Impostazioni: provider LLM, API keys, nicchie attive, lingua, frequenza pubblicazione
- UI-08: Progress indicator durante generazione bulk (stato per singolo post)
Infrastructure & Deploy
- INF-01: Backend FastAPI con API REST per tutte le operazioni
- INF-02: Frontend React + Tailwind CSS (SPA servita da FastAPI)
- INF-03: Single container Docker (multi-stage build: Node build React, Python serve tutto)
- INF-04: Deploy su VPS Hostinger su subpath /postgenerator/ con nginx lab-router
- INF-05: Configurazione via .env (API keys, provider LLM, lingua, frequenza, nicchie)
- INF-06: File-based storage: prompts/, outputs/, data/ (no database)
v2 Requirements
Campaign History & Analytics
- V2-01: Storico campagne con browsing e ricerca
- V2-02: Note performance per campagna (engagement, reach manuale)
- V2-03: A/B analysis per nicchia (confronto performance tra target)
Advanced Generation
- V2-04: Generazione multi-lingua (inglese oltre italiano)
- V2-05: Template prompt per nicchia specifica (es: pas_valore_dentisti.txt)
- V2-06: Configurazione mix Persuasion Nurturing personalizzabile (non solo 13 post fissi)
Integration
- V2-07: Webhook/API per triggering generazione da n8n
- V2-08: Export diretto via Canva API (bypass CSV)
Out of Scope
| Feature | Reason |
|---|---|
| Pubblicazione diretta su Instagram | Il sistema produce CSV, la pubblicazione e' manuale via Canva |
| Scheduling automatico | Le date sono suggerite, la pianificazione e' manuale |
| Multi-utente / autenticazione | Uso personale di Michele, single-user |
| Database relazionale | File system sufficiente per MVP, complessita' non giustificata |
| Template Canva generation | I template si creano manualmente su Canva |
| Real-time analytics Instagram | Dominio diverso, richiede Instagram API con review |
| Video/Reel generation | Solo caroselli per MVP |
Traceability
| Requirement | Phase | Status |
|---|---|---|
| CAL-01 | Phase 1 | Complete |
| CAL-02 | Phase 1 | Complete |
| CAL-03 | Phase 1 | Complete |
| CAL-04 | Phase 1 | Complete |
| CAL-05 | Phase 1 | Complete |
| CAL-06 | Phase 1 | Complete |
| CAL-07 | Phase 1 | Complete |
| FMT-01 | Phase 1 | Complete |
| FMT-02 | Phase 1 | Complete |
| LLM-01 | Phase 1 | Complete |
| LLM-02 | Phase 1 | Complete |
| LLM-03 | Phase 1 | Complete |
| LLM-04 | Phase 1 | Complete |
| LLM-05 | Phase 1 | Complete |
| LLM-06 | Phase 1 | Complete |
| PRM-01 | Phase 1 | Complete |
| PRM-02 | Phase 1 | Complete |
| PRM-03 | Phase 1 | Complete |
| PRM-04 | Phase 1 | Complete |
| PRM-05 | Phase 2 | Complete |
| CSV-01 | Phase 1 | Complete |
| CSV-02 | Phase 1 | Complete |
| CSV-03 | Phase 1 | Complete |
| CSV-04 | Phase 1 | Complete |
| IMG-01 | Phase 1 | Complete |
| IMG-02 | Phase 4 | Pending |
| IMG-03 | Phase 4 | Pending |
| IMG-04 | Phase 1 | Complete |
| SWP-01 | Phase 3 | Complete |
| SWP-02 | Phase 3 | Complete |
| SWP-03 | Phase 3 | Complete |
| SWP-04 | Phase 3 | Complete |
| UI-01 | Phase 1 | Complete |
| UI-02 | Phase 1 | Complete |
| UI-03 | Phase 1 | Complete |
| UI-04 | Phase 1 | Complete |
| UI-05 | Phase 2 | Complete |
| UI-06 | Phase 3 | Complete |
| UI-07 | Phase 1 | Complete |
| UI-08 | Phase 1 | Complete |
| INF-01 | Phase 1 | Complete |
| INF-02 | Phase 1 | Complete |
| INF-03 | Phase 1 | Complete |
| INF-04 | Phase 1 | Complete |
| INF-05 | Phase 1 | Complete |
| INF-06 | Phase 1 | Complete |
Coverage:
- v1 requirements: 46 total
- Mapped to phases: 46
- Unmapped: 0
Requirements defined: 2026-03-07 Last updated: 2026-03-09 — Phase 3 requirements marked Complete