Mağaza Arayüzleri ve Tema Tasarımı

Tecof tema geliştirme akışı Next.js App Router, @tecof/theme-editor ve backend /api/store/* API katmanı üzerine kuruludur. Tema projesi backend'den sayfa JSON'unu alır, TecofRender ile render eder ve editör modunda TecofEditor ile aynı sayfayı düzenler.

---

Tema Runtime Akışı

sequenceDiagram
    participant Theme as Next.js Theme
    participant StoreAPI as /api/store
    participant Backend as Tecof Backend
    participant Editor as Tecof Editor

    Theme->>StoreAPI: POST /render?themeId&locale
    StoreAPI->>Backend: merchant + theme + slug çözümle
    Backend-->>Theme: publishedData + CMS data
    Theme->>Theme: TecofRender(data, config)
    Editor->>StoreAPI: GET /editor/:pageId
    Editor->>StoreAPI: PUT /editor/:pageId

Tema tarafındaki temel dosyalar:

Dosya	Görev
lib/api/store.ts	Sayfa, merchant info ve sayfa listesi fetch fonksiyonları
lib/api/ecommerce.ts	Ürün, sepet, checkout, müşteri hesabı ve push API helper'ları
app/components.tsx	Tema bileşen registry'si
app/editor-config.tsx	Editor config ve component map
components/RenderClient.tsx	TecofRender sarmalı
components/global/TecofAnalyticsWrapper.tsx	Analytics runtime script enjeksiyonu

---

Zorunlu Ortam Değişkenleri

NEXT_PUBLIC_BASE_URL=https://api.tecof.com
NEXT_PUBLIC_MERCHANT_SECRET_KEY=merchant_secret_key
NEXT_PUBLIC_THEME_ID=merchant_theme_id

NEXT_PUBLIC_MERCHANT_SECRET_KEY public bundle içinde yer alır. Bu nedenle canlı storefront için uygundur, fakat editör yazma işlemlerinde tek başına yeterli değildir; backend PUT /api/store/editor/:id için JWT/team doğrulaması da ister.

---

`@tecof/theme-editor` Kullanımı

Provider

import { TecofProvider } from "@tecof/theme-editor";

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <TecofProvider
      apiUrl={process.env.NEXT_PUBLIC_BASE_URL!}
      secretKey={process.env.NEXT_PUBLIC_MERCHANT_SECRET_KEY!}
    >
      {children}
    </TecofProvider>
  );
}

Public Render

import { TecofRender } from "@tecof/theme-editor";
import { editorConfig } from "@/app/editor-config";

export function RenderClient({ data, cmsData }: any) {
  return <TecofRender data={data} config={editorConfig as any} cmsData={cmsData} />;
}

Editor

"use client";

import { TecofEditor } from "@tecof/theme-editor";
import { editorConfig } from "@/app/editor-config";

export default function EditorPage({ pageId, accessToken }: { pageId: string; accessToken: string }) {
  return (
    <TecofEditor
      pageId={pageId}
      config={editorConfig as any}
      accessToken={accessToken}
      warnOnUnsavedChanges
    />
  );
}

---

Component Registry Kuralları

Her tema bileşeni registry'de bir key ile yayınlanır. Kaydedilmiş sayfa verisindeki content[].type değeri bu key ile eşleşmelidir.

import { Header } from "@/components/sections/Header";
import { HeroSection } from "@/components/sections/HeroSection";

export const components = {
  Header,
  HeroSection,
};

Bileşen config'i en az şu yapıyı taşımalıdır:

export const HeroSection = {
  label: "Hero",
  fields: {
    title: { type: "text", label: "Başlık" },
  },
  defaultProps: {
    title: "Yeni başlık",
  },
  render: (props: any) => <section>{props.title}</section>,
};

@tecof/theme-editor alan tipleri arasında text, textarea, select, number, boolean, range, array, object, slot, language, editor, upload, link, color, repeater, CMS collection ve icon alanları bulunur.

---

Public API'ler

Tema oluştururken verilmesi gereken temel public API yüzeyi:

Amaç	Endpoint
Yayındaki sayfayı render et	POST /api/store/render?themeId=:themeId&locale=:locale
Editör için sayfa oku	GET /api/store/editor/:pageId
Editör için sayfa kaydet	PUT /api/store/editor/:pageId
Merchant dil/logo/script bilgisi	GET /api/store/merchant-info
Link alanı için sayfa listesi	GET /api/store/pages
Upload	POST /api/store/upload
Medya listesi	GET /api/store/uploads
Otomatik çeviri	POST /api/store/translate
CMS canlı içerik	POST /api/store/cms/collections/:slug/items
E-ticaret ürün listesi	GET /api/store/ecommerce/products
Checkout session	POST /api/store/ecommerce/checkout-session

Tam tablo için Public API Referansı sayfasına bakın.

---

Analytics Entegrasyonu

tecof-theme-core, TecofAnalyticsWrapper ile backend'in servis ettiği runtime script'i yükler:

<TecofAnalyticsWrapper merchantId={merchantId} />

Script kaynağı:

/public/analytics/client.js

Event endpoint'i:

POST /api/analytics/event

Varsayılan event tipleri pageview, web-vital, cart_add, cart_remove ve checkout_start olarak doğrulanmıştır. Tema bileşenleri sepet ve checkout etkileşimlerinde trackCartAdd, trackCartRemove, trackCheckoutStart helper'larını çağırabilir.

---

Tema Oluşturma Kontrol Listesi

1. NEXT_PUBLIC_BASE_URL, NEXT_PUBLIC_MERCHANT_SECRET_KEY, NEXT_PUBLIC_THEME_ID değerlerini tanımla.
2. TecofProvider ile app'i sar.
3. app/components.tsx içinde tüm render edilebilir component key'lerini kaydet.
4. app/editor-config.tsx içinde component config'i export et.
5. Dynamic route'larda getPageData(slug, locale, showDraftData) ile /api/store/render çağır.
6. Public sayfada TecofRender, editör sayfasında TecofEditor kullan.
7. E-ticaret componentleri için lib/api/ecommerce.ts helper'larını kullan.
8. Analytics için TecofAnalyticsWrapper ve checkout event helper'larını ekle.