Michele/postgenerator
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
1dedf7cf98121121d6173742dd28fe6fc76e00c8
postgenerator/.planning/REQUIREMENTS.md
Michele 1dedf7cf98 docs: define v1 requirements 
46 requirements across 9 categories
8 requirements deferred to v2

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-07 14:30:30 +01:00

7.7 KiB
Raw Blame History

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

Reference in New Issue View Git Blame Copy Permalink