# Mimari

> Kaynak plan: [`PLAN.md`](PLAN.md) · Kararlar: [`DECISIONS.md`](DECISIONS.md)

## 1. Genel bakış

```
Tarayıcı ──► Apache/Nginx ──► Laravel 13
                                 │
                 ┌───────────────┼────────────────┐
                 ▼               ▼                ▼
           Genel site         Yönetim          Teknik uçlar
        (Inertia + SSR)   (Inertia, SSR yok)  sitemap.xml · robots.txt · /up
        oturumsuz, çerezsiz  oturum + CSRF
                 │               │
                 ▼               ▼
        resources/js/site.tsx   resources/js/app.tsx
```

Tek Laravel uygulaması, **iki ayrı Inertia ön yüzü** barındırır. İkisi de aynı veritabanını
ve aynı PHP katmanını kullanır; JS/CSS paketleri, kök Blade görünümleri, ara katman grupları
ve SSR ayarları ayrıdır.

## 2. İki ön yüz

|                     | Genel site                       | Yönetim                                                 |
| ------------------- | -------------------------------- | ------------------------------------------------------- |
| Rotalar             | `routes/site.php`                | `routes/web.php` (+ `settings.php`, Fortify) — `/admin` |
| Ara katman grubu    | `site` (oturum yok, çerez yok)   | `web` (oturum, CSRF)                                    |
| Inertia ara katmanı | `HandleSiteInertiaRequests`      | `HandleInertiaRequests`                                 |
| JS girişi           | `resources/js/site.tsx`          | `resources/js/app.tsx`                                  |
| CSS girişi          | `resources/css/site.css`         | `resources/css/app.css`                                 |
| Kök görünüm         | `resources/views/site.blade.php` | `resources/views/app.blade.php`                         |
| Sayfa bileşenleri   | `resources/js/pages/site/**`     | `resources/js/pages/admin/**`, `auth/**`, `settings/**` |
| Ortak kod           | `resources/js/site/**`           | `resources/js/{components,hooks,layouts,lib}/**`        |
| SSR                 | Açık                             | Kapalı                                                  |
| UI kiti             | Siteye özel bileşenler           | shadcn/ui (Radix)                                       |
| Dizinleme           | Canlıda açık (`SEO_INDEXING`)    | Her zaman `noindex`                                     |

**Kurallar**

- `resources/js/site/**` ve `pages/site/**` içinden admin kodu (`@/components/ui/*` vb.)
  **içe aktarılmaz**; tersi de geçerlidir.
- İki ön yüz arasında geçiş **tam sayfa yüklemesidir** (`<a href>`), Inertia `<Link>` değil —
  kök görünümleri ve paketleri farklıdır.
- Hangi ön yüzün yanıt vereceğini **rota grubu** belirler: `bootstrap/app.php` içinde `web`
  grubuna admin ara katmanları, `site` grubuna genel site ara katmanları eklenir.

## 3. İstek akışı (genel site)

1. Rota eşleşir (`site.{dil}.{ad}`) → `SetLocale` dili rotadan belirler (`tr` | `en`).
2. Denetleyici (`App\Http\Controllers\Site\*`, hepsi `SiteController`dan türer) veriyi önbellekli
   **`Catalog`**dan alır; tam sayfa gövdesi gerekiyorsa modeli yükler.
3. **`SitePresenter`** veriyi React'in beklediği biçime çevirir (yalnızca o dilin metinleri, hazır URL'ler,
   varsa fotoğraf/video — `MediaLibrary`). Biçimler `resources/js/site/types.ts` ile eşleşir.
4. Denetleyici bir **`SeoData`** kurar ve sayfayı `SiteController::page()` ile döndürür. Bu yöntem
   `HeadBuilder` ile `<head>` öğelerini (`head` prop'u), dil değiştirici hedeflerini (`alternates`) ve
   görünür kırıntı yolunu (`breadcrumbs`) ekler — bunlar olmadan genel sayfa çıkarılamaz.
5. İlk istekte SSR HTML'i döner (`head` ilk HTML'de); sonraki gezinmeler Inertia XHR ile (JSON) yapılır
   ve istemci `<head>`i eşitler. SSR süreci erişilemezse `site.blade.php` aynı `head` dizgilerini basar:
   `<title>`, meta, hreflang ve JSON-LD **her durumda ilk HTML'dedir** (K3, K13).
6. Yanıt: çerez yok, `Cache-Control: public, max-age=0, must-revalidate` + `ETag`
   (değişmediyse `304`), güvenlik başlıkları, dizinleme kapalıysa `X-Robots-Tag: noindex`.

Her sayfada bir kez gönderilen ortak veriler (`site`, `nav`, `locales`) Inertia "once" prop'larıdır:
site içi gezinmede yeniden gönderilmez.

Bulunamayan adresler önce `redirects` tablosuna, büyük harf düzeltmesine ve eksik dil önekine bakar (301), sonra
o dilin düzeniyle **yerelleştirilmiş hata sayfasını** gerçek durum koduyla (404, 500…) döndürür
(`App\Http\ErrorPages`).

## 4. Dizin yapısı

```
app/
  Console/Commands/   content:import, admin:create
  Content/            ContentFiles (dosya şeması + doğrulama), ContentImporter, Catalog (önbellekli okuma),
                      Departments (ana branşlar → alanlar, K37), Blog (yayındaki yazılar),
                      SitePresenter (React için biçimlendirme), MediaLibrary (ada göre fotoğraf/video)
  Enums/              LeadStatus
  Http/
    Controllers/
      Site/           Genel site denetleyicileri (+ SitemapController, RobotsController)
      Admin/          Yönetim denetleyicileri
      Settings/       Starter kit: profil, güvenlik
    Middleware/       SetLocale, HandleSiteInertiaRequests, HandleInertiaRequests, SecurityHeaders,
                      RobotsTag, SameOrigin, HandleAppearance
    Requests/         Site/StoreLeadRequest, Admin/*Request, Settings/*
    ErrorPages.php    Yerelleştirilmiş hata sayfaları
  Models/             TreatmentCategory, Treatment, Post, Page, Faq, Lead, Setting, Redirect, User
                      (+ Concerns/HasTranslations)
  Seo/                SeoData, HeadBuilder, SchemaGraph, Schemas (JSON-LD), Sitemap
  Settings/           SiteSettings (önbellekli site ayarları)
  Support/            Locales, helpers.php (site_route, site_url), Redirects, SlugRedirects,
                      FontPreloads, ScriptPriority, RecordKey, Translations
config/
  site.php            Diller, marka varsayılanları, dizinleme anahtarı
database/
  content/            İlk içerik (JSON) — categories/, treatments/<kategori>/, posts/, pages/,
                      faqs.json, settings.json (iletişim bilgileri)
  migrations/ seeders/ factories/
lang/
  tr/ en/             routes.php (rota segmentleri), site.php (sunucu metinleri), validation.php …
resources/
  css/site.css        Tasarım belirteçleri + site stilleri + hareket CSS'i
  css/app.css         Yönetim (shadcn) stilleri
  js/site.tsx         Genel site girişi (istemci ve SSR)
  js/app.tsx          Yönetim girişi
  js/site/            components/ (layout, sections, ui, motion, art, media) · hooks/ · i18n/ · layouts/ · lib/ · types.ts
  js/pages/site/      home, treatments/{index,category,show}, about, contact, faq, legal, error
  js/pages/admin/     Yönetim sayfaları (pano, talepler, kategoriler, işlemler, SSS, sayfalar, yönlendirmeler, site ayarları)
  views/              site.blade.php, app.blade.php, sitemap.blade.php
routes/
  site.php            Dile göre üretilen genel rotalar + sitemap.xml + robots.txt
  web.php             /admin/** (panel modülleri)
  settings.php        /admin/settings/** (profil, güvenlik, görünüm)
storage/app/public/   Yüklenen dosyalar: logo, media/ (→ /storage, `php artisan storage:link`)
docs/                 Bu belgeler
```

## 5. Veri modeli

Çevrilebilir alanlar JSON sütunlarında `{"tr": …, "en": …}` biçiminde tutulur.
`HasTranslations` yardımcısı `->t('name', $locale)` ile okur; metinlerde eksik çeviri varsayılan
dile düşer, ad ve slug'da düşmez (kayıt o dilde yok sayılır).

| Tablo                  | Amaç                       | Öne çıkan alanlar                                                                                                                                                                                   |
| ---------------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `treatment_categories` | 11 kategori                | `key`, `name`, `slug`, `tagline`, `summary`, `content` (giriş, öne çıkanlar, SSS), `seo_title`, `seo_description`, `icon`, `accent`, `sort_order`, `is_published`                                   |
| `treatments`           | 71 işlem                   | `treatment_category_id`, `key`, `name`, `slug`, `excerpt`, `content` (yapılandırılmış gövde), `facts`, `zone`, `seo_*`, `source_label`, `is_featured`, `is_published`, `reviewed_by`, `reviewed_at` |
| `pages`                | Yasal sayfalar             | `key`, `title`, `body` (Markdown), `seo_*`, `is_published`                                                                                                                                          |
| `faqs`                 | Genel SSS                  | `key`, `question`, `answer`, `sort_order`, `is_featured`, `is_published`                                                                                                                            |
| `leads`                | İletişim/randevu talepleri | `crm_customer_id`, `name`, `phone`, `email`, `treatment_category_id`, `treatment_id`, `message`, `locale`, `source_path`, `consent_at`, `ip_address`, `user_agent`, `status`, `note`                |
| `settings`             | Site ayarları              | `group`, `key`, `value` (JSON)                                                                                                                                                                      |
| `redirects`            | 301/302 yönlendirmeler     | `from_path`, `to_path`, `status_code`, `hits`, `last_hit_at`                                                                                                                                        |
| `users`                | Panel kullanıcıları        | Starter kit + Fortify 2FA sütunları                                                                                                                                                                 |

`key` her kayıtta **değişmez kimliktir** (İngilizce, ör. `forehead-botox`): içerik dosyası, medya
dosyası ve iletişim formundaki `?t=` parametresi onu kullanır; slug'lar değişse de `key` aynı kalır.

**Ana branşlar** (K37) bir tablo değildir: `config/site.php` → `departments` her branşın alanlarını
(kategori anahtarları) sırasıyla listeler — saç, diş, medikal estetik (botoks, dolgu, mezoterapi, cihazlı
işlemler, güzellik), erkek sağlığı; branş adları `lang/{dil}/site.php` → `departments`. `App\Content\Departments`
bunu yayındaki kataloğa uygular (branşlar, ardından "diğer alanlar"); anasayfa panelleri, menüler ve
`/tedaviler` bu gruplamayı kullanır.

**İşlem gövdesi (`treatments.content.{dil}`)**

```jsonc
{
    "lead": "Hero altındaki giriş paragrafı",
    "what": ["Nedir? paragrafları"],
    "who": ["Kimler için uygun? maddeleri"],
    "steps": [{ "title": "Adım başlığı", "text": "Açıklama" }],
    "aftercare": ["İşlem sonrası maddeleri"],
    "risks": ["Olası yan etkiler"],
    "results": "Sonuçlar ve kalıcılık paragrafı",
    "faq": [{ "q": "Soru", "a": "Cevap" }],
}
```

Dosya biçiminin tamamı, uzunluk sınırları ve üslup kuralları: [`CONTENT_GUIDE.md`](CONTENT_GUIDE.md).

**İçerik yaşam döngüsü**

`database/content/**.json` → `php artisan content:import` → veritabanı → admin panelden düzenleme.
İçe aktarma varsayılan olarak **yalnızca eksik kayıtları ekler**; panelde yapılan düzenlemeleri
ezmez (`--fresh` ile ezilir). `--check` yalnızca dosyaları doğrular. JSON dosyaları ilk içeriğin
sürüm kontrollü kaynağıdır; canlıda doğruluk kaynağı veritabanıdır (K6).

**Medya** veritabanında tutulmaz: fotoğraf/videolar dosya adına göre bulunur (K17,
[`PLACEHOLDERS.md`](PLACEHOLDERS.md) §Medya).

## 6. Çok dillilik

Her dil kendi önekindedir: `/tr/tedaviler`, `/en/treatments` (K20); `/` → `/tr` (301).
Rota segmentleri `lang/{dil}/routes.php` dosyasından, slug'lar veritabanından gelir.
İstemci tarafında rota adı çözülmez: **tüm URL'ler sunucudan prop olarak gelir**.
Ayrıntı: [`I18N.md`](I18N.md).

## 7. Önbellek

| Katman   | Ne                                                                                          | Geçersiz kılma                                                         |
| -------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| Uygulama | `Catalog`: dil başına yayınlanmış kategori/işlem ağacı (`Cache::rememberForever`)           | Kategori/işlem `saved`/`deleted` olayında ve içe aktarmada sürüm artar |
| Uygulama | `SiteSettings`: tüm ayarlar tek anahtarda                                                   | Ayar kaydedildiğinde                                                   |
| HTTP     | Genel sayfalar: `max-age=0, must-revalidate` + `ETag` → değişmediyse `304`                  | İçerik değişince `ETag` değişir                                        |
| HTTP     | `public/build/*` sürümlü dosyalar: 1 yıl, `immutable`; diğer görseller/yazı tipleri 1 hafta | Dosya adı karması; medya adreslerinde `?v=<değişme zamanı>`            |
| Laravel  | `config`/`route`/`view`/`event` önbelleği                                                   | Dağıtımda `php artisan optimize`                                       |

Tam sayfa (HTML) önbelleği yoktur; gerek duyulursa sayfalar herkese aynı olduğu için (çerez yok)
öne bir vekil/CDN konabilir — `Vary: X-Inertia` başlığına uyulmalıdır.

## 8. Güvenlik

- Yönetim: `/admin/**`, Fortify oturumu + isteğe bağlı 2FA; kayıt kapalı; ilk kullanıcı `php artisan admin:create`.
  Seeder kullanıcı oluşturmaz (K19).
- Log viewer: `/admin/log-viewer`, `viewLogViewer` kapısı → yalnızca giriş yapmış kullanıcı.
- Genel site oturumsuzdur (K14). İletişim formu: aynı-köken denetimi (`SameOrigin`), hız sınırı
  (10 dakikada 5 istek / IP), honeypot alanı, zorunlu KVKK onayı, Cloudflare Turnstile (anahtarlar
  girilince; K32); sunucu tarafı doğrulama. Aynı uç anasayfadaki randevu sihirbazına da hizmet eder.
- WhatsApp'a bağlantı yoktur (K39): "WhatsApp ile yazın" düğmeleri kısa formu açar. Sohbetin adresi sayfa
  verisinde bulunmaz (`site.whatsapp` yalnızca formun ayarlarıdır); CRM kapalıyken kısa form aynı uca
  `channel: whatsapp` ile gider (`leads.channel`) ve adres yalnızca kaydedilen talebin yanıtında döner
  (`SitePresenter::whatsappUrl()`); CRM açıkken numarayı CRM verir.
- CRM formları açıkken (`CRM_FORM_*` anahtarları, K34) talep bu uca gelmez: formlar CRM'in form sayfasını
  çerçevede gösterir, talep tarayıcıdan doğrudan CRM'e gider (`App\Support\CrmForms` → `site.crm`).
  Çerçeveden gelen iletiler yalnızca CRM'in kökeninden ve o çerçevenin penceresinden kabul edilir; sayfa
  adresindeki parametrelerden yalnızca kampanya alanları çerçeveye aktarılır.
- Randevu formunun sonraki adımları (alan, uygulama) `contact.interest` ucuna gider (aynı-köken denetimi,
  10 dakikada 30 istek / IP). Talebi iki yoldan biri adlandırır: CRM'in müşteri numarası (`customer`; satır
  `leads.crm_customer_id` ile tutulur, iletişim bilgisi içermez) ya da sitenin kendi formuna verilen şifreli
  belirteç (`lead`; talebin kimliği tahmin edilebilir olduğu için). İkisi de yalnızca son 6 saatin
  talebine dokunur; yanıt her durumda aynıdır (204).
- Yanıt başlıkları (`SecurityHeaders`): `X-Content-Type-Options`, `Referrer-Policy`,
  `Permissions-Policy`, `X-Frame-Options`; canlıda HSTS.
- Markdown içerik (yasal sayfalar) HTML'e çevrilirken ham HTML ayıklanır.
- Web sunucusunun kök dizini **`public/`** olmalıdır; aksi hâlde `.env` dahil proje dosyaları dışarı açılır.

## 9. Test stratejisi

| Tür               | Kapsam                                                                                                                                                                  |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Özellik (PHPUnit) | `tests/Feature/Site`: her rota iki dilde, SEO etiketleri, hreflang karşılıklılığı, site haritası, form, önbellek başlıkları, medya · `Feature/Admin`: yetki ve modüller |
| İçerik            | `tests/Feature/Content`: dosya şeması, Excel listesinin eksiksizliği, slug benzersizliği, içe aktarma, seeder                                                           |
| Statik            | Larastan (seviye 7), Pint, `tsc --noEmit`, `vp check`                                                                                                                   |
| Görsel/elle       | Üretim derlemesi + SSR ile başsız tarayıcı ekran görüntüleri (masaüstü + mobil, TR + EN, JS'siz, hareket azaltılmış, yazı tipsiz), Lighthouse                           |
