Tecof Geliştirici Dokümantasyonu

Tecof geliştirici alanı; mağaza temaları, storefront API'leri, CMS içerikleri, e-ticaret akışları, webhook'lar, analytics ve AI destekli geliştirme araçlarını tek yerde açıklar.

Bu doküman, mevcut repo durumuna göre hazırlanmıştır. Üretimde doğrulanan ana kaynaklar tecof-app-backend, tecof-theme-core, tecof-theme-editor, tecof-app-frontend ve tecof-app-analytics paketleridir.

Geliştirme Kanalları

1. Tema ve Storefront Geliştirme

Tema tarafında ana yol Next.js App Router tabanlı storefront ve @tecof/theme-editor paketidir. Tema; backend'den sayfa verisini, CMS içeriğini, merchant ayarlarını ve e-ticaret verisini x-secret-key ile okur.

Başlamak için Mağaza Arayüzleri ve Tema Tasarımı sayfasına bakın.

2. Public Storefront API'leri

Canlı mağazada kullanılacak güvenli API yüzeyi /api/store/* altında toplanır. Bu katman ürün listesi, sepet doğrulama, checkout, müşteri hesabı, CMS okuma, push, bülten ve tema render verisini sağlar.

Endpoint listesi için Public API Referansı sayfasına bakın.

3. Merchant Admin ve App Entegrasyonları

Satıcı panelindeki yönetim verileri /api/merchant/* altında JWT ile korunur. Webhook yönetimi, CMS editör işlemleri, ödeme yönetimi ve e-ticaret CRUD akışları bu katmandadır.

Detaylar için Uygulama Entegrasyonu sayfasına bakın.

4. Headless CMS

CMS tarafında iki ayrım var: admin paneli için JWT korumalı collection/item yönetimi, storefront için secret-key korumalı canlı içerik okuma API'leri.

Detaylar için Headless CMS Mimarisi ve API Rehberi sayfasına bakın.

5. Analytics ve AI Ajanları

Storefront analytics runtime script'i pageview, web-vital ve checkout davranış eventlerini backend'e gönderir. AI ajanları için önerilen araç seti ise mevcut public storefront API'lerinin güvenli bir aracı katman üzerinden kullanılmasıdır.

Detaylar için Alışveriş Ajanları ve MCP Entegrasyonu sayfalarına bakın.

Kimlik Doğrulama Modeli

Katman	Kullanım	Kimlik doğrulama
Storefront read/write-safe	Canlı tema, ürün, CMS, checkout	`x-secret-key`
Customer account	Profil, adres, siparişler, yorum/favori	`x-secret-key` + customer `Authorization`
Theme editor write	Sayfa kaydetme, upload, shared component mutasyonları	`x-secret-key` + merchant/team JWT
Merchant admin	Satıcı paneli ve yönetim API'leri	JWT role/team auth
Analytics ingest	Storefront event toplama	Public `merchantId` payload

NEXT_PUBLIC_MERCHANT_SECRET_KEY temanın public bundle'ında bulunabilir. Bu nedenle backend yazma yetkisi gerektiren editör işlemleri ayrıca JWT/team doğrulaması ister.

Ortam Değişkenleri

Tema projelerinde doğrulanan temel değişkenler:

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

tecof-theme-core bu değerlerle /api/store/render, /api/store/merchant-info, /api/store/pages ve /api/store/ecommerce/* uçlarını çağırır.

Doğruluk Notu

Bu dokümanda GraphQL veya paketlenmiş @tecof/storefront-sdk birincil yol olarak anlatılmaz; mevcut kodda doğrulanan yol REST tabanlı /api/store/* contract'ıdır. Planlanan veya henüz kodda görünmeyen özellikler ayrı şekilde "plan" olarak belirtilir.