# CLAUDE.md — CLV Clinics

Medikal estetik / longevity kliniği için **çok dilli (TR/EN), SEO öncelikli** kurumsal site
ve yönetim paneli. Laravel 13 + Inertia 3 + React 19 + TypeScript + Tailwind 4.

**Önce oku:** [`TODO.md`](TODO.md) (güncel durum) · [`docs/PLAN.md`](docs/PLAN.md) (plan) ·
[`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) (mimari).

## Yerel ortam

- Yığın **mylocalset** ile çalışır (Apache + PHP-FastCGI + MariaDB). Site: `https://clvclinics.test`
  (mylocalset → Projeler → clvclinics → kök dizin `public` olmalı).
- **`php` PATH'te değildir.** Her PowerShell komutundan önce:
    ```powershell
    $env:Path = (Get-ChildItem C:\Users\PC\mylocalset\bin\php -Directory | Sort-Object Name -Descending | Select-Object -First 1).FullName + ';' + $env:Path
    ```
    Composer: `php C:\Users\PC\mylocalset\bin\composer\composer.phar …` (ya da PATH'e PHP eklendikten sonra `composer …`).
- Node PATH'tedir (22.13). Araç zinciri (Vite+) 22.18+ / 24.11+ ister; 22.13 ile derleme çalışıyor ama
  destek aralığının dışında. Sorun çıkarsa mylocalset'teki Node 24'ü öne al:
  `$env:Path = 'C:\Users\PC\mylocalset\bin\node\node-v24.18.0-win-x64;' + $env:Path`. Paket yöneticisi: **npm**.
- Veritabanı: yerelde **SQLite** (`database/database.sqlite`). MariaDB'ye geçiş: `docs/DEPLOYMENT.md` §8 (demo yayını: §7).
- Yüklenen dosyalar (logo, fotoğraf, video) `storage/app/public` altındadır; `php artisan storage:link` gerekir.
- Dosya adlarında Türkçe karakter varsa (ör. `docs/subjects/*.xlsx`) yolu kabuktan geçirme; klasörü ver, dosyayı kod içinde bul.

## Komutlar

```bash
composer dev                  # sunucu + kuyruk + Vite (geliştirme)
npm run dev                   # yalnızca Vite
npm run build                 # istemci derlemesi
npm run build:ssr             # istemci + SSR derlemesi
php artisan inertia:start-ssr # SSR sunucusu (üretim derlemesiyle)

php artisan test              # PHPUnit
composer lint                 # Pint (biçimlendir)   · composer lint:check
composer types:check          # Larastan
npm run types:check           # tsc --noEmit
npm run check                 # Vite+ lint + biçim    · npm run check:fix

php artisan content:import --check   # database/content/** (kategori, işlem, yazı, sayfa, SSS, ayar) dosyalarını yalnızca doğrula
php artisan content:import           # dosyalar → DB; var olan kayıtlara dokunmaz (panel düzenlemeleri korunur)
php artisan content:import --fresh --no-interaction   # var olan kayıtları dosyalarla EZER
php artisan admin:create             # panel kullanıcısı oluştur (sorar; ya da --name= --email= --password=)
php artisan wayfinder:generate --with-form   # admin rota yardımcıları; derleme yapmadan tsc çalıştırılacaksa
```

Etkileşimli soru soran komutlara (`--fresh` onayı gibi) otomasyonda `--no-interaction` ekle; yoksa girdi bekleyip kalır.

Derlemeden sonra SSR süreci eski paketi sunmaya devam eder: `php artisan inertia:stop-ssr` (çıktısı
"Unable to connect" dese de süreç kapanır) + yeniden `inertia:start-ssr`.

## Değişmez kurallar

### İki ön yüz — karıştırma

- **Genel site:** `resources/js/site.tsx`, `resources/js/site/**`, `resources/js/pages/site/**`, `resources/css/site.css`, `resources/views/site.blade.php`.
- **Yönetim:** `resources/js/app.tsx`, `resources/js/{components,hooks,layouts,lib}/**`, `resources/js/pages/{admin,auth,settings}/**`, `resources/css/app.css`.
- Site kodu admin kodunu (shadcn/Radix dahil) **içe aktarmaz**; tersi de. İkisi arası geçiş `<a href>` ile (Inertia `<Link>` değil).

### SEO — birinci öncelik (`docs/SEO.md`)

- `<title>`, meta, canonical, hreflang, OG ve JSON-LD **sunucuda** üretilir: denetleyici `SeoData` kurar,
  `App\Seo\HeadBuilder` bunu `head` prop'una çevirir (Inertia `serverHead`; SSR yoksa `site.blade.php` aynı
  dizgileri basar). Site sayfalarında Inertia `<Head>` ile başlık/meta **yazma**.
- Yeni genel sayfa = `SiteController::page()` + `SeoData` + iki dilde rota + site haritasına giriş + SEO testi.
- Sayfa başına tek `<h1>`. İçerik SSR HTML'inde bulunmalı.
- JSON-LD'ye sayfada görünmeyen ya da boş/uydurma veri **yazma**.
- Slug değişikliği → 301 kaydı.

### Çok dillilik (`docs/I18N.md`)

- Bileşene gömülü metin yok: arayüz metni `resources/js/site/i18n/tr.ts` (kaynak) + `en.ts` (aynı tip); içerik veritabanından.
- Her dil kendi önekindedir: `/tr/…`, `/en/…`; `/` → `/tr` (301). Öneksiz adres yazma (K20).
- URL'ler **sunucudan prop olarak gelir**; istemcide rota adı çözme. PHP'de `site_route()`.
- Çeviriler JSON sütunlarındadır; `$model->t('name', $locale)` ile okunur. Genel sayfalar veriyi
  önbellekli `App\Content\Catalog` + `SitePresenter` üzerinden alır.
- Stil yazarken mantıksal sınıflar: `ms-/me-/ps-/pe-/start-/end-` (RTL hazırlığı).
- CSS `uppercase` Türkçe sayfada "i"yi "İ" yapar: İngilizce kalan adlarda `lang` ipucunu kullan
  (`lang={category.lang ?? undefined}`), marka adını JS'te büyüt.

### Uydurma veri yok (`docs/DECISIONS.md` K11)

- Sahte telefon/adres/sayı/yorum/hekim adı yazma. Bilgi yoksa alanı gizle.
- Tıbbi metinde vaat/garanti/üstünlük ifadesi yok; yan etkiler yazılır (`docs/CONTENT_MAP.md` → Yazım kuralları).

### Tasarım ve hareket (`docs/DESIGN_SYSTEM.md`, `docs/ANIMATIONS.md`)

- Renk/yazı tipi/yarıçap yalnızca `resources/css/site.css` `@theme` belirteçlerinden; bileşende sabit renk kodu yok.
- Animasyon: yalnızca `transform`/`opacity` (çizilen çizgilerde `stroke-dashoffset`); kütüphane ekleme (K21). İçerik JS'siz ve "hareketi azalt" açıkken de görünür olmalı.
  Kaydırma ele geçirilmez; akıcılık için sahneye `smooth` ver. İki tuval istisnası: hero'nun WebGL zemini
  (`docs/ANIMATIONS.md` §7) ve süreç sahnesinin çizgileri (§11, K40); üçüncüsü için karar gerekir.
- Süreç sahnesi (K40, `process-story.tsx` + `lib/line-field.ts`): sitenin kendine ait efektidir — kardeş marka
  Cellavia'nın "yolculuk" sayfasını (rota üstünde araç) **kopyalama**. Metin levhalarının saati (`--c`) yalnızca
  değişen levhaya yazılır; çizimin yeri motorda (`seat`) ve CSS'te (`--seat-x/y`) birlikte değişir; yeni adım →
  yeni biçim (`BUILDERS`). Statik hâli (JS'siz / hareket kapalı / alçak pencere) kartlardır, onu da çalışır tut.
- Anasayfada yalnızca **ana branşlar** (saç, diş, medikal estetik, erkek sağlığı — bu sırayla; `config/site.php`
  → `departments`, K37) panel ve sahne alır; diğer alanlar yalnızca bölüm başındaki dizinde, branşların ardından
  durur (başlık branş saymaz). `SiteLink`'e verilen `onMouseEnter`/`onMouseLeave` işaretçi olaylarına taşınır
  (Inertia'nın üzerine gelince ön yüklemesi kendi fare olaylarını yazar). Sahneler (`area-scenes.tsx`)
  panelin saatlerini (`--enter`, `--beat`, `--on`, `--now`…) satır içi okur, hareket kapalıyken bitmiş hâlinde
  durur. Yeni branş → yeni sahne (yoksa genel sahne). Kaydırma değişkenini bütün desteye yazma
  (`docs/PERFORMANCE.md` §5).
- İç sayfalar (K38, `docs/ANIMATIONS.md` §10): her sayfa türünün **kendi** çizimi vardır (`components/art/*`,
  `.art`); alan sahneleri anasayfaya dönmez, kategori sayfasında oynar (`TreatmentStory` +
  `art/category-scenes.tsx`; botoks/dolgu yüz haritası; yeni alan → yeni sahne, yoksa kart ızgarası).
  Çizim parçaları `sk`/`so`/`sf` + `--i` ile girer (hero'da salt CSS, başka yerde `Reveal` içinde); giriş ile
  döngü (`art-*`) aynı öğede durmaz; `.art` boyut vermez (boyutu çağıran verir); ölçeklenen grupta `sk` ile
  `non-scaling-stroke` birlikte kullanılmaz; çizimde yazı yok. `PageHero`: fotoğraf `visual`, çizim `art`;
  hero'dan sonraki bölüme `sheet`.
- Fotoğraf/video `MediaSlot` üzerinden; dosya yokken üretken SVG/CSS görünür. Dosyalar ada göre bulunur
  (`App\Content\MediaLibrary`): `storage/app/public/media/{home/hero,home/backdrop-N,home/process-N,clinic/*,categories/<key>,treatments/<key>,blog/<key>}.*`;
  küçük kopyalar `ad@800.avif` srcset olur (`Picture sizes` ver). Üyelik logoları `public/assets/certificates/`.
- Kart ızgaralarında `CardGrid` kullan (son satırda tek kart kalmaz).

### Formlar (`docs/DECISIONS.md` K34, K35, K39)

- `.env`'de `CRM_FORM_API_KEY` + `CRM_FORM_SECRET_KEY` doluyken formlar CRM'in form sayfasını çerçevede
  gösterir (`CrmForm`: randevu formunun ilk adımı, iletişim, WhatsApp bandı ve sabit düğmenin paneli);
  boşken sitenin kendi formları çalışır (`AppointmentWizard`, `ContactForm`, `WhatsAppForm` → Admin → Talepler).
  İkisini de çalışır tut.
- **WhatsApp'a doğrudan bağlantı yok (K39):** hiçbir düğme/bağlantı `wa.me` ya da bir numaraya gitmez.
  "WhatsApp ile yazın" düğmeleri kısa formu açar (ad soyad + telefon): CRM açıkken `CrmForm` (`wp=true`),
  kapalıyken sitenin `WhatsAppForm`'u (→ Talepler, `leads.channel`). Sohbetin adresi sayfa verisinde
  bulunmaz; yalnızca kaydedilen talebin yanıtında gelir ve yalnızca `FormDone` ona bağlanır. CRM akışının
  kaynağı: `crm/public/base/lp-form/documentation.html` (yereldeki CRM projesi) — forma dokunmadan önce oku.
- Randevu formunda sıra Bilgiler → Alan → Uygulama: form ilk adımda gönderilir; alan/uygulama sonradan
  `contact.interest` ile eklenir (CRM talebinde panelde `crm_customer_id` ile, sitenin talebinde kendi satırına).
- Çerçevenin içi `lib/crm-form.ts`teki stil sayfasıyla giydirilir (renkler belirteçlerden okunur); form
  sayfası yüksekliğini bildiremez → stil değişirse `crm-form.tsx`teki `FRAME` yüksekliklerini tarayıcıda yeniden ölç.
- Canlı CRM'e deneme talebi gönderme; görünümü anahtarsız/sahte anahtarla, akışı `postMessage` ile dene.

### Performans (`docs/PERFORMANCE.md`)

- Genel siteye bağımlılık eklemeden önce paket boyutunu düşün; ağır parça → dinamik `import()`.
- Üçüncü taraf betik yok (analitik yalnızca onay sonrası, ertelenmiş). İstisnalar: iletişim sayfasındaki
  harita çerçevesi (K24), formlardaki Cloudflare Turnstile (K32) ve CRM form çerçevesi (K34); hiçbiri
  görünüme yaklaşmadan (sabit düğmenin panelinde: açılmadan) yüklenmez. İlk ekrana çerçeve koyma.
- Ana iş parçacığını bloklayan kurulum yok: ağır/süs işleri boşta ve eşzamansız başlat (ör. WebGL derlemesi).
- İlk ekrandaki metne `Reveal` koyma (`hero-rise` sınıfı kullan); yazı tipi değişirse `site.css`teki
  "… Fallback" ölçülerini **tarayıcıda** yeniden ölç (normal + kalın yüz, `docs/PERFORMANCE.md` §2); süs katmanlarını
  `top/bottom` yüzdesiyle değil `translate` ile konumla (CLS).

### Yönetim paneli (`docs/ADMIN.md`)

- Arayüz Türkçe; metinler bileşende yazılır, bildirimler `lang/tr.json`, alan adları `lang/tr/validation.php`.
- Çevrilebilir alanlı formlar `useForm` + Wayfinder rota nesnesi; basit formlar ve silme onayları
  `<Form {...Controller.action.form()}>` + `ConfirmDialog`. Ortak parçalar `resources/js/components/admin/`.
- Slug'ı değişebilen kayıtlar `SlugRedirects::track()` içinde güncellenir (301 kendiliğinden eklenir).
- Yeni modül = rota (`admin.*`) + `FormRequest` + misafir erişim testi (`AccessTest` tüm `admin.*` rotalarını tarar).

## Çalışma düzeni

1. İşe başlamadan `TODO.md`'ye bak; bitince **aynı oturumda** işaretle.
2. Mimari/karar değiştiyse ilgili `docs/*.md` dosyasını ve `docs/DECISIONS.md`'yi güncelle.
3. Her değişiklikten sonra doğrula:
    ```bash
    php artisan test && composer lint:check && composer types:check
    npm run types:check && npm run check
    ```
    Görsel değişiklikte üretim derlemesi + SSR ile ekran görüntüsü al (masaüstü + mobil, TR + EN).
4. Commit yalnızca istenince. "Commit at" denince commit **ve** `git push origin main` yap; tek dal `main`, ayrı dal açma.

## Belgeler

| Dosya                    | Konu                                                    |
| ------------------------ | ------------------------------------------------------- |
| `docs/PLAN.md`           | Amaç, kapsam, fazlar, riskler                           |
| `docs/ARCHITECTURE.md`   | İki ön yüz, istek akışı, veri modeli, dizin yapısı      |
| `docs/DECISIONS.md`      | Karar günlüğü (K1…)                                     |
| `docs/CONTENT_MAP.md`    | Excel → kategori/işlem/slug eşlemesi, yazım kuralları   |
| `docs/CONTENT_GUIDE.md`  | İçerik dosyası biçimi, uzunluk sınırları, üslup         |
| `docs/CONTENT_REVIEW.md` | Hekim/hukuk incelemesi için sayfa sayfa kontrol listesi |
| `docs/SEO.md`            | SEO kuralları, JSON-LD, yayın öncesi liste              |
| `docs/I18N.md`           | Çeviri katmanları, yeni dil ekleme                      |
| `docs/DESIGN_SYSTEM.md`  | Belirteçler, bileşenler, marka değişimi                 |
| `docs/ANIMATIONS.md`     | Kaydırma motoru, sahne yazım kuralları                  |
| `docs/PERFORMANCE.md`    | Hedefler, bütçeler, ölçüm                               |
| `docs/ADMIN.md`          | Panel modülleri                                         |
| `docs/DEPLOYMENT.md`     | Sunucu, dağıtım, yayın listesi                          |
| `docs/PLACEHOLDERS.md`   | Müşteriden beklenenler ve nereden değiştirileceği       |
