postgenerator/.planning/milestones/v1-REQUIREMENTS.md

# Requirements Archive: v1 MVP Content Marketing Automation

**Archived:** 2026-03-09
**Status:** SHIPPED

This is the archived requirements specification for v1.
For current requirements, see `.planning/REQUIREMENTS.md` (created for next milestone).

---

**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

- [x] **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)
- [x] **CAL-02**: Ogni post ha livello Schwartz assegnato secondo distribuzione (L5+L4=6, L3=4, L2=2, L1=1)
- [x] **CAL-03**: Rotazione nicchie B2B: 50% generico, 50% verticali in rotazione configurabile
- [x] **CAL-04**: Campaign Planner distribuisce post nelle 4 fasi (attira/cattura/coinvolgi/converti) nell'ordine corretto
- [x] **CAL-05**: Date di pubblicazione suggerite calcolate automaticamente (configurabile frequenza)
- [x] **CAL-06**: Topic generation ibrida: LLM auto-genera topic per ogni slot dato l'obiettivo campagna
- [x] **CAL-07**: Override manuale topic per singoli slot prima della generazione contenuti

### Format Selection

- [x] **FMT-01**: Mapping automatico tipo_contenuto x livello_schwartz -> formato narrativo (PAS, AIDA, BAB, Listicle, Storytelling, Dato+Implicazione, Obiezione+Risposta)
- [x] **FMT-02**: Tabella di mapping configurabile via file JSON (data/format_mapping.json)

### LLM Content Generation

- [x] **LLM-01**: Genera contenuto carosello completo (8 slide) tramite Claude API in formato JSON strutturato
- [x] **LLM-02**: Validazione JSON output: verifica struttura, conteggio slide, campi non vuoti
- [x] **LLM-03**: Retry automatico (1 tentativo) con istruzione correttiva se JSON non valido
- [x] **LLM-04**: Rate limiting e backoff rispettando limiti API Claude (Tier 1)
- [x] **LLM-05**: Per-item error isolation: fallimento di un singolo post non blocca il batch
- [x] **LLM-06**: Provider LLM configurabile da .env (Claude come default)

### Prompt System

- [x] **PRM-01**: Prompt esternalizzati in file .txt nella directory /prompts/ con struttura SYSTEM/USER/OUTPUT_SCHEMA
- [x] **PRM-02**: Prompt Manager carica, lista e compila prompt con variabili ({formato}, {tipo_contenuto}, {livello_schwartz}, ecc.)
- [x] **PRM-03**: Almeno 5 prompt base per MVP: PAS valore, Listicle valore, BAB storytelling, AIDA promozione, Dato news
- [x] **PRM-04**: System prompt scritto IN italiano (non "scrivi in italiano" dall'inglese)
- [x] **PRM-05**: Prompt Editor nella Web UI: visualizza, modifica e salva file prompt

### CSV & Export

- [x] **CSV-01**: CSV con header completo compatibile Canva Bulk Create (33 colonne: 8 metadati + 24 slide (8 slide x 3 campi) + 1 caption_instagram)
- [x] **CSV-02**: Encoding utf-8-sig (BOM) per compatibilita' Excel/Windows
- [x] **CSV-03**: Campi metadato (campagna, fase, tipo, formato, funzione, livello, nicchia, data) inclusi per analisi
- [x] **CSV-04**: Download CSV dalla Web UI

### Image Keywords

- [x] **IMG-01**: Genera keyword immagine per ogni slide come parte dell'output LLM
- [x] **IMG-02**: Fetch immagini da Unsplash API (opzionale, attivo solo se API key configurata)
- [x] **IMG-03**: Cache locale per evitare hit ripetuti su Unsplash (50 req/h limite free tier)
- [x] **IMG-04**: Fallback: URL placeholder se Unsplash non disponibile o non configurato

### Swipe File

- [x] **SWP-01**: CRUD per cattura rapida topic/idee (topic, nicchia, note, data)
- [x] **SWP-02**: Storage in file JSON (data/swipe_file.json)
- [x] **SWP-03**: Gestione Swipe File dalla Web UI (aggiungi, lista, elimina)
- [x] **SWP-04**: Possibilita' di usare topic dallo swipe file come override nella generazione calendario

### Web UI

- [x] **UI-01**: Dashboard con stato campagne e ultimi CSV generati
- [x] **UI-02**: Form "Genera Calendario": N settimane + obiettivo campagna + nicchie -> genera ciclo completo
- [x] **UI-03**: Form "Genera Singolo Post": topic + parametri manuali -> genera 1 carosello
- [x] **UI-04**: Output Review: anteprima caroselli generati prima dell'export (visualizzazione slide-by-slide)
- [x] **UI-05**: Prompt Editor: lista, visualizza, modifica e salva prompt
- [x] **UI-06**: Swipe File Manager: aggiungi/lista/elimina idee topic
- [x] **UI-07**: Pagina Impostazioni: provider LLM, API keys, nicchie attive, lingua, frequenza pubblicazione
- [x] **UI-08**: Progress indicator durante generazione bulk (stato per singolo post)

### Infrastructure & Deploy

- [x] **INF-01**: Backend FastAPI con API REST per tutte le operazioni
- [x] **INF-02**: Frontend React + Tailwind CSS (SPA servita da FastAPI)
- [x] **INF-03**: Single container Docker (multi-stage build: Node build React, Python serve tutto)
- [x] **INF-04**: Deploy su VPS Hostinger su subpath /postgenerator/ con nginx lab-router
- [x] **INF-05**: Configurazione via .env (API keys, provider LLM, lingua, frequenza, nicchie)
- [x] **INF-06**: File-based storage: prompts/, outputs/, data/ (no database)

## v2 Requirements (Deferred)

### 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..07 | Phase 1 | Complete |
| FMT-01..02 | Phase 1 | Complete |
| LLM-01..06 | Phase 1 | Complete |
| PRM-01..04 | Phase 1 | Complete |
| PRM-05 | Phase 2 | Complete |
| CSV-01..04 | Phase 1 | Complete |
| IMG-01, IMG-04 | Phase 1 | Complete |
| IMG-02..03 | Phase 4 | Complete |
| SWP-01..04 | Phase 3 | Complete |
| UI-01..04, UI-07..08 | Phase 1 | Complete |
| UI-05 | Phase 2 | Complete |
| UI-06 | Phase 3 | Complete |
| INF-01..06 | Phase 1 | Complete |

**Coverage:**
- v1 requirements: 46 total
- Shipped: 46
- Dropped: 0
- Adjusted: 0

---

## Milestone Summary

**Shipped:** 46 of 46 v1 requirements
**Adjusted:** None — all requirements implemented as originally specified
**Dropped:** None

---
*Archived: 2026-03-09 as part of v1 milestone completion*