# Faunamix: Routing ve middleware mimari kararı

Bu doküman, referans olarak eklenen **OFİS** (Mustakil Villam) kodundaki model ile mevcut Faunamix tasarımını karşılaştırır ve hangi yaklaşımın korunacağını netleştirir.

## Referans model (OFİS)

- Edge middleware, PHP **`/Rewrite`** ile URL çözümler.
- Sonuç **`NextResponse.rewrite`** ile dahili rotaya çevrilir: `/Home`, `/ProductCategory`, `/Detail` vb.; kullanıcı adres çubuğunda SEO URL’yi görür.
- `RoutingType` tablosu controller/action ile Next klasör adlarını eşler.
- Sayfalar `RoutingId` vb. parametreleri query string üzerinden alır.

## Mevcut Faunamix modeli

- **`api/resolve.php`**: normalize path → `{ type, entity_id, redirect, meta }` JSON.
- **Middleware** (`frontend/middleware.ts`): resolve çağrısı **yeniden yazma yapmaz**; redirect varsa uygular, aksi halde **`Cache-Control`**, `x-faunamix-route-type`, entity id gibi **header ipuçları** ekler.
- **Sunucu bileşeni** `[...slug]/page.tsx`: güvenlik için **`resolvePublicPath` ile yeniden çözümler** (middleware header’ları tek başına güvenilir kabul edilmez — `middleware-route-contract.ts`).
- **`route_types`** tablosu (migration): tip başına **cache_profile** ve **renderer_hint** sözlüğü; gerçek bileşen eşlemesi **`frontend/lib/route-types-registry.ts`** whitelist’inde kalır (dinamik `Class::method` yok).

## Karşılaştırma özeti

| Ölçüt | OFİS tarzı rewrite | Faunamix (header + catch-all) |
|--------|---------------------|-------------------------------|
| Edge çağrı maliyeti | Yüksek (her istekte resolve + rewrite çözümlemesi) | Aynı resolve; rewrite adımı yok |
| Kod organizasyonu | Controller başına App Router klasörü | Tek catch-all; dallar `type` ile |
| Çift çözümleme | Genelde tek yerde | Middleware + RSC’de bilinçli tekrar (güvenlik) |
| SEO URL tutarlılığı | İyi | İyi |
| CDN önbelleği | Projeye bağlı (OFİS örneğinde agresif `revalidate: 1` riski) | Tip bazlı `s-maxage` (`cache-policy.ts`) |

## Karar

**Faunamix’te OFİS tarzı internal rewrite’a geçilmeyecek** (şimdilik ve öngörülebilir süre için):

1. **Güven modeli**: Resolve’un tek doğruluk kaynağı PHP + RSC tarafında kalır; Edge header’ları yalnızca CDN ve gözlem içindir.
2. **Sadelik**: Onlarca `app/{Controller}/page.js` dosyası yerine tek catch-all bakım yükünü düşürür.
3. **`route_types` + registry**: OFİS’teki iki katmanlı tip tablosunun işlevini veritabanı + TypeScript ile karşılıyoruz; gerektiğinde admin UI veya raporlama `route_types` üzerinden genişletilebilir.

**Ne zaman OFİS tarzı rewrite düşünülür?**

- Takımlar çok büyük ve sayfa başına izole bundle/test zorunlu olduğunda.
- Edge’de çözülen tip ile tamamen farklı Next segmentleri zorunlu olduğunda (nadir).

Bu koşullar oluşursa karar yeniden değerlendirilir; migration geri alınmadan paralel deneme yapılabilir.

## `site_pages.page_template` (vitrin sayfa şablonu)

`routes.type = page` olduğunda içerik **`site_pages`** kaydından gelir; React şablonu **`page_template`** ile seçilir (dinamik controller yok).

| `page_template` | Render | URL | Müşteri |
|-----------------|--------|-----|---------|
| `content` (varsayılan) | Blank CMS (`body_html` + page builder) | Panel `path` | Serbest metin / bloklar |
| `contact` | İletişim şablonu (form, harita, panel iletişim ayarları) | Panel `path` | Üst metin; form kodda |
| `about` | Hakkımızda şablonu | Panel `path` | Gövde metni |
| `legal` | Hukuki şablon + taslak bandı | Panel `path` | Metin + hukuk onayı |

**Sistem rotaları** (Next `app/*`, CMS dışı): `/`, `/sepet`, `/giris`, `/kayit`, `/hesabim`, `/odeme`, `/favoriler`, `/siparis-takip`, `/admin-v1`, … — `frontend/lib/system-routes.ts`.

**Katalog / ürün:** `routes.type` ∈ `listing`, `product_search`, `product`, `category` — `[...slug]/page.tsx` içinde ayrı dallar.

**URL değişimi:** `site_pages` create/update/delete sonrası `api/lib/site_pages_routes_sync.php` — `routes` güncellenir; eski path `redirect_to` + 301.

**Menü:** `nav_menu_items.site_page_id` (opsiyonel) — sayfa path değişince bağlı menü URL’si güncellenebilir.

Kayıt: `frontend/lib/page-templates-registry.ts`, migration `database/migration_site_pages_page_template.sql`.

## İlgili dosyalar

- Middleware: `frontend/middleware.ts`, `frontend/lib/middleware-resolve-fetch.ts`
- Sözleşme: `frontend/lib/middleware-route-contract.ts`
- Catch-all: `frontend/app/[...slug]/page.tsx`
- Tip whitelist: `frontend/lib/route-types-registry.ts`
- Sayfa şablonları: `frontend/lib/page-templates-registry.ts`
- Routes sync: `api/lib/site_pages_routes_sync.php`
- Şema: `database/migration_route_types.sql`, `database/migration_site_pages_page_template.sql`
- MySQL sorgusu (ortam yüklemeli): `./scripts/mysql-with-env.sh -e "SELECT * FROM route_types;"` — `api/.env` dışında çalışan kabukta `mysql -u\"$DB_USER\"` kullanmayın; `DB_USER` boşken `-p` kullanıcı adı sanılabilir.