@

feat: AE template scanner + scene editor + AEP bundle pipeline

Scene editor (admin): per-project Scenes / Shared Colors / Color Presets
manager (ProjectScenes) reachable from each project.

AEP bundle pipeline: upload .aep or .zip → stored once per template at
templates/{project_id}/(bundle.zip|template.aep); render claim probes and
returns is_bundle+md5; node-agent extracts the bundle, locates the .aep
(zip-slip guarded), and caches by md5 so repeated renders extract once.

AE template scanner ("read scenes/colours/configs from the AEP"):
- content-svc importer: POST /v1/projects/{id}/scan/{preview,apply} —
  review-diff-then-merge into scenes/elements/colours (manual edits kept).
- render-svc Go quick-scan: stdlib RIFX parser extracts comp names+durations
  (no AE) → POST /v1/template-scans/{id}/quick.
- render-svc AE scan jobs + node-agent runner: queue → node runs scan.jsx
  (reverse of legacy JSXGenerator conventions: frfinal/frshare/frl_/frd_) →
  posts ScanResult back. Migration 26_render_scan_jobs.
- admin UI: "اسکن از افترافکت" with quick/full engines + diff-review modal.

Verified: importer preview/apply, Go quick-scan end-to-end (synthetic .aep →
scene imported), bundle extract unit tests, RIFX parser unit tests.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@

services/render/internal/handlers/internal.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"fmt"
 	"net/http"
+	"strings"
 	"time"
 
 	"github.com/flatrender/render-svc/internal/db"
@@ -254,18 +255,37 @@ func (h *InternalHandler) Claim(c *gin.Context) {
 		return
 	}
 
-	// Generate presigned AEP download URL. AEP files are stored at
-	// templates/{original_project_id}/template.aep in the templates bucket.
-	// Errors are non-fatal — node agent falls back to mock render when URL is empty.
+	// Resolve the canonical template object. Each template is stored once, per
+	// project id, at templates/{original_project_id}/<name> in the templates bucket
+	// and reused by every render of that template. A .zip is a full AE project
+	// bundle (.aep + footage/fonts) the node must extract before rendering.
+	// Errors are non-fatal — the node agent falls back to mock render when URL is empty.
 	aepURL := ""
+	isBundle := false
+	bundleMD5 := ""
 	if h.minio != nil {
-		objectKey := fmt.Sprintf("templates/%s/template.aep", job.OriginalProjectID)
-		purl, perr := h.minio.PresignedGetObject(
-			context.Background(), h.templatesBucket, objectKey,
-			2*time.Hour, nil,
-		)
-		if perr == nil {
+		candidates := []struct {
+			name   string
+			bundle bool
+		}{
+			{"bundle.zip", true},
+			{"template.aep", false},
+			{"template.aepx", false},
+		}
+		for _, cand := range candidates {
+			objectKey := fmt.Sprintf("templates/%s/%s", job.OriginalProjectID, cand.name)
+			info, serr := h.minio.StatObject(context.Background(), h.templatesBucket, objectKey, minio.StatObjectOptions{})
+			if serr != nil {
+				continue // not this format
+			}
+			purl, perr := h.minio.PresignedGetObject(context.Background(), h.templatesBucket, objectKey, 2*time.Hour, nil)
+			if perr != nil {
+				continue
+			}
 			aepURL = purl.String()
+			isBundle = cand.bundle
+			bundleMD5 = strings.Trim(info.ETag, "\"")
+			break
 		}
 	}
 
@@ -278,6 +298,8 @@ func (h *InternalHandler) Claim(c *gin.Context) {
 		HasMusic:       job.HasMusic,
 		HasVoiceover:   job.HasVoiceover,
 		AEPDownloadURL: aepURL,
+		IsBundle:       isBundle,
+		BundleMD5:      bundleMD5,
 	})
 }
 

services/render/internal/handlers/scan.go

@@ -0,0 +1,302 @@
+package handlers
+
+import (
+	"archive/zip"
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"path"
+	"strings"
+	"time"
+
+	"github.com/flatrender/render-svc/internal/aep"
+	"github.com/flatrender/render-svc/internal/db"
+	"github.com/flatrender/render-svc/internal/models"
+	"github.com/gin-gonic/gin"
+	"github.com/google/uuid"
+	"github.com/minio/minio-go/v7"
+)
+
+// ScanHandler exposes the headless Go "quick scan" and the async AE scan-job
+// lifecycle. Both produce the same ScanResult shape the content importer consumes.
+type ScanHandler struct {
+	store           *db.Store
+	minio           *minio.Client
+	templatesBucket string
+}
+
+func NewScanHandler(store *db.Store, mc *minio.Client, templatesBucket string) *ScanHandler {
+	return &ScanHandler{store: store, minio: mc, templatesBucket: templatesBucket}
+}
+
+// ── ScanResult shape (matches content-svc) ────────────────────────────────────
+type scanColor struct {
+	ElementKey   string `json:"element_key"`
+	Title        string `json:"title"`
+	AttrValue    string `json:"attr_value"`
+	DefaultColor string `json:"default_color"`
+	Sort         int    `json:"sort"`
+}
+type scanScene struct {
+	Key                string        `json:"key"`
+	Title              string        `json:"title"`
+	SceneType          string        `json:"scene_type"`
+	DefaultDurationSec *float64      `json:"default_duration_sec,omitempty"`
+	Sort               int           `json:"sort"`
+	Elements           []interface{} `json:"elements"`
+	Colors             []scanColor   `json:"colors"`
+}
+type scanResult struct {
+	Source       string      `json:"source"`
+	RenderComp   string      `json:"render_comp,omitempty"`
+	Scenes       []scanScene `json:"scenes"`
+	SharedColors []scanColor `json:"shared_colors"`
+}
+
+// reserved comp names that are not scenes.
+func isReservedComp(name string) bool {
+	switch strings.ToLower(name) {
+	case "frfinal", "frshare", "all":
+		return true
+	}
+	return false
+}
+
+// ── Quick scan (headless, no AE) ──────────────────────────────────────────────
+// POST /v1/template-scans/:project_id/quick
+func (h *ScanHandler) QuickScan(c *gin.Context) {
+	pid, err := uuid.Parse(c.Param("project_id"))
+	if err != nil {
+		c.JSON(http.StatusBadRequest, models.APIError{Code: "bad_request", Message: "invalid project_id"})
+		return
+	}
+	if h.minio == nil {
+		c.JSON(http.StatusServiceUnavailable, models.APIError{Code: "no_storage", Message: "object storage not configured"})
+		return
+	}
+	ctx, cancel := context.WithTimeout(c.Request.Context(), 60*time.Second)
+	defer cancel()
+
+	data, err := h.loadAep(ctx, pid)
+	if err != nil {
+		c.JSON(http.StatusNotFound, models.APIError{Code: "no_template", Message: err.Error()})
+		return
+	}
+	comps, err := aep.ParseComps(data)
+	if err != nil {
+		c.JSON(http.StatusUnprocessableEntity, models.APIError{Code: "parse_failed", Message: err.Error()})
+		return
+	}
+
+	res := scanResult{Source: "go-parser", Scenes: []scanScene{}, SharedColors: []scanColor{}}
+	for _, comp := range comps {
+		if strings.EqualFold(comp.Name, "frfinal") {
+			res.RenderComp = "frfinal"
+		}
+		if isReservedComp(comp.Name) {
+			continue
+		}
+		sc := scanScene{
+			Key: comp.Name, Title: comp.Name, SceneType: "Normal",
+			Sort: len(res.Scenes), Elements: []interface{}{}, Colors: []scanColor{},
+		}
+		if comp.DurationSec > 0 {
+			d := comp.DurationSec
+			sc.DefaultDurationSec = &d
+		}
+		res.Scenes = append(res.Scenes, sc)
+	}
+	c.JSON(http.StatusOK, res)
+}
+
+// loadAep fetches the project's template .aep bytes from MinIO — directly when a
+// raw .aep was uploaded, or by extracting the .aep from the .zip bundle.
+func (h *ScanHandler) loadAep(ctx context.Context, pid uuid.UUID) ([]byte, error) {
+	tryGet := func(key string) ([]byte, bool) {
+		if _, err := h.minio.StatObject(ctx, h.templatesBucket, key, minio.StatObjectOptions{}); err != nil {
+			return nil, false
+		}
+		obj, err := h.minio.GetObject(ctx, h.templatesBucket, key, minio.GetObjectOptions{})
+		if err != nil {
+			return nil, false
+		}
+		defer obj.Close()
+		b, rerr := io.ReadAll(obj)
+		if rerr != nil || len(b) == 0 {
+			return nil, false
+		}
+		return b, true
+	}
+
+	if b, ok := tryGet(fmt.Sprintf("templates/%s/template.aep", pid)); ok {
+		return b, nil
+	}
+	if zb, ok := tryGet(fmt.Sprintf("templates/%s/bundle.zip", pid)); ok {
+		return extractAepFromZip(zb)
+	}
+	return nil, errors.New("no .aep template uploaded for this project (a raw .aepx can only be read by the AE scan)")
+}
+
+func extractAepFromZip(zb []byte) ([]byte, error) {
+	zr, err := zip.NewReader(bytes.NewReader(zb), int64(len(zb)))
+	if err != nil {
+		return nil, fmt.Errorf("open bundle: %w", err)
+	}
+	var best *zip.File
+	bestDepth := 1 << 30
+	for _, f := range zr.File {
+		base := path.Base(f.Name)
+		if strings.HasPrefix(base, "._") || strings.Contains(f.Name, "__MACOSX") {
+			continue
+		}
+		if strings.ToLower(path.Ext(f.Name)) == ".aep" {
+			depth := strings.Count(f.Name, "/")
+			if depth < bestDepth {
+				bestDepth = depth
+				best = f
+			}
+		}
+	}
+	if best == nil {
+		return nil, errors.New("no .aep file found inside the bundle")
+	}
+	rc, err := best.Open()
+	if err != nil {
+		return nil, err
+	}
+	defer rc.Close()
+	return io.ReadAll(rc)
+}
+
+// ── AE scan jobs (async, full fidelity) ───────────────────────────────────────
+// POST /v1/template-scans/:project_id/jobs  (admin)
+func (h *ScanHandler) CreateJob(c *gin.Context) {
+	pid, err := uuid.Parse(c.Param("project_id"))
+	if err != nil {
+		c.JSON(http.StatusBadRequest, models.APIError{Code: "bad_request", Message: "invalid project_id"})
+		return
+	}
+	id, err := h.store.CreateScanJob(c.Request.Context(), pid, "ae-jsx")
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, models.APIError{Code: "internal_error", Message: err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"id": id, "status": "queued"})
+}
+
+// GET /v1/template-scan-jobs/:id  (admin)
+func (h *ScanHandler) GetJob(c *gin.Context) {
+	id, err := uuid.Parse(c.Param("id"))
+	if err != nil {
+		c.JSON(http.StatusBadRequest, models.APIError{Code: "bad_request", Message: "invalid id"})
+		return
+	}
+	j, err := h.store.GetScanJob(c.Request.Context(), id)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, models.APIError{Code: "internal_error", Message: err.Error()})
+		return
+	}
+	if j == nil {
+		c.JSON(http.StatusNotFound, models.APIError{Code: "not_found", Message: "scan job not found"})
+		return
+	}
+	c.JSON(http.StatusOK, j)
+}
+
+// ── internal (node agents, HMAC) ──────────────────────────────────────────────
+// POST /v1/internal/scan/claim
+func (h *ScanHandler) Claim(c *gin.Context) {
+	var req models.ClaimJobRequest
+	_ = c.ShouldBindJSON(&req)
+
+	claim, err := h.store.ClaimScanJob(c.Request.Context(), req.NodeID)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, models.APIError{Code: "internal_error", Message: err.Error()})
+		return
+	}
+	if claim == nil {
+		c.Status(http.StatusNoContent)
+		return
+	}
+	url, isBundle, md5 := resolveTemplateObject(h.minio, h.templatesBucket, claim.ProjectID)
+	c.JSON(http.StatusOK, gin.H{
+		"scan_job_id":      claim.ID,
+		"project_id":       claim.ProjectID,
+		"aep_download_url": url,
+		"is_bundle":        isBundle,
+		"bundle_md5":       md5,
+	})
+}
+
+// POST /v1/internal/scan/:id/result   body = ScanResult JSON
+func (h *ScanHandler) Result(c *gin.Context) {
+	id, err := uuid.Parse(c.Param("id"))
+	if err != nil {
+		c.JSON(http.StatusBadRequest, models.APIError{Code: "bad_request", Message: "invalid id"})
+		return
+	}
+	body, err := io.ReadAll(c.Request.Body)
+	if err != nil || !json.Valid(body) {
+		c.JSON(http.StatusBadRequest, models.APIError{Code: "bad_request", Message: "result must be valid JSON"})
+		return
+	}
+	if err := h.store.SetScanResult(c.Request.Context(), id, string(body)); err != nil {
+		c.JSON(http.StatusInternalServerError, models.APIError{Code: "internal_error", Message: err.Error()})
+		return
+	}
+	c.Status(http.StatusNoContent)
+}
+
+// POST /v1/internal/scan/:id/fail   body {reason}
+func (h *ScanHandler) Fail(c *gin.Context) {
+	id, err := uuid.Parse(c.Param("id"))
+	if err != nil {
+		c.JSON(http.StatusBadRequest, models.APIError{Code: "bad_request", Message: "invalid id"})
+		return
+	}
+	var req struct {
+		Reason string `json:"reason"`
+	}
+	_ = c.ShouldBindJSON(&req)
+	if req.Reason == "" {
+		req.Reason = "scan failed"
+	}
+	if err := h.store.SetScanError(c.Request.Context(), id, req.Reason); err != nil {
+		c.JSON(http.StatusInternalServerError, models.APIError{Code: "internal_error", Message: err.Error()})
+		return
+	}
+	c.Status(http.StatusNoContent)
+}
+
+// resolveTemplateObject presigns the canonical template object for a project,
+// probing bundle.zip → template.aep → template.aepx (same order as render claim).
+func resolveTemplateObject(mc *minio.Client, bucket string, projectID uuid.UUID) (url string, isBundle bool, md5 string) {
+	if mc == nil {
+		return "", false, ""
+	}
+	candidates := []struct {
+		name   string
+		bundle bool
+	}{
+		{"bundle.zip", true},
+		{"template.aep", false},
+		{"template.aepx", false},
+	}
+	for _, cand := range candidates {
+		key := fmt.Sprintf("templates/%s/%s", projectID, cand.name)
+		info, serr := mc.StatObject(context.Background(), bucket, key, minio.StatObjectOptions{})
+		if serr != nil {
+			continue
+		}
+		purl, perr := mc.PresignedGetObject(context.Background(), bucket, key, 2*time.Hour, nil)
+		if perr != nil {
+			continue
+		}
+		return purl.String(), cand.bundle, strings.Trim(info.ETag, "\"")
+	}
+	return "", false, ""
+}

services/render/internal/handlers/template_bundles.go

@@ -0,0 +1,151 @@
+package handlers
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+	"net/url"
+	"path"
+	"strings"
+	"time"
+
+	"github.com/flatrender/render-svc/internal/models"
+	"github.com/gin-gonic/gin"
+	"github.com/google/uuid"
+	"github.com/minio/minio-go/v7"
+)
+
+// TemplateBundleHandler stores the canonical After Effects template object for a
+// project. Each project has ONE template at a deterministic per-project key, and
+// every render of that project reuses it. The source may be a plain .aep/.aepx or
+// a .zip bundle (the .aep plus its footage/fonts) — the node agent extracts zips.
+type TemplateBundleHandler struct {
+	minio           *minio.Client
+	templatesBucket string
+}
+
+func NewTemplateBundleHandler(mc *minio.Client, templatesBucket string) *TemplateBundleHandler {
+	return &TemplateBundleHandler{minio: mc, templatesBucket: templatesBucket}
+}
+
+type setBundleRequest struct {
+	// SourceURL is the public/path-style MinIO URL of the freshly uploaded file,
+	// e.g. http://host:9000/user-uploads/uploads/<uid>/<uuid>.zip
+	SourceURL string `json:"source_url" binding:"required"`
+}
+
+type setBundleResponse struct {
+	Bucket   string `json:"bucket"`
+	Key      string `json:"key"`
+	MD5      string `json:"md5"`
+	Size     int64  `json:"size_bytes"`
+	IsBundle bool   `json:"is_bundle"`
+}
+
+// POST /v1/template-bundles/:project_id
+// Copies an uploaded .aep/.aepx/.zip into templates/{project_id}/(bundle.zip|
+// template.aep|template.aepx) via a server-side MinIO copy (same backend, no
+// proxy through this service), then returns the stored key + md5 so the caller
+// can record it on the project. Replacing a template overwrites the same key, so
+// in-flight and future renders pick up the new bundle (md5 changes → nodes refetch).
+func (h *TemplateBundleHandler) Set(c *gin.Context) {
+	pid, err := uuid.Parse(c.Param("project_id"))
+	if err != nil {
+		c.JSON(http.StatusBadRequest, models.APIError{Code: "bad_request", Message: "invalid project_id"})
+		return
+	}
+	var req setBundleRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, models.APIError{Code: "bad_request", Message: err.Error()})
+		return
+	}
+	if h.minio == nil {
+		c.JSON(http.StatusServiceUnavailable, models.APIError{Code: "no_storage", Message: "object storage not configured"})
+		return
+	}
+
+	srcBucket, srcKey, err := parseObjectURL(req.SourceURL)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, models.APIError{Code: "bad_source", Message: err.Error()})
+		return
+	}
+
+	ext := strings.ToLower(path.Ext(srcKey))
+	isBundle := ext == ".zip"
+	destName := "template.aep"
+	switch ext {
+	case ".zip":
+		destName = "bundle.zip"
+	case ".aepx":
+		destName = "template.aepx"
+	default: // .aep or unknown — treat as a raw project file
+		destName = "template.aep"
+	}
+	destKey := fmt.Sprintf("templates/%s/%s", pid, destName)
+
+	ctx, cancel := context.WithTimeout(c.Request.Context(), 10*time.Minute)
+	defer cancel()
+
+	// The templates bucket may not exist on a fresh deployment — create it (private;
+	// the node downloads via presigned URL, so no public policy is needed).
+	if exists, berr := h.minio.BucketExists(ctx, h.templatesBucket); berr == nil && !exists {
+		if merr := h.minio.MakeBucket(ctx, h.templatesBucket, minio.MakeBucketOptions{}); merr != nil {
+			// A concurrent request may have created it — only fail if it's still missing.
+			if ex2, _ := h.minio.BucketExists(ctx, h.templatesBucket); !ex2 {
+				c.JSON(http.StatusBadGateway, models.APIError{Code: "bucket_error", Message: merr.Error()})
+				return
+			}
+		}
+	}
+
+	// Drop any stale sibling in the other format so the claim probe (which checks
+	// bundle.zip → template.aep → template.aepx in order) can't return the old file.
+	for _, n := range []string{"bundle.zip", "template.aep", "template.aepx"} {
+		if n != destName {
+			_ = h.minio.RemoveObject(ctx, h.templatesBucket, fmt.Sprintf("templates/%s/%s", pid, n), minio.RemoveObjectOptions{})
+		}
+	}
+
+	src := minio.CopySrcOptions{Bucket: srcBucket, Object: srcKey}
+	dst := minio.CopyDestOptions{Bucket: h.templatesBucket, Object: destKey}
+	if _, err := h.minio.CopyObject(ctx, dst, src); err != nil {
+		c.JSON(http.StatusBadGateway, models.APIError{Code: "copy_failed", Message: err.Error()})
+		return
+	}
+
+	info, err := h.minio.StatObject(ctx, h.templatesBucket, destKey, minio.StatObjectOptions{})
+	if err != nil {
+		c.JSON(http.StatusBadGateway, models.APIError{Code: "stat_failed", Message: err.Error()})
+		return
+	}
+
+	c.JSON(http.StatusOK, setBundleResponse{
+		Bucket:   h.templatesBucket,
+		Key:      destKey,
+		MD5:      strings.Trim(info.ETag, "\""),
+		Size:     info.Size,
+		IsBundle: isBundle,
+	})
+}
+
+// parseObjectURL extracts the bucket and object key from a path-style storage URL
+// such as http://host:9000/<bucket>/<key...>. Query/fragment are ignored.
+func parseObjectURL(raw string) (bucket, key string, err error) {
+	u, perr := url.Parse(strings.TrimSpace(raw))
+	if perr != nil {
+		return "", "", fmt.Errorf("parse url: %w", perr)
+	}
+	p := strings.TrimPrefix(u.Path, "/")
+	if p == "" {
+		return "", "", fmt.Errorf("url has no path: %q", raw)
+	}
+	parts := strings.SplitN(p, "/", 2)
+	if len(parts) != 2 || parts[0] == "" || parts[1] == "" {
+		return "", "", fmt.Errorf("cannot derive bucket/key from %q", raw)
+	}
+	k, uerr := url.PathUnescape(parts[1])
+	if uerr != nil {
+		k = parts[1]
+	}
+	return parts[0], k, nil
+}