Kaynak notları, API ve okuyucu

Amaç ve sınır

Kaynak haşiyelerini ve yıldızlı notları, metni değiştirmeden web ve mobil okuyucuda erişilebilir hâle getirmek. Kişisel kullanıcı notları ve atıf ağı bu çalışmaya dahil değildir. Yerel uygulamalar yerel Content API’yi kullanır.

Başlangıç bulguları

• Kurulu ilk release: 146 formal haşiye ve 207 yıldızlı not, toplam 353 ilişki.
• Formal kayıtların marker’ları açıklama başlığından geliyor; metin içindeki çağrıların bağlı olduğu varsayılamaz.
• Kaynakta numaralı 545 açıklama etiketinin 425’i Markdown başlığı değil.
• Dar ilk taramada 542 numaralı çağrının 540’ı aynı dosyada tek bir açıklama anahtarı buluyor. Bu sayı anlam ve gövde sınırı kabulü değildir.
• İlk release’in tek kaynak boşluğu, bütün corpus için kapsam garantisi değildir.
• Bu çalışmadan önce Content API ve ortak okuyucu not capability’si sunmuyordu.

Uygulama sırası

• Çağrı, açıklama etiketi, gövde ve şüpheli biçim envanterini tamamla.
• Mevcut ilişkileri koruyarak eksik eşleştirmeleri ve kaynak boşluklarını çöz.
• Exact cümle koordinatlarına bağlı, tekrar kurulabilir yeni not sürümü üret.
• Ortak Content API ve reader-core not sözleşmesini ekle.
• Web paneli ve mobil alt paneli ekle; kaynak konumuna dönüşü koru.
• Kısa, uzun, çok parçalı, tekrarlı ve eksik açıklama örneklerini doğrula.
• Kullanıcı/geliştirici belgeleri ve yayın durumunu güncelle.

Değişmezler

Core tablo ve metinleri, token/cümle/paragraf sırası ve mevcut kimlikler değişmez. Yeni kayıtlar sürümlü ve kaynak kanıtlıdır. Yanlış veya belirsiz bir not eşleşmesi ana metni görünmez yapamaz. Açıklama başlangıcındaki etiket ile ana metindeki çağrı ayrı rollerdir. Kaynakta açıklaması bulunmayan işaret için metin üretilmez. Notların içeriği kaynak sırasıyla ve bütün parçalarıyla gösterilir.

Doğrulama yaklaşımı

Parser fixture’ları, bütün not envanteri, seçili metin eşitliği, eski kimliklerin korunması, tekrar kurulum ve ilgili API/UI testleri yeterlilik ölçütüdür. Bu katman için veritabanı reseti veya tekrarlanan ağır full-corpus audit yapılmaz.

Tamamlanan kapsam

tr-notes-2, 298 chapter için açık kapsama kaydı taşır. 174 chapter’da 831 açıklama (624 haşiye, 207 yıldızlı not) ve bir gerçek kaynak boşluğu vardır. Eski 353 not kimliği korunmuş, 478 açıklama eklenmiştir. 761 çağrı ve 834 açıklama etiketi ayrı rollerle bağlıdır. 4.426 span yalnız mevcut cümlelerdeki Unicode karakter aralıklarını işaretler; corpus kopyası değildir.

52 özel kaynak biçimi bağlamıyla incelendi. Bunlardan 12 ek açıklama etiketi kayda alındı; 11 düz metin haşiyesinde ana metne dönüş sınırı düzeltildi. Eski gövdelerin 27’sinde sonraki not, ayraç veya mektuba taşan sınır yeni sürümde düzeltildi. Yalnız boşluk farkı olan 202 seçim ve doğrulanmış iki başlık devamı aynı bırakıldı. Dört parçalı Mektubat haşiyesi tek çağrıdan bütün parçalarıyla açılır; Hutbe’deki yazar ve talebe açıklamaları ayrı tutulur.

Eksik tek açıklama Gençlik Rehberi’ndeki (*[3]) çağrısıdır. Başka eserde benzer metin bulunması, bu kaynak boşluğunu tahminle doldurmak için kullanılmaz.

Makineyle okunabilir kapsam ve kararlar: data/curated/source-notes/coverage-v2.json. Kaynak biçimleri ve gerekçeler: scripts/notes/source-exceptions.mjs.

Kurulum ve yeniden üretim

Normal kurulumda kaynak dosyaları veya eski çalışma repoları gerekmez. Migrationlar, core ve tr-notes-1 kurulduktan sonra:

make db-install-notes

Bu komut repodaki koordinat envanterini kurar. Aynı kimlik ve içerik tekrar verildiğinde yeni kayıt üretmez. Aynı release kimliğine farklı içerik verilmesi reddedilir. Ana kurulum komutları da bu adımı içerir.

Kaynak değişikliğini inceleyen geliştiriciler için yeniden üretim:

node scripts/notes/core-snapshot.mjs .cache/notes/core-snapshot.json
node scripts/notes/build-release.mjs "$SOURCE_SENTENCES" .cache/notes/core-snapshot.json .cache/notes/candidate
node scripts/notes/install-release.mjs .cache/notes/candidate/tr-notes-2.json --dry-run
make source-notes-check

Snapshot yalnız yerel çalışma önbelleğidir, git’e eklenmez. Kaynaklar mevcut cümlelere sıra ve birebir metin üzerinden bağlanır. Kabul edilmiş bir yayının değiştirilmesi yerine yeni release kimliği kullanılır; seal-release.mjs yalnız inceleme sonrası yeni envanter ve descriptor hazırlamak içindir.

İlişkisel yapı

note_control.reader_* tabloları eski not paketinin bağımsız okuyucu sürümüdür. Eski note_control.notes ve shared anchor kapanışı değiştirilmez.

Tablo	Görevi
reader_releases	Kaynak core ve önceki not sürümüyle uyumluluk, içerik kimliği.
reader_chapters	Her chapter için kapsam ve mevcut reconstruction root. Boş chapter da açıkça kayıtlıdır.
reader_notes	Kalıcı not kimliği, tür, kaynak boşluğu durumu ve kaynak kanıtı.
reader_spans	Cümle kimliği, başlangıç/bitiş koordinatı ve seçili metin özeti.
reader_markers	Notun metin içi çağrıları ve açıklama etiketleri; roller ayrıdır.
reader_body_members	Açıklamayı oluşturan span’lerin sırası ve aralarındaki exact boşluklar.

Zincir: reader_notes -> reader_markers / reader_body_members -> reader_spans -> public.sentences. Span’ler mevcut core cümlelerini kullanır; token veya cümle tablosuna kolon, kayıt veya sıralama değişikliği uygulanmaz.

import_reader_release_v2 tek transaction’da release, FK, span metni, sıralama, boşluklar ve eski not kimliklerini doğrular. Aynı cümle, kaç span tarafından kullanılırsa kullanılsın doğrulama sırasında bir kez reconstruct edilir. Anonim istemci tablolara yazamaz; yalnız açık RPC projection’ını okuyabilir.

Ortak API

GET /v1/contexts/{contextId}/chapters/{chapterId}/notes/{noteReleaseId}

Reader-core’da getNotes({ source, contentContext, noteRelease }) kullanılır. Not sürümü bağımsız olarak pin edilir. Core, catalog, hedef dil sürümleri ve mevcut API context kimliği değişmez. Kaynak chapter veya release uyumsuzsa not gösterimi reddedilir; ana metin görünmeye devam eder.

Yerel kaynak RPC’si api_v1.get_source_notes_v2(chapter_id, note_release_id) chapter-first çalışır. Çıktı not kimliğini, çağrı/etiket rollerini ve açıklamanın bütün parçalarını içerir; dosya yolları ve özel kaynak kanıtları API’ye sızmaz. DB sıra kolonları sıfırdan, API position alanları birden başlar.

Web ve mobil aynı sözleşmeyi kullanır. Türkçe metinde exact işaret tıklanabilir. Osmanlıca veya hizalı çeviri metninde Türkçe koordinatları doğrudan kullanılmaz: cümle metni birebir aynı değilse ayrı not komutu gösterilir. Bağımsız İngilizce metne varsayımsal cümle bağlantısı eklenmez. Açıklama şimdilik Türkçe kaynak metnidir; arayüz dili ile corpus dili birbirinden ayrıdır.

Yayın paketi ve etkinleştirme

Yerel DB ve API’de yeni sürüm etkin. Notlar ayrı, yalnız okunabilir bir R2 paketi olarak da hazırlandı: 298 chapter nesnesi ve bir manifest, toplam 1.509.771 bayt. Ana metin, Osmanlıca veya İngilizce paketleri yeniden üretilmedi. Yayın kimliği data/releases/tr-notes-2-reader.json içinde kayıtlı.

Kurulu yerel veriden paketi üretmek için:

node --experimental-strip-types scripts/content-api/publish-notes.mjs \
  --mode build --upstream http://127.0.0.1:55321 \
  --note-release-id 058c7fe6-ec1e-5e9e-a840-9b0d2b47c917 \
  --note-release-root e0e3b580093b6ac95cd7b0e9a054c49122222d535518fcf428c24466fcc85d39 \
  --output .cache/notes/publication

Araç ayrıca verify, publish, verify-remote modlarını sunar. R2’ye yükleme yeni prefix altında create-only yapılır; manifest en son yazılır. Mevcut core yayınının üzerine yazılmaz. Worker’da CONTENT_NOTES_PUBLICATION_ID, doğrulanmış not yayın kimliğiyle etkinleştirilir. Bu ayar yokken not capability’si kapalıdır. Eksik not nesnesi, ana metin veya hedef dil endpoint’lerini engellemez.

Bu iş paketinde R2 yüklemesi, remote DB kurulumu ve canlı uygulama deploy’u yapılmadı. Bunlar hazır paketin ayrı yayın adımlarıdır; yerel doğrulama sonucu canlıya çıkıldığı anlamına gelmez.

Okuyucu kontrolleri

• Web: Onuncu Söz’de kısa haşiye, On Dokuzuncu Mektup’ta dört parçalı uzun haşiye ve Gençlik Rehberi’ndeki kaynak boşluğu gerçek yerel veriyle açıldı.
• Panel açılıp kapanırken ana metin değişmedi. Gençlik Rehberi’nin bütün DOM metni core API reconstruction metniyle birebir karşılaştırıldı.
• 320 piksel ekranda uzun açıklama kesilmeden kayıyor; yatay taşma yok. Klavyede Escape kapanışı ve çağrı işaretine odak dönüşü doğrulandı.
• Mobil: paylaşılan API ve Expo-web üzerinde işaretten doğrudan açıklamaya geçiş, kısa alt panel ve Osmanlıca görünümü değiştirmeyen konuma dönüş doğrulandı. Bu gösterim revizyonu fiziksel Android’de ve iOS üzerinde dokunmayla henüz doğrulanmadı.
• Parser, koordinat, envanter, API sözleşmesi, yayın paketi ve web/mobil odaklı testleri eklendi. 19 arayüz dilinde not metinleri mevcut.

Okuma odaklı gösterim

Chapter not listesi ve araç çubuğundaki genel not erişimi kaldırıldı. Çağrı ve açıklama etiketleri doğrudan kendi notunu açar. Dönüştürülmüş metindeki bir cümleye birden fazla not bağlıysa her biri ayrı yerel komutla erişilebilir; arada seçim listesi gösterilmez.

reader-core/source-note-presentation.ts, numaralı köşeli parantezleri metin, sözdizimi ve sayı parçalarına ayırır. Parçaların birleşimi exact kaynak işaretidir. Yalnız sözdizimi parçaları görsel olarak gizlenir; API, reconstruction, DOM ham metni, Unicode koordinatları ve kimlikler değişmez. Sıradan metinde genel regex temizliği yapılmaz. Erişilebilir düğme adı sunum etiketini kullanır.

Aynı yardımcı, doğrulanmış gövde ve etiket aralıklarını kaynak metniyle eşitlik kontrolünden geçirir. Tam açıklama paragrafı ile cümle içindeki kısmi açıklama ayırt edilir; ana anlatım yanlışlıkla açıklama stili almaz. Kaynak gövdeleri yerlerinde açık kalır. Metni daraltma veya yeniden reconstruct etme yoktur.

Webde kısa not, işarete bağlı modal olmayan kutuda; uzun not sağ panelde açılır. Mobilde içerik yüksekliğine uyan, genişletilebilir alt panel kullanılır. Kaynak konumuna gitme, yalnız mevcut okuyucudaki gerçek cümle/paragraf kimliklerini kullanır. Bu düzenleme DB migration’ı veya yeni veri release’i gerektirmez.