postgenerator/.planning/phases/02-prompt-control-output-review/02-01-SUMMARY.md

phase, plan, subsystem, tags, dependency_graph, tech_stack, key_files, decisions, metrics

phase	plan	subsystem	tags	dependency_graph	tech_stack	key_files	decisions	metrics
02-prompt-control-output-review	01	prompt-management	fastapi react crud prompt-editor tanstack-query	requires provides affects 01-02 (PromptService with load/save/list/variables/exists methods) 01-04 (Web UI with stone/amber palette, Sidebar, Layout, routing) Prompt CRUD API (4 endpoints list, read, write, reset) Prompt Editor UI page with live variable extraction 02-02 (Output Review enhancement may reference prompt editing) Future phases that add new prompt types	added patterns Lazy PromptService init for directory lifecycle sync Default vs modified comparison for prompt versioning Client-side regex for live variable extraction	created modified backend/routers/prompts.py frontend/src/pages/PromptEditor.tsx backend/main.py frontend/src/types.ts frontend/src/api/hooks.ts frontend/src/App.tsx frontend/src/components/Sidebar.tsx	id decision reason date prompt-lazy-init PromptService initialized lazily via _get_prompt_service() instead of module-level PROMPTS_PATH directory is created during FastAPI lifespan, not at import time. Module-level init would fail with FileNotFoundError during import. 2026-03-08	duration completed ~5 min 2026-03-08

Phase 02 Plan 01: Prompt CRUD + Prompt Editor UI Summary

PromptService CRUD completo con 4 endpoint FastAPI e pagina React Prompt Editor con lista, textarea monospace, variabili live, salva e reset al default.

What Was Done

Task 1: Backend prompts router (4 CRUD endpoints)

Created backend/routers/prompts.py with APIRouter(prefix="/api/prompts", tags=["prompts"]):

• GET /api/prompts — Lists all .txt prompts with modified flag (compares runtime vs default in backend/data/prompts/)
• GET /api/prompts/{name} — Returns content, required variables, and modified flag
• PUT /api/prompts/{name} — Saves modified content with min_length=10 validation, returns updated variables
• POST /api/prompts/{name}/reset — Restores default content from backend/data/prompts/, returns 404 if no default exists

Key implementation detail: PromptService is lazily initialized via _get_prompt_service() because PROMPTS_PATH is created during FastAPI's lifespan event, not at module import time.

Router registered in main.py before the SPA catch-all mount.

Task 2: Frontend Prompt Editor (page, hooks, types, route, sidebar)

• Types: Added PromptInfo, PromptListResponse, PromptDetail to types.ts
• Hooks: Added usePromptList, usePrompt, useSavePrompt, useResetPrompt to hooks.ts with TanStack Query cache invalidation
• Page: Created PromptEditor.tsx with two-column layout (1/3 list, 2/3 editor on lg, stacked on mobile)
  • Prompt list with amber "Modificato" / stone "Default" badges
  • Monospace textarea (min-height 400px, stone-900 bg)
  • Live client-side variable extraction via regex {{nome}}
  • Save button (amber, disabled when not dirty)
  • Reset to Default with inline confirmation dialog
  • Success/error feedback inline
• Route: /prompt-editor added in App.tsx
• Sidebar: "Prompt Editor" nav item with Pencil icon, positioned after "Genera Singolo Post" and before "Impostazioni"

Deviations from Plan

Auto-fixed Issues

1. [Rule 3 - Blocking] Lazy PromptService initialization

• Found during: Task 1
• Issue: Module-level PromptService(PROMPTS_PATH) raised FileNotFoundError because PROMPTS_PATH directory doesn't exist at import time — it's created in the FastAPI lifespan event.
• Fix: Changed to lazy initialization via _get_prompt_service() function with PROMPTS_PATH.mkdir(parents=True, exist_ok=True) on first access.
• Files modified: backend/routers/prompts.py
• Commit: 05972fa

Verification

• Backend imports without errors: from backend.routers.prompts import router OK
• 4 routes registered: /api/prompts/, /api/prompts/{name}, /api/prompts/{name}, /api/prompts/{name}/reset
• main.py includes app.include_router(prompts.router) before SPA catch-all
• TypeScript compiles with npx tsc --noEmit — zero errors
• Route /prompt-editor in App.tsx
• Sidebar contains "Prompt Editor" nav link
• Types and hooks exported correctly

Next Phase Readiness

Plan 02-01 is complete. The Prompt Editor is functional for CRUD operations on prompt files. Plan 02-02 can proceed independently (Output Review enhancements).