API, reader ve mobil tüketicileri

Yeni /reader web yüzeyi ve Expo mobil reader, Supabase tablo veya RPC’lerini doğrudan okumaz. İkisi de generated ContentApiV1Client ve platform bağımsız @munderecat/reader-core üzerinden aynı Content API v1 sözleşmesini kullanır. API quickstart ve OpenAPI şeması temel sözleşmedir.

Ortamlar

Tüketici	Runtime	Content API URL	Kural
Web local	local	http://127.0.0.1:8788/v1	Yalnız loopback
Expo development	local	Simulator/emulator için explicit URL	Hosted ve production fallback yok
Web production	production	https://api.munderecat.com/v1	Explicit origin zorunlu
Mobil production	production	https://api.munderecat.com/v1	Explicit origin zorunlu

Web için NEXT_PUBLIC_MUNDERECAT_CONTENT_API_URL, mobil için EXPO_PUBLIC_MUNDERECAT_CONTENT_API_URL açıkça verilmelidir. Runtime değişkeni ilgili platformda local veya production olmalıdır. Eksik veya hatalı değer production’a sessiz fallback oluşturmaz.

Mevcut annotation ağırlıklı /chapters yüzeyinin Supabase transportu ayrı bir legacy consumerdır. /reader ve mobil adapter bu transportu import etmez.

Yerel çalışma

Yerel Supabase ve reader metadata hazırlandıktan sonra API ile web’i birlikte başlatın:

make db-install-data
make reader-dev

Mevcut kurulumda yalnız servisleri açmak için make db-start yeterlidir. db-install-data non-destructive bir full local setup komutudur; db-rebuild-data kullanılmaz.

Metadata kapanışını veri değiştirmeden doğrulamak için:

make db-verify-reader-metadata

Reader http://127.0.0.1:3000/reader, Content API ise http://127.0.0.1:8788/v1 adresinde açılır. Ayrı süreçler gerektiğinde:

make content-api-dev
make web-dev

Mobil geliştirme için:

Development build için iOS’ta tam Xcode ve iOS Simulator runtime’ı, Android’de Android SDK ve bir emulator veya USB ile bağlı fiziksel cihaz gerekir. Development client’ı bir kez pnpm --filter @munderecat/mobile ios veya pnpm --filter @munderecat/mobile android ile, aşağıdaki aynı EXPO_PUBLIC_* değişkenlerini vererek derleyip kurun. Sonraki çalıştırmalarda Metro’yu açın:

EXPO_PUBLIC_MUNDERECAT_RUNTIME=local \
EXPO_PUBLIC_MUNDERECAT_CONTENT_API_URL=http://127.0.0.1:8788/v1 \
  pnpm --filter @munderecat/mobile start

Android Emulator host makineye çoğunlukla 10.0.2.2 ile ulaşır; fiziksel cihazda API origini ayrıca port-forward edilmelidir.

USB ile Android Arayüz Kontrolü

İlk arayüz kontrolü, projedeki Expo SDK ile uyumlu Expo Go üzerinden de yapılabilir. Bu yol Android Studio veya native derleme gerektirmez; development client, uygulamaya özel native eklentiler ve universal link testinin yerini tutmaz. Bağımsız APK/IPA üretimi için yukarıdaki development build yolu korunur.

Mac’te brew install --cask android-platform-tools ile adb kurun. Telefonda USB hata ayıklamayı açıp cihazı bağlayın ve bilgisayarın yetkilendirme isteğini telefondan onaylayın. adb devices -l çıktısında durum device olmalıdır.

Aşağıdaki örnekte yerel Content API 8791, Metro 8081 portundadır. API’yi bir sonraki bölümdeki komutla başlatın; mevcut API bu portta açıksa tekrar başlatmayın. Metro için tek bir süreç yeterlidir:

NODE_OPTIONS=--dns-result-order=ipv4first \
EXPO_PUBLIC_MUNDERECAT_RUNTIME=local \
EXPO_PUBLIC_MUNDERECAT_CONTENT_API_URL=http://127.0.0.1:8791/v1 \
  pnpm --filter @munderecat/mobile exec expo start --go --localhost --port 8081

adb -d reverse tcp:8081 tcp:8081
adb -d reverse tcp:8791 tcp:8791
adb -d shell am start -a android.intent.action.VIEW \
  -d exp://127.0.0.1:8081 host.exp.exponent

-d tek bir USB cihazını seçer; birden fazla cihaz varsa -s SERIAL kullanın. Expo Go cihazda kurulu ve SDK 57 ile uyumlu olmalıdır. --go yalnız bu test sunucusunu seçer; projenin start komutu development client kullanmaya devam eder. IPv4 tercihi, macOS’ta localhost yalnız ::1 adresine bağlanırken Metro’nun cihaza 127.0.0.1 vermesinden doğan bağlantı hatasını önler.

USB yönlendirmesi yalnız Metro ve Content API portlarını taşır. Supabase portunu yönlendirmeyin; LAN, public tunnel veya production bağlantısı gerekmez. İşiniz bitince yalnız bu iki yönlendirmeyi kaldırın:

adb -d reverse --remove tcp:8081
adb -d reverse --remove tcp:8791

Kontrolde katalogdan bölüm açma, içindekiler, üç tema, arayüz dili, Latin / Osmanlıca / İngilizce geçişi ve uygulamayı yeniden açınca tercihlerin korunması incelenir. Expo Go’da cihaz kontrolü ile aşağıdaki tarayıcı önizlemesi ayrı doğrulamalardır. Kurulum ve bağlantı ayrıntıları: Expo geliştirme akışı ve Android cihaz bağlantısı.

iOS Simülatöründe Yerel Kontrol

Yukarıdaki Metro komutu iOS simülatörü için de kullanılabilir; adb reverse gerekmez. Yerel Content API ve Metro açıkken, Xcode Simulator’da bir cihazı başlatıp uyumlu Expo Go ile projeyi açın. Örneğin, tek cihaz boot edilmişse:

xcrun simctl openurl booted exp://127.0.0.1:8081

İngilizce bir bölüme doğrudan gitmek için:

xcrun simctl openurl booted \
  exp://127.0.0.1:8081/--/en/rays/the-sixth-ray

Metro’nun yalnız ::1:8081 üzerinde dinlemesi, 127.0.0.1 bağlantısını başarısız kılabilir. Yeni bir sunucu açmadan önce mevcut süreci kontrol edin; gerekirse yalnız Metro’yu yukarıdaki NODE_OPTIONS ile yeniden başlatın. Bu durum Content API veya Supabase verisinin bozulduğu anlamına gelmez.

macOS oturumu kilitliyken simctl ekran görüntüsü alabilir, fakat masaüstü üzerinden gönderilen dokunma/kaydırma olayları simülatöre ulaşmayabilir. Ekran görüntüsü alınabilmesi etkileşim testinin geçtiğini kanıtlamaz. Bu testte oturum açık tutulur; kilit veya parola güvenliği kapatılmaz.

Native Arayüz Önizlemesi

Xcode/Android SDK olmadan Expo’nun web hedefiyle native bileşenleri tarayıcıda inceleyebilirsiniz. Bu Next.js sitesi değil, mobil uygulamanın React Native Web çıktısıdır. Ayrı iki terminalde, mevcut yerel Supabase’e bağlı:

MUNDERECAT_CONTENT_API_PORT=8791 \
MUNDERECAT_LOCAL_WEB_ORIGIN=http://localhost:8081 \
  pnpm --filter @munderecat/content-api-runtime dev

EXPO_PUBLIC_MUNDERECAT_RUNTIME=local \
EXPO_PUBLIC_MUNDERECAT_CONTENT_API_URL=http://127.0.0.1:8791/v1 \
  pnpm --filter @munderecat/mobile exec expo start --web --localhost --port 8081

Önizleme http://localhost:8081 adresindedir. localhost yerine 127.0.0.1 kullanılacaksa API’nin izin verilen web origini de aynı olmalıdır. Mevcut Next.js/API sunucularını kapatmak veya production bağlantısına geçmek gerekmez.

pnpm --filter @munderecat/mobile test
pnpm --filter @munderecat/mobile typecheck
MUNDERECAT_MOBILE_BASE_URL=http://localhost:8081 \
  pnpm --filter @munderecat/mobile test:browser

Browser testleri hazır yerel corpusla kitap/bölüm araması, 19 arayüz dili, dar ekran/RTL, tercihler ve EN’den Osmanlıcaya geçişi kontrol eder. Dil/tema değişiminde gösterilen paragraf metinleri ve kimlikleri karşılaştırılır; yeni corpus isteği yapılmadığı da kontrol edilir. Bu testler cihaz klavyesi, VoiceOver/TalkBack ve native dokunma davranışının yerini tutmaz.

Native Metro/Hermes paketlerini SDK kurulumu olmadan ayrıca üretmek mümkündür:

EXPO_PUBLIC_MUNDERECAT_RUNTIME=local \
EXPO_PUBLIC_MUNDERECAT_CONTENT_API_URL=http://127.0.0.1:8791/v1 \
  pnpm --filter @munderecat/mobile exec expo export \
    --platform ios --platform android --output-dir ../../.cache/mobile-native-export

Bu komut IPA/APK veya mağaza yayını üretmez. Cihaz üzerinde açılış ve okuma testi, imzalı native build ve mağaza teslimi ayrı adımlardır.

Addressing ve okuma akışı

Catalog, immutable content context’i ve 298 Türkçe bölümün sırasını verir. Address projection stable bookId ve chapterId ile birleştirilir. Türkçe route sayısı 298, kabul edilmiş İngilizce route sayısı 179’dur; unavailable English için URL, sitemap veya fallback üretilmez.

Web ve native aynı canonical grammarı kullanır:

/{locale}/{book-alias}/{chapter-alias}
/tr/sozler/birinci-soz
/en/words/the-first-word

Eski /reader/{chapterId} yolu canonical adrese yönlenir. Paragraph, sentence ve heading fragmentleri stable kimliklere bağlıdır. Dil değişimi aynı source bölümün adresine gider ve geçerli fragmenti korur. Tema, yazı boyutu ve layout canonical URL’nin parçası değildir.

Reader context, target availability ve reconstruction doğrulamalarını tamamlamadan raw API cevabı render etmez. available içerik gösterir; unavailable veya pending içerik için yeni bir metin üretmez; invalid içerik kapatılır.

Kontrol sınırı

Olağan consumer değişikliğinde full corpus veya database rebuild gerekmez. İlgili paket kontrolleri:

make content-api-check
make mobile-check

Production web build’i NEXT_PUBLIC_MUNDERECAT_RUNTIME=production ve NEXT_PUBLIC_MUNDERECAT_CONTENT_API_URL=https://api.munderecat.com/v1 değerlerini birlikte kullanır. Web Access exposure’ı bu API origin ayarından bağımsızdır; reader deploymentı API publication veya database pointerını değiştirmez.