Güncel bölüm atıfları

GET /v1/contexts/{contextId}/chapters/{chapterId}/references adresi chapter_reference_context_get işlemini ve 84dce1b5-46dd-4c0a-8597-a298c291ae38 işlem sürümünü kullanır. Önceki 12 sürüm değişmez. Bu bağımsız sürümlü, isteğe bağlı yetenek sabit tr-passage-1 yanıtlarını, bağlamı, core veya dil hedefi kimliklerini değiştirmez.

Okuyucu Arayüzü

ReaderChapterReferencesProjection, @munderecat/reader-core paketinden alınır. ContentApiReaderRepository.getChapterReferences(chapterId, { signal? }), Promise<ReaderResult<ReaderChapterReferencesProjection>> döndürür. İletim tipi @munderecat/content-api/types içindeki ChapterReferenceContextProjection’dır.

Kullanılabilir yanıt verisi:

{
  schemaVersion: 1;
  chapterId: string;
  revision: number; // Bagimsiz, negatif olmayan yonetim surumu.
  baseline: { readerReleaseId: string; releaseKey: "tr-passage-1";
    coreReleaseId: string; textVersionId: string; coreRootSha256: string };
  counts: { placements: number; memberships: number; selections: number;
    scopes: number; bindings: number; references: number; effectiveEndpoints: number };
  placements: { placementId: string; selectionId: string; chapterId: string }[];
  memberships: { membershipId: string; placementId: string; identityId: string;
    applicability: "whole" | "excerpt_only" }[];
  selections: { selectionId: string; chapterId: string;
    spans: { sentenceId: string; startScalar: number; endScalar: number }[] }[];
  scopes: { scopeId: string; identityId: string; kind: "whole" | "subpart"; label: string | null }[];
  bindings: { bindingId: string; scopeId: string; placementId: string;
    selectionId: string; evidence: "exact" | "reviewed_variant" | "accepted_family" }[];
  references: { referenceId: string; label: string | null; text: string | null;
    source: { kind: "identity" | "scope" | "placement" | "selection" | "chapter"; id: string };
    target: { kind: "identity" | "scope" | "placement" | "selection" | "chapter"; id: string };
    sourceActive: boolean; targetActive: boolean }[];
  effectiveEndpoints: { referenceId: string; side: "source" | "target";
    kind: "identity" | "scope" | "placement" | "selection" | "chapter";
    chapterId: string; placementId: string | null; selectionId: string | null;
    identityId: string | null; scopeId: string | null; bindingId: string | null;
    evidence: "exact" | "reviewed_variant" | "accepted_family" | null }[];
}

Uç etkinliği atfın o tarafındaki bütün konumlara bakar; etkin karşılıklar ve seçim koordinatları yalnız istenen bölüme aittir. Etkin olmayan karşı uç bilgisi korunur, bir halefe sessizce taşınmaz. Bölüm dışındaki koordinatları tahmin etmeyin; kaynak/hedef konumlarını bütün çiftler halinde çoğaltmayın.

Kaynak ve Erişilebilirlik

Yerel kaynak: api_v1.get_managed_chapter_references_v1(p_chapter_id, p_deployment_id). RPC API zarfı değil, filtrelenmiş bölüm verisini veya null döndürür. Uyarlayıcı yalnız izin verilen public alanları alır. İşlem yapan kişi, özel inceleme notu, seçim parmak izi ve işlem geçmişi dışarı verilmez. Bölüm, başlangıç sürümü, ilişkiler, uç karşılıkları, cümle aidiyeti ve Unicode scalar koordinatları doğrulanır.

Veri kaynağı bu yeteneği sağlamıyorsa, RPC null dönerse veya RPC kurulmamışsa (PGRST202) normal unavailable sonucu gelir. Doğrulanmış boş bölüm sıfır sayımlarla available döner. Production R2 kaynağı aşağıdaki bağımsız yayın katmanını kullanır; başka DB’ye veya remote kaynağa kendiliğinden geçilmez. Başarılı yanıtlar bağımsız sürümü de içeren veriden türetilmiş ETag ve özel yeniden doğrulama kullanır; unavailable/hata yanıtları önbelleklenmez.

R2 Okuma Yayını

publication-references.ts yönetim verisinin yalnız public bölüm projeksiyonunu ayrı bir pakette saklar. Core, çeviri, not ve mevcut pasaj yayınları yeniden üretilmez. 29 Eylül yayımlanmış paket: yönetim sürümü 680, 298 bölüm, 18.746.679 bayt. Yayın kimliği: 7b119182514c4967245361d58fe99d0a367c1528487aacb7f5c91c2600ac26f9.

4 Ekim’de 709 sürümünün teslim paketi R2’ye yüklenip önce staging, ardından production’da etkinleştirildi: 183 aile, 412 yerleşim, 298 bölüm, 19.162.958 bayt. Yayın kimliği 1494a78c96e254d923c8c871d64f6e1e06eb42943ba6049d0b8f936993ddf7c5. İki ortamın API kataloğu ve örnek bölüm çıktıları paketle doğrulandı. Kaynak metin, API kodu, runtime ve diğer yayın pinleri değişmedi; staging erişim koruması duruyor. 680 paketi geri dönüş için saklanır. Yayın kaydı, önceki sürümle farklar ve geçiş/geri dönüş adımları data/curated/passages/reference-publication-709.md dosyasında kayıtlıdır. Paket yönetim DB’sinin yedeği değil, public okuma projeksiyonudur.

Her bölüm ayrı nesnedir; istek anında bütün korpus indirilmez. Manifest bağlamı, bölüm envanterini ve tek yönetim sürümünü sabitler. Bölüm nesnesinin boyutu ve özeti, API sözleşmesi ve ilişkileri kontrol edilir; servis ayrıca kaynak cümlelerin aidiyetini ve Unicode koordinatlarını doğrular. Bozuk yayın ana metne erişimi kesmez; ilgili references isteği hata verir. Yapılandırılmamış yetenek unavailable kalır.

node --experimental-strip-types scripts/content-api/reference-publication.mjs \
  --mode build --upstream http://127.0.0.1:55321 \
  --output .cache/content-api-references-release-candidate
node --experimental-strip-types scripts/content-api/reference-publication.mjs \
  --mode verify --package .cache/content-api-references-release-candidate

Kaynak yalnız açıkça belirtilen yerel adrestir. Derleme sırasında yönetim sürümü değişirse paket kabul edilmez. Bu salt okunur işlem DB’de hiçbir şeyi yeniden oluşturmaz. Sonraki sürüm ayrı çıktı dizinine yazılır.

Yayın için aynı komuta --mode publish, --package, --publication-id ve --bucket verilir. Mevcut S3 yayıncısı CLOUDFLARE_ACCOUNT_ID, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY ortam değerlerini kullanır. Alternatif --mode publish-wrangler, ayrıca --account-id alır ve mevcut Wrangler oturumunu kullanır; yeni kalıcı anahtar üretmez. Bu yol yüklenen her nesneyi tekrar okuyarak byte eşitliğini denetler. Manifest daima en son yazılır. İki yükleme yolunun metadata denetimleri farklı olduğundan aynı paketin devamı ilk kullanılan yöntemle yapılmalıdır. Anahtarlar günlüklerde veya repoda yer almaz.

Doğrulanmış paketin kimliği Worker’ın CONTENT_REFERENCES_PUBLICATION_ID değerine atanıp API dağıtılır. Yeni okuyucu ancak bu uç available döndükten sonra yayımlanır. Geri dönüş önceki yayın kimliğine dönmektir; corpus reset edilmez. Yerel DB’deki daha sonraki yönetim değişikliği kendiliğinden canlıya geçmez: yeni snapshot yayımlanıp pin güncellenir. Canlı yanıtın revision değeri tam olarak yayımlanmış yönetim sürümüdür, yerel DB’nin anlık sürümü değildir.

Güncel Pasaj Dizini

GET /v1/contexts/{contextId}/managed-passages güncel aileleri ve etkin yerleşimleri döndürür. managed_passage_catalog_get bağımsız bir işlemdir; sabit pasaj haritasının veya kaynak metnin yayın kimliğini değiştirmez. Yanıtta baseline, revision, identities ve placements vardır. Her yerleşim aile, seçim, bölüm ve kitap kimliğini taşır; kaynak metin kopyalanmaz. İşlem geçmişi ve özel inceleme notları bu dizine alınmaz.

Web ve mobilde ortak okuyucu şu sırayı kullanır:

1. Güncel dizinden bölümün veya seçili ailenin etkin yerleşimlerini bulur.
2. Yalnız ilgili bölümlerin güncel seçim koordinatlarını okur.
3. Mevcut doğrulanmış kaynak bölümden bu aralıkların metnini çıkarır. Unicode karakter sınırları, cümle arası ve paragraf arası ayraçlar aynen korunur.
4. Dizinin ve bölümün yönetim sürümü, kaynak tabanı ve üyelikleri uyuşmuyorsa eski yayınla tamamlamaz; yeniden deneme sunar.

Böylece başlangıç haritasında bulunmayan yeni bir aile veya başka bir bölümdeki yeni yerleşim de görülebilir. Sınır düzeltmesi halef yerleşimin yeni seçimini gösterir. Üyelik kaldırıldığında yalnız ilişki listeden çıkar; kaynak metin, eski yerleşim kimliği ve diğer konumlar korunur. Karar değişikliği yapmadan bu üç durum test verisiyle doğrulanır.

Yeni yayın biçimi munderecat.chapter-references-publication.v2, bölüm nesnelerine ek olarak küçük bir catalog.json taşır. Derleyici katalogdaki etkin üyeliklerle tüm bölüm projeksiyonlarının birebir aynı envanter olduğunu doğrular. Katalog ve bölümler aynı yönetim sürümüne aittir; manifest en son yayımlanır. V1 paketleri eski bölüm API’si için okunabilir; ancak güncel katalog yoksa yeni okuyucu sessizce eski haritaya dönmez.

Yeni kuruluma eklenen salt okunur katalog fonksiyonları:

node scripts/passages/install-management.mjs

Sonrasında yukarıdaki build/publish akışı yeni bir çıktı diziniyle kullanılır. Bu işlem corpus aktarımı, yeniden eşleştirme veya DB reset gerektirmez.

Laboratuvardan Okuyucuya

Yeni bir laboratuvar kararı gelmesi bu mekanizmayı kurmanın ön koşulu değildir. Geldiğinde izlenecek yol: gerekçeli değişiklik planı, yönetim önizlemesi, yalnız onaylanan değişikliğin uygulanması, yeni references paketi, API yayın pini. Önizleme ve işlem günlüğü özel kalır; okuyucu yalnız yayımlanmış sonucu görür. Üç ayrı teslimat birbirine karıştırılmamalıdır: DB kararının uygulanması, okuma paketinin yayımlanması ve istemci kodunun dağıtılması. Veri değişiklikleri için istemci kodunu yeniden yazmak gerekmez; bu yeni sözleşmeyi kullanan web ve mobil aynı API pinindeki veriyi okur.