Academy Visual Builder (Blok Tabanlı CMS)

Achidemy academy vitrini artık sabit sayfalar yerine blok tabanlı bir render motoru ile çalışır. Eğitmen, /:lang/instructor/academy/builder üzerinden sayfayı bölüm bölüm (block) inşa eder.

• Taslak (draft): düzenlemeler academies.themeConfigDraft.blocks içine yazılır.
• Canlı (published): öğrenci storefront’u sadece academies.themeConfig.blocks okur.

---

İlgili route’lar

• Builder (CMS): /:lang/instructor/academy/builder → app/routes/instructor.academy.builder.tsx
  • Anasayfa: ?pageId yok → bloklar academies.themeConfigDraft.blocks
  • Dinamik sayfa: ?pageId=<uuid> → bloklar academy_pages.draftContent
• Deploy geçmişi: /:lang/instructor/academy/deployments → app/routes/instructor.academy.deployments.tsx
• Önizleme iframe: /:lang/builder-preview → app/routes/$lang.builder-preview.tsx
• Auth önizleme iframe: /:lang/builder-preview-auth → app/routes/$lang.builder-preview-auth.tsx
• Storefront (tenant ana sayfa): /:lang → app/routes/_index.tsx (host tenant ise blok render)
• Storefront dinamik sayfa: /p/:slug → app/routes/p.$slug.tsx

Detaylı path listesi için Route Haritası sayfasına bakın. iframe postMessage protokolü: Builder Preview.

Storefront’un taslak/canlı mantığı, deploy geçmişi ve rollback için tek kaynak doküman: Storefront Publishing, Versioning & Rollback.

---

Veri modeli: Draft vs Published themeConfig + Theme Engine

Builder’ın ürettiği temel veri yapısı academies.themeConfigDraft içindeki blocks alanıdır:

type BlockData = {
  id: string;
  type:
    | "navbar"
    | "hero"
    | "course-grid"
    | "features"
    | "footer"
    | "testimonials"
    | "pricing"
    | "faq";
  variant: string;          // v1, v2, v3...
  settings: Record<string, unknown>;
};

type ThemeConfig = {
  // legacy theme alanları olabilir (primaryColor vb.)
  blocks?: BlockData[];
  /**
   * Academy panel (instructor UI) tema ayarları
   * Bu tema instructor layout + sidebar üzerinde uygulanır.
   */
  adminTheme?: {
    branding?: { primaryColor?: string };
    typography?: { headingFont?: string; bodyFont?: string };
    ui?: { sidebarBg?: string; textColor?: string; fontSize?: number };
  };
  /**
   * Public storefront tema ayarları
   * Bu tema tenant host’unda :root CSS değişkenleri olarak enjekte edilir.
   */
  siteTheme?: {
    branding?: { primaryColor?: string; secondaryColor?: string; accentColor?: string };
    typography?: { headingFont?: string; bodyFont?: string };
    button?: {
      radius?: number;
      shadow?: string;
      shadowHover?: string;
      paddingX?: number;
      paddingY?: number;
    };
    ui?: { textColor?: string; fontSize?: number };
  };
};

Not: Builder loader’ı, eski/boş themeConfig için coerceBlocks() ve ensureCoreBlocks() ile çekirdek blokları (navbar/hero/course-grid/features/footer) otomatik tamamlar.

---

Bloklar (v1–v5)

1) Navbar

• Component: app/components/academy/blocks/NavbarBlock.tsx
• Varyant: v1, v2, v3, v4, v5
• Tipik settings: academyName, primaryColor, links[], ctaText, isLoginEnabled, logoUrl (media picker ile)

2) Hero

• Component: app/components/academy/blocks/HeroBlock.tsx
• Varyant: v1, v2, v3, v4, v5
• Tipik settings: title, subtitle, ctaText, secondaryCtaText, bgImageUrl (media picker), overlayOpacity, primaryColor, textAlign

3) Course Grid

• Component: app/components/academy/blocks/CourseGridBlock.tsx
• Varyant: v1, v2, v3, v4, v5
• Tipik settings: sectionTitle, sectionSubtitle, primaryColor, columns

Storefront’ta bu blok, tenant’a ait kurs listesini render eder.

4) Features (Neden Biz?)

• Component: app/components/academy/blocks/FeaturesBlock.tsx
• Varyant: v1, v2, v3, v4, v5
• Tipik settings: sectionTitle, sectionSubtitle, primaryColor, items[]

items[].icon DB’de string tutulur; UI’da Lucide ikonlarına map’lenir (IconMap).

5) Footer

• Component: app/components/academy/blocks/FooterBlock.tsx
• Varyant: v1, v2, v3, v4, v5
• Tipik settings: academyName, copyrightText, socialLinks{instagram,x,linkedin,facebook,youtube,tiktok}, footerLinks[]

Builder iframe önizlemede (isPreviewMode + onPreviewNavigate) navbar/footer linkleri native navigation yapmaz; mantıksal path parent’a BUILDER_PREVIEW_PATH_CHANGE ile bildirilir ve builder sol paneli ilgili sayfaya senkronlanır. Detay: Builder Preview.

Dinamik Menü Yöneticisi (Link Picker)

Navbar blok link’leri (settings.links[]) edit modunda iki şekilde yönetilir:

• Link label: Önizleme üzerinde inline (contenteditable) düzenlenir.
• Link hedefi (URL): Builder edit modunda her link için bir Link Picker (dropdown) ile seçilir.

Link Picker seçenekleri:

• Genel linkler: /, /courses, /pricing gibi sabit hedefler
• Eğitmenin oluşturduğu dinamik sayfalar: /p/:slug (academy pages)

Bu sayede eğitmen, yeni oluşturduğu sayfaları (About/Contact/FAQ vb.) Navbar menüsüne kod yazmadan bağlayabilir.

6) Testimonials

• Component: app/components/academy/blocks/TestimonialsBlock.tsx
• Varyant: v1, v2, v3
• Tipik settings: sectionTitle, sectionSubtitle, items[]

7) Pricing

• Component: app/components/academy/blocks/PricingBlock.tsx
• Varyant: v1, v2, v3
• Tipik settings: sectionTitle, sectionSubtitle, plans[], footnote

8) FAQ

• Component: app/components/academy/blocks/FaqBlock.tsx
• Varyant: v1, v2, v3
• Tipik settings: sectionTitle, sectionSubtitle, items[]

---

Builder UX: Sol rail sekmeleri

Sol ikon rail’de beş ana mod vardır (instructor.academy.builder.tsx):

Sekme	Açıklama
Bölümler	Blok listesi (header/template/footer grupları), sürükle-bırak, section library
Tema	Global site + admin panel tema (renk, tipografi, buton)
Sayfalar	In-builder sayfa yöneticisi: anasayfa + academy_pages listesi, Yeni Sayfa modal
Giriş & Kayıt	authPages tasarımı — Academy Auth Pages
SEO ve ayarlar	Site geneli SEO + sayfa bazlı meta (sayfa modunda)

Üst çubukta ek sayfa seçici (Anasayfa / dinamik sayfa dropdown) hızlı geçiş sağlar; iframe BUILDER_PREVIEW_NAVIGATE ile aynı hedefe gider.

Context-aware kayıt

Aktif hedef	Blokların kaydedildiği yer
Anasayfa (pageId yok)	academies.themeConfigDraft.blocks (+ yayınla → themeConfig)
/p/:slug (?pageId=…)	academy_pages.draftContent (JSON { blocks }); navbar/footer sayfa JSON’una yazılmaz

Global navbar, footer ve siteTheme her modda themeGlobals ile akademi kaydına merge edilir; sayfa modunda ana sayfa blokları ezilmez.

In-builder sayfa yöneticisi (Faz 6)

• Sayfalar sekmesinde tüm sayfalar listelenir; tıklanınca ?pageId= ile builder ve iframe senkronlanır.
• Yeni Sayfa Ekle → modal → action intent=create-page → academy_pages insert → otomatik yeni sayfaya geçiş.
• Ayrıntılı liste/şablon akışı: Academy Page Manager.

---

Builder UX: İkili sidebar + inline düzenleme

Builder, klasik “form alanı” yaklaşımına ek olarak önizleme üzerinde tıklayıp düzenleme akışını destekler.

Preview üzerinde seçim ve odak

• Önizlemede bir bloğa tıklanınca seçilir (ring/highlight).
• Seçilen blok için BuilderSidebar otomatik olarak:
  • Sections sekmesine geçer
  • ilgili bloğun accordion’unu açar
  • karta smooth scroll yapar ve kısa highlight uygular

Inline düzenlenebilir alanlar (contenteditable)

Seçili bloklarda bazı metin alanları direkt önizleme üzerinden düzenlenebilir:

• Hero: title/subtitle/ctaText (ve varsa secondaryCtaText)
• Navbar: academyName, ctaText, link label’ları
• CourseGrid: sectionTitle/sectionSubtitle
• Features: sectionTitle/sectionSubtitle + item title/description

Bu düzenlemeler blok settings state’ine yazılır; “Yayınla” ile DB’ye kaydedilir.

---

Kaydet (Taslak) / Yayınla (Canlıya Al)

• Builder’da iki aksiyon vardır:
  • Taslağı Kaydet: blocksData JSON’unu action’a gönderir; sadece academies.themeConfigDraft güncellenir.
  • Değişiklikleri Yayınla: draft veriyi canlıya taşır: themeConfigDraft → themeConfig.
• Aynı POST ile Theme Engine ayarları da themeGlobals üzerinden kaydedilir:
  • themeConfig.adminTheme (Academy panel UI)
  • themeConfig.siteTheme (Storefront UI)
• Tenant storefront (app/routes/_index.tsx) host tenant ise published olan tenant.themeConfig.blocks’u okuyup tüm blokları (navbar/hero/course-grid/features/footer) sırayla render eder.

Detay: Theme Engine’in siteText/sitePrimary/siteAccent gibi global ayarlarının CSS değişkenlerine nasıl çevrildiği için Academy Theme Engine (Global Tema) sayfasına bakın.

Deploy geçmişi (publish snapshot)

Yayınlama (publish) işlemi aynı zamanda deploy geçmişine bir snapshot yazar:

• academy_deployments: yayınlanan tema snapshot’ı + version
• academy_deployment_pages: yayın anındaki yayınlı sayfaların (published) snapshot’ları

Bu sayede /:lang/instructor/academy/deployments üzerinden rollback mümkündür.

---

Blok ekleme, sıralama ve silme

Builder artık sadece mevcut blokları düzenlemekle kalmaz; yeni blok ekleme ve sıralama yönetimi de sunar:

• Yeni Bölüm Ekle: “Section Library” drawer’ı üzerinden tüm blok tipleri eklenebilir (core + testimonials/pricing/faq).
• Ekleme sırası: Yeni bloklar footer bloğundan hemen önce eklenir (site kabuğu korunur).
• Sürükle-bırak sıralama: dnd-kit ile bloklar yeniden sıralanabilir.
• Sil: Bloklar silinebilir.
• Koruma: navbar ve footer blokları silinemez / taşınamaz.

---

Site Settings → bloklara nasıl etki eder?

Storefront tema ayarları siteTheme üzerinden CSS değişkenlerine dönüşür (ör. --primary, --font-heading, --btn-shadow).

Bloklar:

• settings.primaryColor boşsa var(--primary) kullanacak şekilde tasarlanmıştır.
• Fontlar --font-heading ve --font-body üzerinden okunur.

Link Yönetimi (Navbar / Footer)

Builder sidebar’ı, navbar ve footer için dinamik link yönetimi sunar:

• Link ekle/sil: label + hedef (home, courses, pricing, dinamik sayfalar)
• Footer hızlı linkleri
• Sosyal medya linkleri: Instagram, X, Facebook, LinkedIn, YouTube, TikTok

Media Manager (Görsel Seçici)

Bazı görsel alanlar (örn. Navbar logo, Hero background) statik URL input yerine Media Manager ile seçilir:

• Stock Images (Unsplash)
• Upload
• Web URL

Gelişmiş Tasarım (Blok Bazlı)

Her blok için ekstra tasarım kontrolleri:

• Background Style: transparent / surface vurgulu / inverse (koyu)
• Padding: dar / normal / geniş

Toast Bildirimleri

Kaydet/Yayınla aksiyonları sonrası toast bildirimleri gösterilir (örn. “Taslak kaydedildi”, “Yayınlandı”).

---

Canlı önizleme (iframe)

Builder sağ panelde vitrin iframe kullanır (previewIframeRef):

• Blok/tema güncellemeleri BUILDER_PREVIEW_UPDATE ile gönderilir.
• Sayfa değişiminde BUILDER_PREVIEW_NAVIGATE ile mantıksal path senkronlanır.
• Önizmede blok seçimi BUILDER_BLOCK_SELECT ile sağ inspector’ı açar.

Tam mesaj sözleşmesi: Builder Preview (iframe).

---

İlgili mimari sayfalar

• Academy Theme Engine — siteTheme / CSS değişkenleri
• Academy Page Manager — academy_pages CRUD
• Academy Auth Pages — login/register tasarımı
• Storefront Runtime — canlı vitrin render
• Storefront Publishing — draft/published ve rollback