From 1dedf7cf98121121d6173742dd28fe6fc76e00c8 Mon Sep 17 00:00:00 2001 From: Michele Date: Sat, 7 Mar 2026 14:30:30 +0100 Subject: [PATCH] docs: define v1 requirements 46 requirements across 9 categories 8 requirements deferred to v2 Co-Authored-By: Claude Opus 4.6 --- .planning/REQUIREMENTS.md | 170 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 170 insertions(+) create mode 100644 .planning/REQUIREMENTS.md diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md new file mode 100644 index 0000000..ebc5009 --- /dev/null +++ b/.planning/REQUIREMENTS.md @@ -0,0 +1,170 @@ +# 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 (32 colonne: 8 metadati + 8 slide x 3 campi) +- [ ] **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 | Pending | Pending | +| CAL-02 | Pending | Pending | +| CAL-03 | Pending | Pending | +| CAL-04 | Pending | Pending | +| CAL-05 | Pending | Pending | +| CAL-06 | Pending | Pending | +| CAL-07 | Pending | Pending | +| FMT-01 | Pending | Pending | +| FMT-02 | Pending | Pending | +| LLM-01 | Pending | Pending | +| LLM-02 | Pending | Pending | +| LLM-03 | Pending | Pending | +| LLM-04 | Pending | Pending | +| LLM-05 | Pending | Pending | +| LLM-06 | Pending | Pending | +| PRM-01 | Pending | Pending | +| PRM-02 | Pending | Pending | +| PRM-03 | Pending | Pending | +| PRM-04 | Pending | Pending | +| PRM-05 | Pending | Pending | +| CSV-01 | Pending | Pending | +| CSV-02 | Pending | Pending | +| CSV-03 | Pending | Pending | +| CSV-04 | Pending | Pending | +| IMG-01 | Pending | Pending | +| IMG-02 | Pending | Pending | +| IMG-03 | Pending | Pending | +| IMG-04 | Pending | Pending | +| SWP-01 | Pending | Pending | +| SWP-02 | Pending | Pending | +| SWP-03 | Pending | Pending | +| SWP-04 | Pending | Pending | +| UI-01 | Pending | Pending | +| UI-02 | Pending | Pending | +| UI-03 | Pending | Pending | +| UI-04 | Pending | Pending | +| UI-05 | Pending | Pending | +| UI-06 | Pending | Pending | +| UI-07 | Pending | Pending | +| UI-08 | Pending | Pending | +| INF-01 | Pending | Pending | +| INF-02 | Pending | Pending | +| INF-03 | Pending | Pending | +| INF-04 | Pending | Pending | +| INF-05 | Pending | Pending | +| INF-06 | Pending | Pending | + +**Coverage:** +- v1 requirements: 46 total +- Mapped to phases: 0 +- Unmapped: 46 (will be mapped during roadmap creation) + +--- +*Requirements defined: 2026-03-07* +*Last updated: 2026-03-07 after initial definition*