docs(01): create phase plan
Phase 01: Core Generation Pipeline - 4 plan(s) in 3 wave(s) - Wave 1: 01-01 (infra) + 01-02 (core services) parallel - Wave 2: 01-03 (LLM pipeline + API routers) - Wave 3: 01-04 (Web UI) with human-verify checkpoint - Ready for execution
This commit is contained in:
Michele
328
.planning/phases/01-core-generation-pipeline/01-04-PLAN.md
Normal file
328
.planning/phases/01-core-generation-pipeline/01-04-PLAN.md
Normal file
@@ -0,0 +1,328 @@
|
||||
---
|
||||
phase: 01-core-generation-pipeline
|
||||
plan: 04
|
||||
type: execute
|
||||
wave: 3
|
||||
depends_on: ["01-01", "01-02", "01-03"]
|
||||
files_modified:
|
||||
- frontend/src/App.tsx
|
||||
- frontend/src/pages/Dashboard.tsx
|
||||
- frontend/src/pages/GenerateCalendar.tsx
|
||||
- frontend/src/pages/GenerateSingle.tsx
|
||||
- frontend/src/pages/OutputReview.tsx
|
||||
- frontend/src/pages/Settings.tsx
|
||||
- frontend/src/components/Layout.tsx
|
||||
- frontend/src/components/Sidebar.tsx
|
||||
- frontend/src/components/PostCard.tsx
|
||||
- frontend/src/components/SlideViewer.tsx
|
||||
- frontend/src/components/ProgressIndicator.tsx
|
||||
- frontend/src/components/BadgePN.tsx
|
||||
- frontend/src/components/BadgeSchwartz.tsx
|
||||
- frontend/src/api/client.ts
|
||||
- frontend/src/api/hooks.ts
|
||||
- frontend/src/types.ts
|
||||
autonomous: false
|
||||
|
||||
must_haves:
|
||||
truths:
|
||||
- "L'utente vede una Dashboard con link a Genera Calendario, Genera Singolo Post, e Impostazioni"
|
||||
- "L'utente compila il form Genera Calendario (obiettivo + settimane) e clicca Genera — vede progress indicator per ogni post"
|
||||
- "L'utente vede i 13 post generati come griglia di card con badge colorati PN e Schwartz"
|
||||
- "L'utente clicca su una card e vede le slide con navigazione frecce laterali + caption Instagram"
|
||||
- "L'utente puo' modificare il testo di una slide inline (click to edit) e le modifiche si riflettono nel CSV"
|
||||
- "L'utente scarica il CSV cliccando un pulsante Download CSV"
|
||||
- "Post falliti appaiono come card errore con pulsante Riprova"
|
||||
- "Il pulsante Genera e' disabilitato se API key non configurata, con messaggio che rimanda a Impostazioni"
|
||||
- "La pagina Impostazioni permette di configurare API key, modello LLM, nicchie, frequenza"
|
||||
artifacts:
|
||||
- path: "frontend/src/pages/Dashboard.tsx"
|
||||
provides: "Dashboard con stato e navigazione"
|
||||
min_lines: 30
|
||||
- path: "frontend/src/pages/GenerateCalendar.tsx"
|
||||
provides: "Form generazione calendario con progress indicator"
|
||||
min_lines: 80
|
||||
- path: "frontend/src/pages/OutputReview.tsx"
|
||||
provides: "Griglia card post con espansione slide, edit inline, download CSV"
|
||||
min_lines: 100
|
||||
- path: "frontend/src/pages/Settings.tsx"
|
||||
provides: "Form configurazione con API key, modello, nicchie"
|
||||
min_lines: 50
|
||||
- path: "frontend/src/components/PostCard.tsx"
|
||||
provides: "Card singolo post con badge PN e Schwartz"
|
||||
min_lines: 40
|
||||
- path: "frontend/src/components/SlideViewer.tsx"
|
||||
provides: "Navigazione slide con frecce laterali"
|
||||
min_lines: 50
|
||||
- path: "frontend/src/api/hooks.ts"
|
||||
provides: "TanStack Query hooks per tutte le API calls"
|
||||
contains: "useQuery"
|
||||
key_links:
|
||||
- from: "frontend/src/api/hooks.ts"
|
||||
to: "/postgenerator/api"
|
||||
via: "apiFetch con endpoint completo"
|
||||
pattern: "apiFetch"
|
||||
- from: "frontend/src/pages/GenerateCalendar.tsx"
|
||||
to: "frontend/src/api/hooks.ts"
|
||||
via: "useMutation per POST /api/generate/bulk"
|
||||
pattern: "useMutation"
|
||||
- from: "frontend/src/pages/OutputReview.tsx"
|
||||
to: "frontend/src/components/PostCard.tsx"
|
||||
via: "Render griglia di PostCard"
|
||||
pattern: "PostCard"
|
||||
- from: "frontend/src/components/PostCard.tsx"
|
||||
to: "frontend/src/components/SlideViewer.tsx"
|
||||
via: "Espansione card mostra SlideViewer"
|
||||
pattern: "SlideViewer"
|
||||
---
|
||||
|
||||
<objective>
|
||||
Creare l'intera Web UI: Dashboard, form Genera Calendario con progress indicator, Output Review con griglia card + navigazione slide + edit inline + download CSV, form Genera Singolo Post, e pagina Impostazioni.
|
||||
|
||||
Purpose: Dare all'utente l'interfaccia per interagire con la pipeline di generazione. Questa e' l'unica via di accesso al sistema — senza UI il backend non e' utilizzabile.
|
||||
|
||||
Output: SPA React completa con tutte le pagine e componenti per il workflow: configura -> genera -> rivedi -> scarica.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@C:\Users\miche\.claude/get-shit-done/workflows/execute-plan.md
|
||||
@C:\Users\miche\.claude/get-shit-done/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/PROJECT.md
|
||||
@.planning/ROADMAP.md
|
||||
@.planning/STATE.md
|
||||
@.planning/phases/01-core-generation-pipeline/01-CONTEXT.md
|
||||
@.planning/phases/01-core-generation-pipeline/01-01-SUMMARY.md
|
||||
@.planning/phases/01-core-generation-pipeline/01-02-SUMMARY.md
|
||||
@.planning/phases/01-core-generation-pipeline/01-03-SUMMARY.md
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 1: Layout, routing, API hooks, tipi TypeScript, pagine Settings e Dashboard</name>
|
||||
<files>
|
||||
frontend/src/types.ts
|
||||
frontend/src/api/client.ts
|
||||
frontend/src/api/hooks.ts
|
||||
frontend/src/components/Layout.tsx
|
||||
frontend/src/components/Sidebar.tsx
|
||||
frontend/src/App.tsx
|
||||
frontend/src/pages/Dashboard.tsx
|
||||
frontend/src/pages/Settings.tsx
|
||||
</files>
|
||||
<action>
|
||||
1. Creare frontend/src/types.ts con i tipi TypeScript che rispecchiano gli schemas Pydantic del backend:
|
||||
- CalendarSlot, CalendarRequest, CalendarResponse
|
||||
- SlideContent, GeneratedPost, PostResult, GenerateResponse
|
||||
- Settings (api_key, llm_model, nicchie_attive, lingua, frequenza_post, brand_name, tono)
|
||||
- SettingsStatus (api_key_configured: boolean, llm_model: string)
|
||||
|
||||
2. Aggiornare frontend/src/api/client.ts (gia' creato in Plan 01):
|
||||
- Aggiungere metodi specifici: apiGet<T>, apiPost<T>, apiPut<T>
|
||||
- Gestione download file: apiDownload(endpoint) -> Blob
|
||||
|
||||
3. Creare frontend/src/api/hooks.ts con TanStack Query hooks:
|
||||
- useSettings(): useQuery per GET /api/settings
|
||||
- useSettingsStatus(): useQuery per GET /api/settings/status
|
||||
- useUpdateSettings(): useMutation per PUT /api/settings
|
||||
- useGenerateCalendar(): useMutation per POST /api/generate/bulk — ritorna GenerateResponse
|
||||
- useGenerateSingle(): useMutation per POST /api/generate/single
|
||||
- useJobResults(jobId): useQuery per GET /api/generate/job/{jobId}
|
||||
- useDownloadCsv(): funzione che chiama apiDownload e triggera download browser
|
||||
- useFormats(): useQuery per GET /api/calendar/formats
|
||||
|
||||
4. Creare frontend/src/components/Layout.tsx:
|
||||
- Layout wrapper con Sidebar a sinistra e contenuto a destra
|
||||
- Responsive: sidebar collassabile su mobile
|
||||
- Tailwind CSS per styling
|
||||
|
||||
5. Creare frontend/src/components/Sidebar.tsx:
|
||||
- Logo/titolo "PostGenerator" in alto
|
||||
- Navigazione con link: Dashboard, Genera Calendario, Genera Singolo Post, Impostazioni
|
||||
- Usa react-router-dom NavLink con activeClassName
|
||||
- Icone da lucide-react
|
||||
|
||||
6. Aggiornare frontend/src/App.tsx:
|
||||
- BrowserRouter con basename="/postgenerator"
|
||||
- QueryClientProvider con QueryClient
|
||||
- Layout wrapping
|
||||
- Routes: / -> Dashboard, /genera -> GenerateCalendar, /genera-singolo -> GenerateSingle, /risultati/:jobId -> OutputReview, /impostazioni -> Settings
|
||||
|
||||
7. Creare frontend/src/pages/Dashboard.tsx:
|
||||
- Card di benvenuto con nome progetto e descrizione breve
|
||||
- Quick actions: "Genera Calendario" (link), "Impostazioni" (link)
|
||||
- Se API key non configurata: banner prominente "Configura la tua API key Claude nelle Impostazioni"
|
||||
- Se ci sono job recenti (check /api/generate/job/latest): mostra ultimo job con link a risultati
|
||||
- Usa useSettingsStatus() per verificare API key
|
||||
|
||||
8. Creare frontend/src/pages/Settings.tsx:
|
||||
- Form con campi:
|
||||
- API Key Claude (input password con toggle visibilita', mostra solo ultimi 4 char se gia' configurata)
|
||||
- Modello LLM (select: claude-sonnet-4-5, claude-haiku-3-5)
|
||||
- Brand Name (input text, opzionale)
|
||||
- Tono di voce (input text, default "diretto e concreto")
|
||||
- Nicchie attive (lista checkbox con le nicchie default + possibilita' di aggiungerne)
|
||||
- Frequenza post settimanale (number input, 1-7, default 3)
|
||||
- Pulsante Salva con feedback (successo/errore)
|
||||
- Usa useSettings() e useUpdateSettings()
|
||||
|
||||
NOTA DESIGN: Claude ha discrezione sul design UI. Scegliere uno stile pulito e professionale, NON il solito template generico con gradienti viola. Colori suggeriti: palette terrosa o industriale adatta a B2B.
|
||||
</action>
|
||||
<verify>
|
||||
- frontend/src/App.tsx ha BrowserRouter con basename="/postgenerator"
|
||||
- frontend/src/api/hooks.ts ha almeno 7 hooks (settings, settingsStatus, updateSettings, generateCalendar, generateSingle, jobResults, downloadCsv)
|
||||
- frontend/src/types.ts ha CalendarSlot, GeneratedPost, PostResult, Settings
|
||||
- Sidebar ha 4 link di navigazione
|
||||
- Settings ha campo API key con tipo password
|
||||
- Dashboard mostra banner se API key non configurata
|
||||
- npm run build completa senza errori TypeScript
|
||||
</verify>
|
||||
<done>
|
||||
Layout con sidebar, routing completo, API hooks TanStack Query per tutti gli endpoint, tipi TypeScript, Dashboard con stato API key, Settings form funzionale.
|
||||
</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 2: Genera Calendario, Output Review con card/slide/edit, Genera Singolo Post</name>
|
||||
<files>
|
||||
frontend/src/pages/GenerateCalendar.tsx
|
||||
frontend/src/pages/GenerateSingle.tsx
|
||||
frontend/src/pages/OutputReview.tsx
|
||||
frontend/src/components/PostCard.tsx
|
||||
frontend/src/components/SlideViewer.tsx
|
||||
frontend/src/components/ProgressIndicator.tsx
|
||||
frontend/src/components/BadgePN.tsx
|
||||
frontend/src/components/BadgeSchwartz.tsx
|
||||
</files>
|
||||
<action>
|
||||
1. Creare frontend/src/components/BadgePN.tsx:
|
||||
- Badge colorato per tipo Persuasion Nurturing
|
||||
- Colori distinti per ogni tipo: valore (blu), storytelling (viola), news (verde), riprova_sociale (arancione), coinvolgimento (giallo), promozione (rosso)
|
||||
- Mostra label (es. "Valore", "Storytelling")
|
||||
|
||||
2. Creare frontend/src/components/BadgeSchwartz.tsx:
|
||||
- Badge per livello Schwartz (L1-L5)
|
||||
- Colori progressivi (L5 chiaro -> L1 scuro) per indicare vicinanza all'acquisto
|
||||
- Tooltip con descrizione livello
|
||||
|
||||
3. Creare frontend/src/components/ProgressIndicator.tsx:
|
||||
- Mostra progresso generazione bulk: "Post 3/13 in generazione..."
|
||||
- Barra di progresso visuale
|
||||
- Lista dei post con stato: pending (grigio), processing (spinner), success (verde check), failed (rosso X)
|
||||
- Animazione per il post attualmente in generazione
|
||||
|
||||
4. Creare frontend/src/components/PostCard.tsx:
|
||||
- Card per singolo post nel risultato
|
||||
- Mostra: indice, tipo PN (badge), livello Schwartz (badge), formato narrativo, nicchia, data
|
||||
- Se status=success: mostra cover_title come titolo card, click per espandere
|
||||
- Se status=failed: card con sfondo rosso chiaro, icona errore, messaggio errore, pulsante "Riprova"
|
||||
- Pulsante Riprova chiama useGenerateSingle() per rigenerare quel slot
|
||||
- Click su card success -> espande per mostrare SlideViewer
|
||||
|
||||
5. Creare frontend/src/components/SlideViewer.tsx:
|
||||
- Visualizzazione slide-by-slide con navigazione frecce laterali (stile Instagram stories)
|
||||
- Mostra: slide corrente N/8, headline, body, image_keyword
|
||||
- Freccia sinistra/destra per navigare
|
||||
- Ogni campo testo e' EDITABILE inline: click per trasformare in input/textarea
|
||||
- Le modifiche aggiornano lo stato locale (PostResult) che verra' usato per il CSV download
|
||||
- Sotto le slide: caption Instagram in textarea editabile
|
||||
- Keyboard navigation: frecce sinistra/destra per cambiare slide
|
||||
|
||||
6. Creare frontend/src/pages/GenerateCalendar.tsx:
|
||||
- Form con campi:
|
||||
- Obiettivo campagna (textarea, obbligatorio, placeholder "Es: Aumentare awareness sull'AI per PMI italiane")
|
||||
- Settimane (number, default 2, range 1-4)
|
||||
- Brand name (input, opzionale — prende default da Settings)
|
||||
- Tono di voce (input, opzionale — prende default da Settings)
|
||||
- Nicchie (multi-select o checkbox, prende default da Settings)
|
||||
- Pulsante "Genera Calendario" con stati:
|
||||
- Se API key non configurata: disabilitato, messaggio "Configura API key nelle Impostazioni"
|
||||
- Se configurata: abilitato, al click mostra ProgressIndicator
|
||||
- Usa useSettingsStatus() per controllare API key
|
||||
- Usa useGenerateCalendar() mutation
|
||||
- Al completamento (successo o parziale): redirect a OutputReview con jobId
|
||||
|
||||
7. Creare frontend/src/pages/OutputReview.tsx:
|
||||
- Riceve jobId da route params
|
||||
- Carica risultati con useJobResults(jobId)
|
||||
- Header con: nome campagna, conteggio successi/falliti, pulsante "Download CSV"
|
||||
- Griglia di PostCard (3 colonne desktop, 2 tablet, 1 mobile)
|
||||
- PostCard espandibile con SlideViewer
|
||||
- Pulsante "Download CSV":
|
||||
- Chiama useDownloadCsv(jobId)
|
||||
- Se ci sono post falliti: mostra nota "Il CSV contiene solo i N post generati con successo"
|
||||
- Se tutti i post sono falliti: messaggio "Nessun post generato con successo. Riprova."
|
||||
|
||||
8. Creare frontend/src/pages/GenerateSingle.tsx:
|
||||
- Form per generare un singolo post manualmente:
|
||||
- Topic (textarea, obbligatorio)
|
||||
- Tipo contenuto (select: valore, storytelling, news, riprova_sociale, coinvolgimento, promozione)
|
||||
- Livello Schwartz (select: L1-L5)
|
||||
- Nicchia (select dalla lista)
|
||||
- Formato narrativo (select, auto-compilato in base a tipo+livello ma override possibile)
|
||||
- Al submit: chiama useGenerateSingle()
|
||||
- Mostra risultato con SlideViewer direttamente nella pagina
|
||||
- Pulsante download CSV per singolo post
|
||||
|
||||
GESTIONE STATO EDIT INLINE (importante):
|
||||
- OutputReview mantiene stato locale dei post (copia di GenerateResponse)
|
||||
- Quando utente edita una slide in SlideViewer, aggiorna lo stato locale
|
||||
- Il pulsante Download CSV usa lo stato locale aggiornato (non l'originale dal server)
|
||||
- Questo significa che il CSV riflette le modifiche dell'utente
|
||||
</action>
|
||||
<verify>
|
||||
- GenerateCalendar.tsx ha form con obiettivo e settimane, pulsante disabilitato senza API key
|
||||
- OutputReview.tsx mostra griglia di PostCard con badge PN e Schwartz
|
||||
- SlideViewer.tsx ha navigazione frecce e campi editabili inline
|
||||
- PostCard.tsx ha stati distinti per success e failed, con pulsante Riprova
|
||||
- ProgressIndicator.tsx mostra progresso per-item
|
||||
- GenerateSingle.tsx ha form con select per tipo, livello, nicchia, formato
|
||||
- npm run build completa senza errori TypeScript
|
||||
</verify>
|
||||
<done>
|
||||
Web UI completa: form Genera Calendario con progress, griglia risultati con card/badge, SlideViewer con navigazione e edit inline, download CSV con modifiche utente, Genera Singolo Post, gestione errori per-item con Riprova.
|
||||
</done>
|
||||
</task>
|
||||
|
||||
<task type="checkpoint:human-verify" gate="blocking">
|
||||
<what-built>
|
||||
Web UI completa con tutte le pagine: Dashboard, Genera Calendario, Output Review, Genera Singolo Post, Impostazioni. Inclusi progress indicator, griglia card con badge, navigazione slide, edit inline.
|
||||
</what-built>
|
||||
<how-to-verify>
|
||||
1. Verificare che `cd frontend && npm run build` completa senza errori
|
||||
2. Verificare che la struttura delle pagine e componenti sia coerente
|
||||
3. Controllare che il routing in App.tsx abbia tutte le 5 route
|
||||
4. Verificare che l'API client usi /postgenerator/api come base
|
||||
5. Opzionale: se deployato, navigare su https://lab.mlhub.it/postgenerator/ e verificare che la UI si carichi
|
||||
</how-to-verify>
|
||||
<resume-signal>Digita "approved" se la UI e' accettabile, oppure descrivi i problemi da correggere</resume-signal>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<verification>
|
||||
1. `cd frontend && npm run build` produce dist/ senza errori
|
||||
2. App.tsx ha 5 route definite con BrowserRouter basename="/postgenerator"
|
||||
3. Tutti i componenti importano tipi da types.ts (non definiscono tipi inline)
|
||||
4. API hooks usano /postgenerator/api come base URL
|
||||
5. PostCard ha due varianti visive: success (espandibile) e failed (errore + riprova)
|
||||
6. SlideViewer supporta edit inline e navigazione frecce
|
||||
7. GenerateCalendar disabilita pulsante se API key non configurata
|
||||
8. OutputReview fa download CSV con le modifiche inline dell'utente
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
- Dashboard mostra stato API key e quick actions
|
||||
- Settings permette configurazione API key, modello, nicchie, frequenza
|
||||
- Genera Calendario ha form, progress indicator, redirect a risultati
|
||||
- Output Review mostra griglia card con badge, slide viewer con edit, download CSV
|
||||
- Post falliti mostrano errore e pulsante Riprova
|
||||
- Genera Singolo Post ha form completo con anteprima risultato
|
||||
- Build frontend completa senza errori
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
After completion, create `.planning/phases/01-core-generation-pipeline/01-04-SUMMARY.md`
|
||||
</output>
|
||||
Reference in New Issue
Block a user