feat: async image-gen and description jobs with review panels

- Add POST /api/admin/image-gen/async: fire-and-forget image generation
  that stores the result (base64) in an ai_job payload and returns 202
  immediately — no more 60-120s blocking on FLUX models
- Add POST /api/admin/text-gen/description/async: same pattern for book
  description generation
- Register both new routes in server.go
- Rewrite image-gen admin page to use the async path (submit → redirect
  to AI Jobs for monitoring)
- Extend ai-jobs page with Review panels for image-gen jobs (show image,
  Save as cover / Download / Discard) and description jobs (diff old vs
  new, editable textarea, Apply / Discard)

backend/internal/backend/handlers_image.go

@@ -1,14 +1,17 @@
 package backend
 
 import (
+	"context"
 	"encoding/base64"
 	"encoding/json"
 	"fmt"
 	"io"
 	"net/http"
 	"strings"
+	"time"
 
 	"github.com/libnovel/backend/internal/cfai"
+	"github.com/libnovel/backend/internal/domain"
 )
 
 // handleAdminImageGenModels handles GET /api/admin/image-gen/models.
@@ -288,3 +291,231 @@ func sniffImageContentType(data []byte) string {
 	}
 	return "image/png"
 }
+
+// handleAdminImageGenAsync handles POST /api/admin/image-gen/async.
+//
+// Fire-and-forget variant: validates the request, creates an ai_job record of
+// kind "image-gen", spawns a background goroutine, and returns HTTP 202 with
+// {job_id} immediately. The goroutine calls Cloudflare AI, stores the result
+// as base64 in the job payload, and marks the job done/failed when finished.
+//
+// The admin can then review the result via the ai-jobs page and approve
+// (save as cover) or reject (discard) the image.
+func (s *Server) handleAdminImageGenAsync(w http.ResponseWriter, r *http.Request) {
+	if s.deps.ImageGen == nil {
+		jsonError(w, http.StatusServiceUnavailable, "image generation not configured (CFAI_ACCOUNT_ID/CFAI_API_TOKEN missing)")
+		return
+	}
+	if s.deps.AIJobStore == nil {
+		jsonError(w, http.StatusServiceUnavailable, "ai job store not configured")
+		return
+	}
+
+	var req imageGenRequest
+	var refImageData []byte
+
+	ct := r.Header.Get("Content-Type")
+	if strings.HasPrefix(ct, "multipart/form-data") {
+		if err := r.ParseMultipartForm(32 << 20); err != nil {
+			jsonError(w, http.StatusBadRequest, "parse multipart: "+err.Error())
+			return
+		}
+		if jsonPart := r.FormValue("json"); jsonPart != "" {
+			if err := json.Unmarshal([]byte(jsonPart), &req); err != nil {
+				jsonError(w, http.StatusBadRequest, "parse json field: "+err.Error())
+				return
+			}
+		}
+		if f, _, err := r.FormFile("reference"); err == nil {
+			defer f.Close()
+			refImageData, _ = io.ReadAll(f)
+		}
+	} else {
+		if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+			jsonError(w, http.StatusBadRequest, "parse body: "+err.Error())
+			return
+		}
+		if req.ReferenceImageB64 != "" {
+			var decErr error
+			refImageData, decErr = base64.StdEncoding.DecodeString(req.ReferenceImageB64)
+			if decErr != nil {
+				refImageData, decErr = base64.RawStdEncoding.DecodeString(req.ReferenceImageB64)
+				if decErr != nil {
+					jsonError(w, http.StatusBadRequest, "decode reference_image_b64: "+decErr.Error())
+					return
+				}
+			}
+		}
+	}
+
+	if strings.TrimSpace(req.Prompt) == "" {
+		jsonError(w, http.StatusBadRequest, "prompt is required")
+		return
+	}
+	if req.Type != "cover" && req.Type != "chapter" {
+		jsonError(w, http.StatusBadRequest, `type must be "cover" or "chapter"`)
+		return
+	}
+	if req.Slug == "" {
+		jsonError(w, http.StatusBadRequest, "slug is required")
+		return
+	}
+	if req.Type == "chapter" && req.Chapter <= 0 {
+		jsonError(w, http.StatusBadRequest, "chapter must be > 0 when type is chapter")
+		return
+	}
+
+	// Resolve model.
+	model := cfai.ImageModel(req.Model)
+	if model == "" {
+		if req.Type == "cover" {
+			model = cfai.DefaultImageModel
+		} else {
+			model = cfai.ImageModelFlux2Klein4B
+		}
+	}
+
+	// Encode request params as job payload so the UI can reconstruct context.
+	type jobParams struct {
+		Prompt    string `json:"prompt"`
+		Type      string `json:"type"`
+		Chapter   int    `json:"chapter,omitempty"`
+		NumSteps  int    `json:"num_steps,omitempty"`
+		Width     int    `json:"width,omitempty"`
+		Height    int    `json:"height,omitempty"`
+		Guidance  float64 `json:"guidance,omitempty"`
+		Strength  float64 `json:"strength,omitempty"`
+		HasRef    bool   `json:"has_ref,omitempty"`
+	}
+	paramsJSON, _ := json.Marshal(jobParams{
+		Prompt:   req.Prompt,
+		Type:     req.Type,
+		Chapter:  req.Chapter,
+		NumSteps: req.NumSteps,
+		Width:    req.Width,
+		Height:   req.Height,
+		Guidance: req.Guidance,
+		Strength: req.Strength,
+		HasRef:   len(refImageData) > 0,
+	})
+
+	jobID, createErr := s.deps.AIJobStore.CreateAIJob(r.Context(), domain.AIJob{
+		Kind:    "image-gen",
+		Slug:    req.Slug,
+		Status:  domain.TaskStatusPending,
+		Model:   string(model),
+		Payload: string(paramsJSON),
+		Started: time.Now(),
+	})
+	if createErr != nil {
+		jsonError(w, http.StatusInternalServerError, "create ai job: "+createErr.Error())
+		return
+	}
+
+	jobCtx, jobCancel := context.WithCancel(context.Background())
+	registerCancelJob(jobID, jobCancel)
+
+	// Mark running before returning.
+	_ = s.deps.AIJobStore.UpdateAIJob(r.Context(), jobID, map[string]any{
+		"status": string(domain.TaskStatusRunning),
+	})
+
+	s.deps.Log.Info("admin: image-gen async started",
+		"job_id", jobID, "slug", req.Slug, "type", req.Type, "model", model)
+
+	// Capture locals for the goroutine.
+	store := s.deps.AIJobStore
+	imageGen := s.deps.ImageGen
+	coverStore := s.deps.CoverStore
+	logger := s.deps.Log
+	capturedReq := req
+	capturedModel := model
+	capturedRefImage := refImageData
+
+	go func() {
+		defer deregisterCancelJob(jobID)
+		defer jobCancel()
+
+		if jobCtx.Err() != nil {
+			_ = store.UpdateAIJob(context.Background(), jobID, map[string]any{
+				"status":   string(domain.TaskStatusCancelled),
+				"finished": time.Now().Format(time.RFC3339),
+			})
+			return
+		}
+
+		imgReq := cfai.ImageRequest{
+			Prompt:   capturedReq.Prompt,
+			Model:    capturedModel,
+			NumSteps: capturedReq.NumSteps,
+			Width:    capturedReq.Width,
+			Height:   capturedReq.Height,
+			Guidance: capturedReq.Guidance,
+			Strength: capturedReq.Strength,
+		}
+
+		var imgData []byte
+		var genErr error
+		if len(capturedRefImage) > 0 {
+			imgData, genErr = imageGen.GenerateImageFromReference(jobCtx, imgReq, capturedRefImage)
+		} else {
+			imgData, genErr = imageGen.GenerateImage(jobCtx, imgReq)
+		}
+
+		if genErr != nil {
+			logger.Error("admin: image-gen async failed", "job_id", jobID, "err", genErr)
+			_ = store.UpdateAIJob(context.Background(), jobID, map[string]any{
+				"status":        string(domain.TaskStatusFailed),
+				"error_message": genErr.Error(),
+				"finished":      time.Now().Format(time.RFC3339),
+			})
+			return
+		}
+
+		contentType := sniffImageContentType(imgData)
+		b64 := base64.StdEncoding.EncodeToString(imgData)
+
+		// Build result payload: include the original params + the generated image.
+		type resultPayload struct {
+			Prompt      string  `json:"prompt"`
+			Type        string  `json:"type"`
+			Chapter     int     `json:"chapter,omitempty"`
+			ContentType string  `json:"content_type"`
+			ImageB64    string  `json:"image_b64"`
+			Bytes       int     `json:"bytes"`
+			NumSteps    int     `json:"num_steps,omitempty"`
+			Width       int     `json:"width,omitempty"`
+			Height      int     `json:"height,omitempty"`
+			Guidance    float64 `json:"guidance,omitempty"`
+		}
+		resultJSON, _ := json.Marshal(resultPayload{
+			Prompt:      capturedReq.Prompt,
+			Type:        capturedReq.Type,
+			Chapter:     capturedReq.Chapter,
+			ContentType: contentType,
+			ImageB64:    b64,
+			Bytes:       len(imgData),
+			NumSteps:    capturedReq.NumSteps,
+			Width:       capturedReq.Width,
+			Height:      capturedReq.Height,
+			Guidance:    capturedReq.Guidance,
+		})
+
+		_ = store.UpdateAIJob(context.Background(), jobID, map[string]any{
+			"status":     string(domain.TaskStatusDone),
+			"items_done": 1,
+			"items_total": 1,
+			"payload":    string(resultJSON),
+			"finished":   time.Now().Format(time.RFC3339),
+		})
+
+		logger.Info("admin: image-gen async done",
+			"job_id", jobID, "slug", capturedReq.Slug,
+			"bytes", len(imgData), "content_type", contentType)
+
+		// Suppress unused variable warning for coverStore when SaveToCover is false.
+		_ = coverStore
+	}()
+
+	writeJSON(w, http.StatusAccepted, map[string]any{"job_id": jobID})
+}

backend/internal/backend/handlers_textgen.go

@@ -801,3 +801,161 @@ func (s *Server) handleAdminTextGenApplyDescription(w http.ResponseWriter, r *ht
 	s.deps.Log.Info("admin: book description applied", "slug", req.Slug)
 	writeJSON(w, 0, map[string]any{"updated": true})
 }
+
+// handleAdminTextGenDescriptionAsync handles POST /api/admin/text-gen/description/async.
+//
+// Fire-and-forget variant: validates inputs, creates an ai_job record of kind
+// "description", spawns a background goroutine that calls the LLM, stores the
+// old/new description in the job payload, and marks the job done/failed.
+// Returns HTTP 202 with {job_id} immediately.
+func (s *Server) handleAdminTextGenDescriptionAsync(w http.ResponseWriter, r *http.Request) {
+	if s.deps.TextGen == nil {
+		jsonError(w, http.StatusServiceUnavailable, "text generation not configured (CFAI_ACCOUNT_ID/CFAI_API_TOKEN missing)")
+		return
+	}
+	if s.deps.AIJobStore == nil {
+		jsonError(w, http.StatusServiceUnavailable, "ai job store not configured")
+		return
+	}
+
+	var req textGenDescriptionRequest
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		jsonError(w, http.StatusBadRequest, "parse body: "+err.Error())
+		return
+	}
+	if strings.TrimSpace(req.Slug) == "" {
+		jsonError(w, http.StatusBadRequest, "slug is required")
+		return
+	}
+
+	// Load current metadata eagerly so we can fail fast if the book is missing.
+	meta, ok, err := s.deps.BookReader.ReadMetadata(r.Context(), req.Slug)
+	if err != nil {
+		jsonError(w, http.StatusInternalServerError, "read metadata: "+err.Error())
+		return
+	}
+	if !ok {
+		jsonError(w, http.StatusNotFound, fmt.Sprintf("book %q not found", req.Slug))
+		return
+	}
+
+	model := cfai.TextModel(req.Model)
+	if model == "" {
+		model = cfai.DefaultTextModel
+	}
+
+	instructions := strings.TrimSpace(req.Instructions)
+	if instructions == "" {
+		instructions = "Write a compelling 2–4 sentence description. Keep it spoiler-free and engaging."
+	}
+
+	// Encode the initial params (without result) as the starting payload.
+	type initPayload struct {
+		Instructions   string `json:"instructions"`
+		OldDescription string `json:"old_description"`
+	}
+	initJSON, _ := json.Marshal(initPayload{
+		Instructions:   instructions,
+		OldDescription: meta.Summary,
+	})
+
+	jobID, createErr := s.deps.AIJobStore.CreateAIJob(r.Context(), domain.AIJob{
+		Kind:    "description",
+		Slug:    req.Slug,
+		Status:  domain.TaskStatusPending,
+		Model:   string(model),
+		Payload: string(initJSON),
+		Started: time.Now(),
+	})
+	if createErr != nil {
+		jsonError(w, http.StatusInternalServerError, "create ai job: "+createErr.Error())
+		return
+	}
+
+	jobCtx, jobCancel := context.WithCancel(context.Background())
+	registerCancelJob(jobID, jobCancel)
+
+	_ = s.deps.AIJobStore.UpdateAIJob(r.Context(), jobID, map[string]any{
+		"status": string(domain.TaskStatusRunning),
+	})
+
+	s.deps.Log.Info("admin: text-gen description async started",
+		"job_id", jobID, "slug", req.Slug, "model", model)
+
+	// Capture locals.
+	store := s.deps.AIJobStore
+	textGen := s.deps.TextGen
+	logger := s.deps.Log
+	capturedMeta := meta
+	capturedModel := model
+	capturedInstructions := instructions
+	capturedMaxTokens := req.MaxTokens
+
+	go func() {
+		defer deregisterCancelJob(jobID)
+		defer jobCancel()
+
+		if jobCtx.Err() != nil {
+			_ = store.UpdateAIJob(context.Background(), jobID, map[string]any{
+				"status":   string(domain.TaskStatusCancelled),
+				"finished": time.Now().Format(time.RFC3339),
+			})
+			return
+		}
+
+		systemPrompt := `You are a book description writer for a web novel platform. ` +
+			`Given a book's title, author, genres, and current description, write an improved ` +
+			`description that accurately captures the story. ` +
+			`Respond with ONLY the new description text — no title, no labels, no markdown, no quotes.`
+
+		userPrompt := fmt.Sprintf(
+			"Title: %s\nAuthor: %s\nGenres: %s\nStatus: %s\n\nCurrent description:\n%s\n\nInstructions: %s",
+			capturedMeta.Title,
+			capturedMeta.Author,
+			strings.Join(capturedMeta.Genres, ", "),
+			capturedMeta.Status,
+			capturedMeta.Summary,
+			capturedInstructions,
+		)
+
+		newDesc, genErr := textGen.Generate(jobCtx, cfai.TextRequest{
+			Model: capturedModel,
+			Messages: []cfai.TextMessage{
+				{Role: "system", Content: systemPrompt},
+				{Role: "user", Content: userPrompt},
+			},
+			MaxTokens: capturedMaxTokens,
+		})
+		if genErr != nil {
+			logger.Error("admin: text-gen description async failed", "job_id", jobID, "err", genErr)
+			_ = store.UpdateAIJob(context.Background(), jobID, map[string]any{
+				"status":        string(domain.TaskStatusFailed),
+				"error_message": genErr.Error(),
+				"finished":      time.Now().Format(time.RFC3339),
+			})
+			return
+		}
+
+		type resultPayload struct {
+			Instructions   string `json:"instructions"`
+			OldDescription string `json:"old_description"`
+			NewDescription string `json:"new_description"`
+		}
+		resultJSON, _ := json.Marshal(resultPayload{
+			Instructions:   capturedInstructions,
+			OldDescription: capturedMeta.Summary,
+			NewDescription: strings.TrimSpace(newDesc),
+		})
+
+		_ = store.UpdateAIJob(context.Background(), jobID, map[string]any{
+			"status":      string(domain.TaskStatusDone),
+			"items_done":  1,
+			"items_total": 1,
+			"payload":     string(resultJSON),
+			"finished":    time.Now().Format(time.RFC3339),
+		})
+		logger.Info("admin: text-gen description async done", "job_id", jobID, "slug", capturedMeta.Slug)
+	}()
+
+	writeJSON(w, http.StatusAccepted, map[string]any{"job_id": jobID})
+}

backend/internal/backend/server.go

@@ -201,6 +201,7 @@ func (s *Server) ListenAndServe(ctx context.Context) error {
 	// Admin image generation endpoints
 	mux.HandleFunc("GET /api/admin/image-gen/models", s.handleAdminImageGenModels)
 	mux.HandleFunc("POST /api/admin/image-gen", s.handleAdminImageGen)
+	mux.HandleFunc("POST /api/admin/image-gen/async", s.handleAdminImageGenAsync)
 	mux.HandleFunc("POST /api/admin/image-gen/save-cover", s.handleAdminImageGenSaveCover)
 
 	// Admin text generation endpoints (chapter names + book description)
@@ -209,6 +210,7 @@ func (s *Server) ListenAndServe(ctx context.Context) error {
 	mux.HandleFunc("POST /api/admin/text-gen/chapter-names/async", s.handleAdminTextGenChapterNamesAsync)
 	mux.HandleFunc("POST /api/admin/text-gen/chapter-names/apply", s.handleAdminTextGenApplyChapterNames)
 	mux.HandleFunc("POST /api/admin/text-gen/description", s.handleAdminTextGenDescription)
+	mux.HandleFunc("POST /api/admin/text-gen/description/async", s.handleAdminTextGenDescriptionAsync)
 	mux.HandleFunc("POST /api/admin/text-gen/description/apply", s.handleAdminTextGenApplyDescription)
 
 	// Admin catalogue enrichment endpoints