From fed78f0e43b20d9c91543b518ba87e44e4a7877e Mon Sep 17 00:00:00 2001 From: Michele Date: Sat, 7 Mar 2026 14:37:14 +0100 Subject: [PATCH] docs: create roadmap (4 phases) Phases: 1. Core Generation Pipeline: 36 requirements (infra + calendar + LLM + CSV + UI) 2. Prompt Control + Output Review: 2 requirements 3. Organization Layer: 5 requirements (swipe file) 4. Enrichment: 3 requirements (Unsplash) All 46 v1 requirements mapped to phases. Co-Authored-By: Claude Opus 4.6 --- .planning/REQUIREMENTS.md | 98 +++++++++++++++++++------------------- .planning/ROADMAP.md | 99 +++++++++++++++++++++++++++++++++++++++ .planning/STATE.md | 65 +++++++++++++++++++++++++ 3 files changed, 213 insertions(+), 49 deletions(-) create mode 100644 .planning/ROADMAP.md create mode 100644 .planning/STATE.md diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index ebc5009..083d12d 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -113,58 +113,58 @@ | 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 | +| CAL-01 | Phase 1 | Pending | +| CAL-02 | Phase 1 | Pending | +| CAL-03 | Phase 1 | Pending | +| CAL-04 | Phase 1 | Pending | +| CAL-05 | Phase 1 | Pending | +| CAL-06 | Phase 1 | Pending | +| CAL-07 | Phase 1 | Pending | +| FMT-01 | Phase 1 | Pending | +| FMT-02 | Phase 1 | Pending | +| LLM-01 | Phase 1 | Pending | +| LLM-02 | Phase 1 | Pending | +| LLM-03 | Phase 1 | Pending | +| LLM-04 | Phase 1 | Pending | +| LLM-05 | Phase 1 | Pending | +| LLM-06 | Phase 1 | Pending | +| PRM-01 | Phase 1 | Pending | +| PRM-02 | Phase 1 | Pending | +| PRM-03 | Phase 1 | Pending | +| PRM-04 | Phase 1 | Pending | +| PRM-05 | Phase 2 | Pending | +| CSV-01 | Phase 1 | Pending | +| CSV-02 | Phase 1 | Pending | +| CSV-03 | Phase 1 | Pending | +| CSV-04 | Phase 1 | Pending | +| IMG-01 | Phase 1 | Pending | +| IMG-02 | Phase 4 | Pending | +| IMG-03 | Phase 4 | Pending | +| IMG-04 | Phase 1 | Pending | +| SWP-01 | Phase 3 | Pending | +| SWP-02 | Phase 3 | Pending | +| SWP-03 | Phase 3 | Pending | +| SWP-04 | Phase 3 | Pending | +| UI-01 | Phase 1 | Pending | +| UI-02 | Phase 1 | Pending | +| UI-03 | Phase 1 | Pending | +| UI-04 | Phase 1 | Pending | +| UI-05 | Phase 2 | Pending | +| UI-06 | Phase 3 | Pending | +| UI-07 | Phase 1 | Pending | +| UI-08 | Phase 1 | Pending | +| INF-01 | Phase 1 | Pending | +| INF-02 | Phase 1 | Pending | +| INF-03 | Phase 1 | Pending | +| INF-04 | Phase 1 | Pending | +| INF-05 | Phase 1 | Pending | +| INF-06 | Phase 1 | Pending | **Coverage:** - v1 requirements: 46 total -- Mapped to phases: 0 -- Unmapped: 46 (will be mapped during roadmap creation) +- Mapped to phases: 46 +- Unmapped: 0 --- *Requirements defined: 2026-03-07* -*Last updated: 2026-03-07 after initial definition* +*Last updated: 2026-03-07 — traceability mapped after roadmap creation* diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md new file mode 100644 index 0000000..30c5d34 --- /dev/null +++ b/.planning/ROADMAP.md @@ -0,0 +1,99 @@ +# Roadmap: PostGenerator + +## Overview + +PostGenerator trasforma framework strategici di content marketing (Persuasion Nurturing + livelli Schwartz) in caroselli Instagram pronti per Canva Bulk Create. Il percorso di sviluppo segue una logica precisa: prima costruire la pipeline di generazione end-to-end funzionante (Fase 1), poi dare il controllo sulla qualita' dell'output tramite editor di prompt e anteprima (Fase 2), poi aggiungere gli strumenti organizzativi per un workflow sostenibile (Fase 3), infine arricchire con integrazioni opzionali (Fase 4). Ogni fase consegna un sistema verificabile e utilizzabile indipendentemente dalla successiva. + +## Phases + +**Phase Numbering:** +- Integer phases (1, 2, 3): Planned milestone work +- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED) + +Decimal phases appear between their surrounding integers in numeric order. + +- [ ] **Phase 1: Core Generation Pipeline** - Infrastruttura + pipeline calendario → LLM → CSV funzionante end-to-end +- [ ] **Phase 2: Prompt Control + Output Review** - Editor prompt via UI e anteprima caroselli prima dell'export +- [ ] **Phase 3: Organization Layer** - Swipe File e gestione storico campagne per workflow sostenibile +- [ ] **Phase 4: Enrichment** - Integrazione Unsplash, context injection da Swipe File, polish UI + +## Phase Details + +### Phase 1: Core Generation Pipeline +**Goal**: L'utente puo' generare un calendario di 13 caroselli completi e scaricare un CSV valido per Canva Bulk Create con un click dalla Web UI deployata su VPS. +**Depends on**: Nothing (first phase) +**Requirements**: INF-01, INF-02, INF-03, INF-04, INF-05, INF-06, CAL-01, CAL-02, CAL-03, CAL-04, CAL-05, CAL-06, CAL-07, FMT-01, FMT-02, LLM-01, LLM-02, LLM-03, LLM-04, LLM-05, LLM-06, PRM-01, PRM-02, PRM-03, PRM-04, CSV-01, CSV-02, CSV-03, CSV-04, IMG-01, IMG-04, UI-01, UI-02, UI-03, UI-04, UI-07, UI-08 +**Success Criteria** (what must be TRUE): + 1. L'utente accede a `https://lab.mlhub.it/postgenerator/` e la Web UI si carica senza errori + 2. L'utente inserisce obiettivo campagna e settimane desiderate, clicca "Genera Calendario" e vede un progress indicator per ogni post in generazione + 3. Al termine della generazione, l'utente puo' scaricare un file CSV che si apre correttamente in Excel con caratteri italiani intatti e header che corrispondono esattamente ai placeholder del template Canva + 4. Il CSV contiene esattamente 13 righe di contenuto con la distribuzione Persuasion Nurturing corretta (4 valore, 2 storytelling, 2 news, 3 riprova, 1 coinvolgimento, 1 promo) e i livelli Schwartz assegnati + 5. Se la generazione di un singolo post fallisce (errore API), gli altri post del batch sono salvati e scaricabili; il post fallito e' marcato come errore senza bloccare il resto +**Plans**: TBD + +Plans: +- [ ] 01-01: Infrastructure setup — FastAPI + React SPA single container, Docker multi-stage build, subpath /postgenerator/ configurato correttamente (root_path via Uvicorn, Vite base, nginx lab-router) +- [ ] 01-02: Core services — CalendarService (distribuzione 13 post, Schwartz, nicchie, date), FormatSelector (mapping tipo x Schwartz → formato), PromptService base (carica .txt, compile variabili), file-based storage layout +- [ ] 01-03: LLM pipeline — LLMService (Claude API, retry, backoff, rate limit, JSON validation), CSVBuilder (header Canva locked, utf-8-sig encoding), per-item error isolation +- [ ] 01-04: Web UI base — Dashboard, form Genera Calendario, form Genera Singolo Post, Output Review (anteprima slide-by-slide), Impostazioni, progress indicator bulk + +--- + +### Phase 2: Prompt Control + Output Review +**Goal**: L'utente puo' modificare i prompt direttamente dalla Web UI senza toccare il codice, rigenerare singoli post insoddisfacenti, e rivedere l'anteprima completa di ogni carosello prima di esportare il CSV. +**Depends on**: Phase 1 +**Requirements**: PRM-05, UI-05 +**Success Criteria** (what must be TRUE): + 1. L'utente apre la sezione Prompt Editor, vede la lista dei file .txt disponibili, clicca su un prompt e ne modifica il contenuto direttamente nel browser + 2. Dopo aver salvato un prompt modificato, l'utente genera un nuovo post e il contenuto prodotto riflette le modifiche apportate al prompt + 3. L'utente puo' rigenerare un singolo post dell'anteprima senza rigenerare l'intero batch +**Plans**: TBD + +Plans: +- [ ] 02-01: PromptService CRUD completo — endpoint FastAPI per lista/leggi/scrivi file prompt, validazione variabili richieste, UI Prompt Editor (lista, textarea, salva) +- [ ] 02-02: Per-item regeneration — endpoint rigenera singolo post per ID slot, aggiornamento anteprima senza rigenerare il batch, integrazione con Output Review UI + +--- + +### Phase 3: Organization Layer +**Goal**: L'utente puo' salvare rapidamente idee e topic interessanti in un Swipe File consultabile, e ritrovare e ri-scaricare calendari generati in sessioni precedenti. +**Depends on**: Phase 1 +**Requirements**: SWP-01, SWP-02, SWP-03, SWP-04, UI-06 +**Success Criteria** (what must be TRUE): + 1. L'utente aggiunge un'idea al Swipe File con topic, nicchia e note; l'idea appare immediatamente nella lista e persiste al riavvio del container + 2. L'utente puo' eliminare una voce dal Swipe File e la lista si aggiorna + 3. L'utente puo' selezionare un topic dallo Swipe File come override per uno slot specifico prima di avviare la generazione del calendario +**Plans**: TBD + +Plans: +- [ ] 03-01: SwipeService — CRUD JSON collections (swipe_file.json), endpoint FastAPI lista/aggiungi/elimina, UI Swipe File Manager (aggiungi, lista, elimina) +- [ ] 03-02: Swipe-to-calendar integration — meccanismo per selezionare topic da Swipe File come override slot nel form Genera Calendario (CAL-07 + SWP-04) + +--- + +### Phase 4: Enrichment +**Goal**: L'utente con API key Unsplash configurata vede URL immagini reali nel CSV invece di placeholder; l'utente puo' passare voci dello Swipe File come contesto durante la generazione topic per risultati piu' aderenti alle proprie osservazioni. +**Depends on**: Phase 3 +**Requirements**: IMG-02, IMG-03 +**Success Criteria** (what must be TRUE): + 1. Se l'API key Unsplash e' configurata nelle Impostazioni, il CSV esportato contiene URL immagini reali (non placeholder) per ogni slide + 2. Se Unsplash non e' configurato o supera il rate limit, il CSV usa URL placeholder senza errori e senza bloccare l'export + 3. La cache locale evita chiamate duplicate a Unsplash per keyword identiche nella stessa sessione +**Plans**: TBD + +Plans: +- [ ] 04-01: Unsplash integration — UnsplashService via httpx async, cache JSON locale, fallback trasparente a placeholder, integrazione nel pipeline CSV quando API key presente + +--- + +## Progress + +**Execution Order:** +Phases execute in numeric order: 1 → 2 → 3 → 4 + +| Phase | Plans Complete | Status | Completed | +|-------|----------------|--------|-----------| +| 1. Core Generation Pipeline | 0/4 | Not started | - | +| 2. Prompt Control + Output Review | 0/2 | Not started | - | +| 3. Organization Layer | 0/2 | Not started | - | +| 4. Enrichment | 0/1 | Not started | - | diff --git a/.planning/STATE.md b/.planning/STATE.md new file mode 100644 index 0000000..357cd8e --- /dev/null +++ b/.planning/STATE.md @@ -0,0 +1,65 @@ +# Project State + +## Project Reference + +See: .planning/PROJECT.md (updated 2026-03-07) + +**Core value:** Generare un calendario di 13 caroselli Instagram strategicamente orchestrati, pronti per Canva Bulk Create, con un click dalla Web UI. +**Current focus:** Phase 1 — Core Generation Pipeline + +## Current Position + +Phase: 1 of 4 (Core Generation Pipeline) +Plan: 0 of 4 in current phase +Status: Ready to plan +Last activity: 2026-03-07 — Roadmap e STATE.md inizializzati dopo requirements e research + +Progress: [░░░░░░░░░░] 0% + +## Performance Metrics + +**Velocity:** +- Total plans completed: 0 +- Average duration: — min +- Total execution time: 0 hours + +**By Phase:** + +| Phase | Plans | Total | Avg/Plan | +|-------|-------|-------|----------| +| - | - | - | - | + +**Recent Trend:** +- Last 5 plans: — +- Trend: — + +*Updated after each plan completion* + +## Accumulated Context + +### Decisions + +Decisions are logged in PROJECT.md Key Decisions table. +Recent decisions affecting current work: + +- [Setup]: Tutti i 9 critical pitfalls identificati dalla research sono concentrati in Phase 1 — affrontarli subito e' la priorita' assoluta +- [Setup]: FastAPI root_path SOLO via Uvicorn (--root-path), mai nel costruttore FastAPI() — altrimenti doppio path bug +- [Setup]: CSV encoding = utf-8-sig (BOM) sempre; CANVA_FIELDS locked come costante prima di qualsiasi codice di generazione +- [Setup]: Prompt di sistema scritti IN italiano (non inglese + "scrivi in italiano") +- [Setup]: Per-item error isolation dal primo loop di generazione — un fallimento non blocca il batch + +### Pending Todos + +None yet. + +### Blockers/Concerns + +- [Phase 1]: Canva field schema (placeholder names) non ancora definiti — devono essere locked come CANVA_FIELDS prima di scrivere codice generazione o LLM output schema +- [Phase 1]: Validare token usage reale per batch 13 post con claude-sonnet-4-5 contro limite Tier 1 (8,000 OTPM) — necessario inter-request delay configurabile (2-3s) +- [Phase 1]: Baseline qualita' prompt italiani da validare dopo prima generazione reale + +## Session Continuity + +Last session: 2026-03-07 +Stopped at: Roadmap creato, STATE.md inizializzato — pronto per /gsd:plan-phase 1 +Resume file: None