From e8a93526a285705406307d22e67a7a3b6fbbdd24 Mon Sep 17 00:00:00 2001 From: Michele Date: Mon, 9 Mar 2026 08:18:47 +0100 Subject: [PATCH] docs(04-02): complete Frontend Unsplash UI plan Tasks completed: 2/2 - Task 1: Types + Settings page + hooks per Unsplash - Task 2: Thumbnail PostCard + hint OutputReview SUMMARY: .planning/phases/04-enrichment/04-02-SUMMARY.md --- .planning/STATE.md | 35 +++--- .../phases/04-enrichment/04-02-SUMMARY.md | 115 ++++++++++++++++++ 2 files changed, 134 insertions(+), 16 deletions(-) create mode 100644 .planning/phases/04-enrichment/04-02-SUMMARY.md diff --git a/.planning/STATE.md b/.planning/STATE.md index 4e76da0..c40a41e 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -5,23 +5,23 @@ 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 4 Plan 01 COMPLETO — integrazione Unsplash backend +**Current focus:** TUTTI I PIANI COMPLETATI — pronto per deploy VPS e test end-to-end ## Current Position -Phase: 4 of 4 (Enrichment) — In progress -Plan: 1 of 1 in current phase — Completato -Status: Phase 4 Plan 01 completa — backend Unsplash integrato -Last activity: 2026-03-09 — Completed 04-01-PLAN.md (Unsplash image resolution) +Phase: 4 of 4 (Enrichment) — COMPLETA +Plan: 2 of 2 in current phase — Completato +Status: PROGETTO COMPLETO — tutte le 4 fasi implementate (backend + frontend) +Last activity: 2026-03-09 — Completed 04-02-PLAN.md (Frontend Unsplash UI) -Progress: [█████████░] 100% (9/9 piani totali) +Progress: [██████████] 100% (10/10 piani totali) ## Performance Metrics **Velocity:** -- Total plans completed: 9 -- Average duration: ~6 min -- Total execution time: 55 min +- Total plans completed: 10 +- Average duration: ~5.8 min +- Total execution time: ~58 min **By Phase:** @@ -30,10 +30,10 @@ Progress: [█████████░] 100% (9/9 piani totali) | 01-core-generation-pipeline | 4/4 COMPLETA | 33 min | 8 min | | 02-prompt-control-output-review | 2/2 COMPLETA | 9 min | 4.5 min | | 03-organization-layer | 2/2 COMPLETA | 8 min | 4 min | -| 04-enrichment | 1/1 COMPLETA | 5 min | 5 min | +| 04-enrichment | 2/2 COMPLETA | 8 min | 4 min | **Recent Trend:** -- Last 5 plans: 4 min, 5 min, 3 min, 3 min, 5 min +- Last 5 plans: 5 min, 3 min, 3 min, 5 min, 3 min - Trend: stabile intorno a 3-5 min *Updated after each plan completion* @@ -77,22 +77,25 @@ Recent decisions affecting current work: - [04-01]: Dizionario statico IT->EN (~30 keyword B2B) — no API di traduzione - [04-01]: Fallback trasparente: keyword non risolte restano testuali, nessun errore bloccante - [04-01]: Rate limit: X-Ratelimit-Remaining < 5 => stop batch, keyword restanti non risolte +- [04-02]: Link vs navigate() — usato Link da react-router-dom per coerenza col pattern codebase +- [04-02]: showUnsplashKey state separato da showApiKey — toggle indipendenti per le due API key +- [04-02]: Thumbnail 80x56px — anteprima visiva senza dominare la card (13 immagini in pagina) +- [04-02]: Hint OutputReview volutamente discreto (stone-600) — non aggressivo, scompare silenziosamente ### Blockers/Concerns - [Phase 1]: Validare token usage reale per batch 13 post con claude-sonnet-4-5 — inter_request_delay=2.0s configurato, da validare in produzione - [Phase 1]: Baseline qualita' prompt italiani da validare dopo prima generazione reale - [Deploy]: PRIORITA' — eseguire vps-lab-deploy per testare end-to-end il sistema completo (tutte le 4 fasi complete) -- [04-01]: Frontend non aggiornato per campo unsplash_api_key in Impostazioni — funzionalita' disponibile ma non configurabile via UI (workaround: API diretta o settings.json) ## Session Continuity Last session: 2026-03-09 -Stopped at: Completed 04-01-PLAN.md (Unsplash image resolution) — Plan 1/1 Phase 4 +Stopped at: Completed 04-02-PLAN.md (Frontend Unsplash UI) — Plan 2/2 Phase 4 Resume file: None ## Next Actions -1. `vps-lab-deploy` — tutte le 4 fasi sono complete, deployare su VPS e testare end-to-end -2. Aggiornare il frontend Settings per esporre il campo unsplash_api_key (opzionale, post-deploy) -3. Test reale della generazione bulk con Unsplash API key configurata +1. `vps-lab-deploy` — PRIORITA' — tutte le 4 fasi sono complete, deployare su VPS e testare end-to-end +2. Test reale della generazione bulk: configurare API key Claude + Unsplash in Settings UI, verificare thumbnail in OutputReview, verificare URL immagini nel CSV +3. Validare qualita' prompt italiani con dati reali diff --git a/.planning/phases/04-enrichment/04-02-SUMMARY.md b/.planning/phases/04-enrichment/04-02-SUMMARY.md new file mode 100644 index 0000000..65641e9 --- /dev/null +++ b/.planning/phases/04-enrichment/04-02-SUMMARY.md @@ -0,0 +1,115 @@ +--- +phase: 04-enrichment +plan: 02 +subsystem: ui +tags: [react, typescript, unsplash, thumbnail, settings, tanstack-query] + +# Dependency graph +requires: + - phase: 04-01 + provides: UnsplashService backend + unsplash_api_key in Settings schema + image_url_map nel job JSON + +provides: + - Campo API Key Unsplash in pagina Settings con sezione dedicata "Immagini" + - Thumbnail cover image in PostCard (80x56px) quando cover_image_keyword e' un URL reale + - Hint discreto in OutputReview che suggerisce di configurare Unsplash se non presente + - Types aggiornati: Settings con unsplash_api_key, SettingsStatus con unsplash_api_key_configured + +affects: + - deploy (frontend pronto per deploy completo fase 4) + +# Tech tracking +tech-stack: + added: [] + patterns: + - "Logica di submit difensiva: campi API key non inviati se vuoti (evita sovrascrittura)" + - "Hint contestuali condizionali via useSettingsStatus (scompaiono quando risolto)" + - "Thumbnail lazy con onError fallback (nasconde immagine se URL non valido)" + - "Rilevamento URL reale via startsWith('http') — pattern semplice e affidabile" + +key-files: + created: [] + modified: + - frontend/src/types.ts + - frontend/src/pages/Settings.tsx + - frontend/src/components/PostCard.tsx + - frontend/src/pages/OutputReview.tsx + +key-decisions: + - "Pattern Link da react-router-dom (non useNavigate) per navigazione a /impostazioni — coerente col codebase" + - "showUnsplashKey state separato da showApiKey — toggle indipendenti per le due API key" + - "Thumbnail 80x56px (w-20 h-14) — anteprima sufficiente senza appesantire la pagina con 13 immagini" + - "Hint OutputReview volutamente discreto (text-stone-600) — non aggressivo, scompare silenziosamente" + +patterns-established: + - "Tutti i campi API key: non pre-popolati nel form, non inviati se vuoti, reset dopo salvataggio" + - "useSettingsStatus() come fonte di verita' per feature-gating UI (configured vs not)" + +# Metrics +duration: 3min +completed: 2026-03-09 +--- + +# Phase 4 Plan 02: Frontend Unsplash — Settings, Thumbnail, Hint Summary + +**Campo Unsplash API key in Settings, thumbnail cover image 80x56px in PostCard, e hint contestuale in OutputReview con Link a /impostazioni** + +## Performance + +- **Duration:** ~3 min +- **Started:** 2026-03-09T07:14:26Z +- **Completed:** 2026-03-09T07:17:09Z +- **Tasks:** 2 +- **Files modified:** 4 + +## Accomplishments + +- Types TypeScript aggiornati: `unsplash_api_key` in `Settings`, `unsplash_api_key_configured` in `SettingsStatus` +- Pagina Settings: nuova sezione "Immagini" con input API Key Unsplash, toggle visibilita' indipendente, helper text condizionale (diverso se key configurata o no), logica submit identica a API Key Claude (non invia se vuota) +- PostCard: thumbnail 80x56px della cover image visibile solo quando `cover_image_keyword` e' un URL reale (`startsWith('http')`), con `loading="lazy"` e `onError` per fallback silenzioso +- OutputReview: hint discreto con Link a `/impostazioni` visibile solo quando `unsplash_api_key_configured === false`, scompare automaticamente dopo configurazione + +## Task Commits + +Ogni task e' stato committato atomicamente: + +1. **Task 1: Types + Settings page + hooks per Unsplash** - `d537c03` (feat) +2. **Task 2: Thumbnail PostCard + hint OutputReview** - `f154f1b` (feat) + +**Plan metadata:** (doc commit segue) + +## Files Created/Modified + +- `frontend/src/types.ts` - Aggiunto `unsplash_api_key` a Settings, `unsplash_api_key_configured` a SettingsStatus +- `frontend/src/pages/Settings.tsx` - Sezione "Immagini" con campo Unsplash API key, state showUnsplashKey, logica submit, reset post-salvataggio +- `frontend/src/components/PostCard.tsx` - Thumbnail condizionale dopo cover_title nella sezione SUCCESS +- `frontend/src/pages/OutputReview.tsx` - Import Link e useSettingsStatus, hint discreto Unsplash con Link a /impostazioni + +## Decisions Made + +- **Link vs navigate():** Usato `Link` da `react-router-dom` con `to="/impostazioni"` (pattern usato in tutto il codebase, es. Dashboard, GenerateCalendar, GenerateSingle) — non introdotto `useNavigate` che non era necessario +- **showUnsplashKey separato:** State `showUnsplashKey` indipendente da `showApiKey` — ogni campo API key ha il proprio toggle, coerente con comportamento atteso +- **Thumbnail size 80x56px:** `w-20 h-14` — abbastanza grande per dare un'anteprima visiva significativa, abbastanza piccolo da non dominare la card con 13 post in pagina +- **Hint discreto stone-600:** Testo volutamente sottotono, non un warning aggressivo. Colore amber solo sul link di azione + +## Deviations from Plan + +Nessuna — piano eseguito esattamente come scritto. + +## Issues Encountered + +Nessuno. + +## User Setup Required + +None — l'API key Unsplash si configura ora direttamente dalla UI in Settings. + +## Next Phase Readiness + +- Frontend completo per tutte le 4 fasi (core generation, prompt control, organization, enrichment) +- Pronto per `vps-lab-deploy` per testing end-to-end completo +- Per testare Unsplash: configurare API key in Settings, avviare generazione bulk, verificare thumbnail in OutputReview e URL immagini nel CSV scaricato + +--- +*Phase: 04-enrichment* +*Completed: 2026-03-09*