Açılış, oturum ve API çağrıları

Bu sayfa index.html dosyasının ilk baytı ile kullanılabilir bir ana ekran arasında olanları ve sonraki her isteğin API'ye nasıl ulaştığını açıklar. webapp/js/ içindeki main.js, api.js, app-session.js, gen-api.js, meta.js ve data-bus.js dosyalarını kapsar. Sunucudaki jeton işleme mekanizma düzeyinde kimlik doğrulama ve oturumlar sayfasında anlatılır.

Kısaca¶

• boot() kayıtlı tercihleri uygular, dili yükler, giriş formunu bağlar ve sonra oturumu GET /auth/me ile kanıtlar ya da giriş ekranını gösterir (webapp/js/main.js:211-252).
• Oturum HttpOnly çerezlerde yaşar. Betik kodu yalnız oturum açmış kullanıcıyı ve izin listesini bir görüntüleme ipucu olarak tutar (webapp/js/api.js:1-6, webapp/js/api.js:26-28).
• Ana ekran görünmeden önce uygulama kataloğu, metadata belgesi ve kullanıcı arayüz durumu paralel istenir (webapp/js/home.js:439-474).
• Metadata güdümlü tüm çağrılar her yolu metadata uç bildirimlerinden kuran GenApi üzerinden geçer (webapp/js/gen-api.js:37-61).
• Açılış bittiğinde document.documentElement.dataset.appReady değeri 1 yapılır; bir hatadan sonra da (webapp/js/main.js:274-280).

Nasıl çalışır¶

Açılış sırası¶

Sıra diyagramı, geri dönen bir kullanıcı için sayfa yüklemesinden ana ekrana giden yolu gösterir.

sequenceDiagram
  participant B as Tarayıcı
  participant S as Sunucu
  participant M as main.js
  participant H as home.js
  B->>S: GET /app/
  S-->>B: damgası doldurulmuş index.html
  B->>M: main.js içe aktarımı
  M->>M: initPrefs, initA11y, initI18n
  M->>S: GET /api/v1/auth/me
  S-->>M: kullanıcı ve izinler
  M->>H: loadAppCatalog
  H->>S: GET /_meta, /_switches, /_overlay
  H->>S: GET /auth/ui-state
  H->>S: GET /app_store/registry
  H->>H: initHome, hydrateFromServer, restoreSession
  M->>B: data-app-ready = 1

Sözle:

1. Sunucu index.html dosyasını varlık damgası doldurulmuş olarak döndürür (92f8051 commit'inde src/cluster_erp/server/app.py:1616-1625). Sayfa js/main.js dosyasını modül olarak yükler (webapp/index.html:406).
2. boot(), tema ve yoğunluk için initPrefs(), erişilebilirlik ayarları için initA11y() çağırır; ikisi de ilk boyamadan öncedir (webapp/js/main.js:212-213).
3. initI18n() i18n/languages.json dosyasını okur, bir dil seçer ve sözlüğünü yükler. apply() statik işaretlemeyi çevirir (webapp/js/main.js:218-221). Bkz. uluslararasılaştırma ve diller.
4. Açılış çevrimdışı şeridini, giriş formunu, üyelik girişini, çıkış işleyicisini, ana ekran çoğaltma düğmesini, özel seçim kutusu yükseltmesini ve tablo başlığı hizalamasını kurar (webapp/js/main.js:222-231).
5. Kayıtlı bir kullanıcı varsa fetchMe() GET /auth/me çağırır. Başarı ana ekranı gösterir; başarısızlık yerel oturumu temizler ve giriş formunu gösterir (webapp/js/main.js:233-251).
6. showHome() ana ekranı göstermeden önce loadAppCatalog() sonucunu bekler; böylece yarım kurulmuş bir ekran hiç görünmez (webapp/js/main.js:31-41).
7. loadAppCatalog() loadMeta() ve loadUiState() çağrılarını başlatır, sonra GET /app_store/registry ister. Bir kez yeniden dener ve iki deneme de başarısızsa home.catalog_error gösterir (webapp/js/home.js:439-474).
8. initHome() cihaz sınıfının tahta profilini uygular, kayıtlı düzeni uzlaştırır, dock'u, yüzen tuşu ve durum satırını kurar, düzenin sunucu kopyasını benimser ve yenilemeden önce açık olan uygulamaları yeniden açar (webapp/js/home.js:4479-4562).

Oturum ve giriş¶

login() kullanıcı adını, parolayı ve beni hatırla bayrağını POST /auth/login ucuna gönderir ve çerez taşımasını ister. Sunucu HttpOnly çerezler ve kullanıcı yüküyle yanıt verir. İstemci kullanıcıyı ve izin listesini yerel depoda saklar (webapp/js/api.js:185-205). Çok kiracılı bir kurulumda şirket e-posta adresinin alan adı bölümü kiracıyı seçer (webapp/js/api.js:179-184). Kiracı yönlendirmesi çok kiracılılık sayfasında anlatılır.

isAuthenticated() yalnız kayıtlı bir kullanıcı olup olmadığına bakar. Yorum, bu ipucunun betik kodunun oturumdan görebildiği tek şey olduğunu belirtir (webapp/js/api.js:24-28). Sunucu oturumu her çağrıda kanıtlar.

hasPermission(code) kayıtlı izin listesinden yanıt verir. Liste yoksa true döner. Yorum, istemci tarafı kısıtlamanın bir görüntüleme yardımı olduğunu ve her izni sunucunun uyguladığını belirtir (webapp/js/api.js:49-55). Bkz. roller ve izinler.

logout() yerel ipucunu temizler, kaydedilmemiş her form taslağını siler ve sunucunun oturumu iptal etmesi için POST /auth/logout gönderir (webapp/js/api.js:207-226). main.js içindeki cluster:logout işleyicisi ayrıca çoğaltılmış ana ekranları kapatır, asistan ve mail durumunu sıfırlar ve sonraki girişin en yeni dağıtılmış kodu çalıştırması için sayfayı yeniden yükler (webapp/js/main.js:163-177).

API çağrıları¶

apiFetch(path, options) /api/v1 önekini ekler, JSON gönderir, sunucunun siteler arası istek denetimi olarak kullandığı özel bir istek başlığı ekler ve geçerli dille Accept-Language ekler (webapp/js/api.js:10-22, webapp/js/api.js:129-144). 2xx dışı bir yanıt durum ve ayrıştırılmış gövdeyle ApiError fırlatır (webapp/js/api.js:86-92). Bir ağ hatası tarayıcının TypeError hatasını fırlatır.

Oturum açmış bir kullanıcı için 401 yanıtında istemci bir kez oturum yenilemeyi dener ve isteği bir kez tekrarlar. Paralel 401 yanıtları tek bir yenileme isteğini paylaşır (webapp/js/api.js:94-113, webapp/js/api.js:138-141). apiFetchBlob ve apiUpload dosyalar ve çok parçalı yüklemeler için aynı kuralı izler (webapp/js/api.js:151-177).

apiErrorText(ex) bir hatayı iletiye çevirir. Dil dosyasındaki error.<code> çevirisini sunucunun hata ayrıntılarıyla doldurarak tercih eder ve sunucunun iletisine geri düşer (webapp/js/gen-api.js:11-35). Hata kodları hatalar ve istisnalar sayfasında listelenir.

GenApi sınıfı¶

GenApi(moduleName, entityMeta) yolları /<module><endpoint path> biçiminde, {id}, {parent_id} ve {scope_id} değiştirilerek kurar (webapp/js/gen-api.js:37-61).

Değiştiren her yöntem _changed çağırır; bu, modülün önbelleğe alınmış referans listelerini düşürür ve veri değişti sinyalini yayar (webapp/js/gen-api.js:48-51). Bkz. veri tazeleme ve değişiklik sinyalleri. Silme sunucuda bir devre dışı bırakmadır; bkz. yumuşak silme ve devre dışı bırakma.

Referans liste önbelleği¶

fkItems, fkPreload ve fkItem yabancı anahtar seçicileri ve sütunları için seçenek listelerinin tamamını yükler ve modül, uç ve parametrelere göre önbelleğe alır (webapp/js/gen-api.js:189-298). Bir liste baştan sona sayfalanır. Kalan sayfalar, sunucunun yansıttığı sayfa boyutuyla ve istek başına 200 tavanıyla altışar altışar istenir (webapp/js/gen-api.js:194, webapp/js/gen-api.js:203-251). resolveMissingLabels, bir listede bulunmayan kimlikler için GET /records/<module>/<entity_type>/labels sorar; böylece devre dışı kayıtlar da bir başlık gösterir (webapp/js/gen-api.js:320-351). Önbellek çıkışta ve dil değişiminde temizlenir (webapp/js/gen-api.js:362-371).

Metadata yüklemesi¶

loadMeta() /_meta, /_switches ve /_overlay uçlarını paralel ister ve eşzamanlı çağıranlar arasında tek bir isteği paylaştırır (webapp/js/meta.js:16-47). /_switches başarısız olursa her anahtar açık sayılır; /_overlay başarısız olursa ürünle gelen form korunur (webapp/js/meta.js:21-25). Belge sonra budanır ve üzerine katman uygulanır; bkz. metadata çizimi.

Yenileme ve açık uygulamalar¶

app-session.js oturum deposuna cluster.session.open_apps altında yalnız açık uygulamaların kimliklerini ve öndeki uygulamayı yazar (webapp/js/app-session.js:17-30). Bir yenilemeden sonra restoreSession() bu uygulamaları kök ekranlarında yeniden açar ve artık kurulu olmayanları atlar (webapp/js/home.js:2583-2598). Çıkış bu girdiyi siler (webapp/js/app-session.js:52-53).

Neden böyle kurulu¶

• Çerez oturumu: webapp/js/api.js:1-6 içindeki yorum, betik kodunun hiçbir zaman jeton tutmadığını, bu yüzden bu kökendeki hiçbir şeyin bir jeton okuyamayacağını belirtir.
• Hazır olma niteliği: webapp/js/main.js:268-273 içindeki yorum, giriş düğmesinin açılış bitmeden var olduğunu, bu yüzden niteliğin denetimlerin bağlandığının işareti olduğunu belirtir.
• Çıkıştan sonra yeniden yükleme: webapp/js/main.js:170-174 içindeki yorum, tam yeniden yüklemenin sonraki girişte en yeni dağıtılmış kodu çalıştırdığını belirtir.
• Altı paralel sayfa: webapp/js/gen-api.js:219-222 içindeki yorum, sıralı yürüyüşün büyük seçicileri saniyelerce beklettiğini belirtir.

Kurallar ve sınırlar¶

• Metadata bir yolu bildiriyorsa hiçbir görünüm varlık yolunu elle kurmaz. GenApi.path bildirilmemiş bir uç anahtarı için hata fırlatır (webapp/js/gen-api.js:53-56).
• Önbelleğe alınmış seçenek listeleri oturumdan uzun yaşamaz (webapp/js/gen-api.js:360-365).
• Tarayıcı testleri oturum ve yenileme davranışını sabitler: web-client/_e2e_cookie_session.mjs, web-client/_e2e_session_remember.mjs ve web-client/_e2e_refresh_session.mjs.

Diğer parçalarla etkileşim¶

• GET /api/v1/_meta ve GET /api/v1/_switches uçlarını src/cluster_erp/server/app.py:1518-1572 sunar (92f8051 commit'inde). GET /api/v1/_overlay ucunu src/cluster_erp/server/routes/tenant_fields.py:446 sunar.
• GET /api/v1/app_store/registry ucunu src/cluster_erp/modules/app_store/routes.py:18-40 sunar. Bkz. uygulama mağazası modülü.
• Etiketler, pasif listeler ve yeniden etkinleştirme için kullanılan kayıt uçları records modülüne aittir; bkz. kayıtlar modülü.

Sınırlar ve açık noktalar¶

• restoreSession() itilmiş alt ekranları geri getiremez, çünkü görünüm yığını çizim işlevlerini tutar. Yorum bunu bilinçli bir sınır olarak adlandırır (webapp/js/home.js:2579-2582).
• Başarısız bir kapılı uygulama veya metadata isteği yalnız kodun söylediği yerde yeniden denenir. loadMeta() hata durumunda false döner ve sonraki çağıranlar onu yeniden ister (webapp/js/meta.js:42-46).

Tanıtılan terimler¶

İlgili sayfalar¶

• Web uygulaması platformu
• Web uygulamasına genel bakış
• Metadata çizimi
• Kullanıcı arayüz durumu
• Kimlik doğrulama ve oturumlar

92f8051 numaralı commit ile 2026-11-13 tarihinde doğrulandı.