# Tema Mimarisi ve Runtime

> Tecof temalarının yapısı — Next.js runtime akışı, ortam değişkenleri, temel dosyalar, bileşen kaydı (registry), vitrin API’leri ve analytics entegrasyonu.
>
> Kaynak: https://tecof-app-dev.vercel.app/storefronts · Bölüm: Tema geliştirme · Son güncelleme: 2018-10-20

Tecof temaları Next.js App Router, `@tecof/theme-editor` ve backend’in `/api/store/*` katmanı üzerine kuruludur. Tema sayfa JSON’unu backend’den alır, `TecofRender` ile render eder; panel aynı sayfayı temanın editör rotasında `TecofEditor` ile düzenletir. Yeni bir tema genelde `tecof-theme-core`’dan türetilir ve [CLI ile](/theme-quickstart) geliştirilip yayınlanır.

---

## Tema Runtime Akışı

```mermaid
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

```dotenv
NEXT_PUBLIC_BASE_URL=https://api.tecof.com
NEXT_PUBLIC_CDN_URL=https://cdn.tecof.com
NEXT_PUBLIC_MERCHANT_SECRET_KEY=merchant_secret_key
NEXT_PUBLIC_THEME_ID=merchant_theme_id
```

`tecof theme dev` bu değerleri mağazanızdan alıp `.env.local` dosyasına yazar. `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 Studio entegrasyonu

Tema üç noktada `@tecof/theme-editor` kullanır: tüm uygulamayı saran `TecofProvider`, panelin iframe ile açtığı editör rotası (`app/editor/[id]/page.tsx` → `TecofEditor`, `?token=` ile gelen JWT `accessToken` olur) ve yayın sayfalarındaki `TecofRender`. Kurulum, prop’lar ve örnek kodlar: [Tecof Studio’ya giriş](/theme-editor).

---

## Bileşen kaydı (registry)

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.

```tsx
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:

```tsx
export const HeroSection = {
  label: "Hero",
  fields: {
    title: { type: "text", label: "Başlık" },
  },
  defaultProps: {
    title: "Yeni başlık",
  },
  // className kök elemana basılmalı; yoksa bileşen editörde seçilemez
  render: (props: any) => <section className={props.className}>{props.title}</section>,
};
```

Alan tiplerinin tamamı [Alanlar](/editor-fields), bileşen yapılandırmasının tamamı (`defineSection`, slotlar, kök `className` sözleşmesi) [Bileşen yapılandırması](/editor-components) sayfasındadır.

---

## 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ı](/public-apis) sayfasına bakın.

---

## Analytics Entegrasyonu

`tecof-theme-core`, `TecofAnalyticsWrapper` ile backend’in servis ettiği runtime betiğini yükler (betik ve olay adresi `NEXT_PUBLIC_BASE_URL`’den türetilir). Aynı işi bir pakette isterseniz [`@tecof/analytics`](/packages#tecofanalytics) `TecofAnalyticsProvider` ve `useTecofAnalytics().track()` sunar:

```tsx
<TecofAnalyticsWrapper merchantId={merchantId} />
```

Script kaynağı:

```text
/public/analytics/client.js
```

Event endpoint'i:

```text
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; ikisi aynı `editorConfig`’i paylaşsın ve her bileşen `className`’i kökte bassın.
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.