API istemcisi ve çalışanlar

Bu sayfa masaüstü istemcinin sunucu API'sine nasıl ulaştığını açıklar. src/cluster_erp/desktop/ altındaki core/api_client.py (ApiClient ve hata sınıfları), core/api_worker.py (ApiWorker, ApiMixin, format_api_error), core/generic_api.py (GenericApi) ve core/core_api.py (not, ek ve e-posta sarmalayıcıları) dosyalarını kapsar. Değişikliklerin yaydığı sinyaller sinyal veri yolu ve watch_entity sayfasında açıklanır.

Kısaca¶

• Tek bir ApiClient, 30 saniyelik zaman aşımı, bir temel adres ve bir Accept-Language başlığı olan tek bir httpx.Client sarar (src/cluster_erp/desktop/core/api_client.py:80-96).
• Ekranlar çağrıları ApiMixin.call_api üzerinden bir QThread olan ApiWorker içinde yürütür. Sonuçlar ve hatalar Qt sinyalleri olarak döner (src/cluster_erp/desktop/core/api_worker.py:28-65, src/cluster_erp/desktop/core/api_worker.py:187-259).
• Bir entity tanımlayıcısıyla çağrılan değişiklik, sunucu yanıt verdikten sonra bir değişiklik sinyali yayar (src/cluster_erp/desktop/core/api_client.py:223-294).
• HTTP hataları türlü istisnalara dönüşür ve format_api_error bunları kullanıcının dilinde bir iletiye çevirir (src/cluster_erp/desktop/core/api_client.py:55-77, src/cluster_erp/desktop/core/api_worker.py:108-176).
• GenericApi her varlık yolunu metadata'daki uç bildirimlerinden kurar (src/cluster_erp/desktop/core/generic_api.py:24-31).

Nasıl çalışır¶

API istemcisi¶

ApiClient.__init__, httpx.Client nesnesini temel adresle, 30 saniyelik zaman aşımıyla, yönlendirmeleri izleyecek biçimde ve Accept-Language değeri en olarak oluşturur (src/cluster_erp/desktop/core/api_client.py:81-91). Ardından main() çevirmenin dilini ayarlar ve her dil değişikliği başlığı günceller (src/cluster_erp/desktop/main.py:169-172, src/cluster_erp/desktop/core/api_client.py:110-112). set_base_url, httpx.Client nesnesini değiştirir ve başlıklarını korur (src/cluster_erp/desktop/core/api_client.py:98-108).

login, kullanıcı adını ve parolayı /auth/login ucuna gönderir. Başarı durumunda erişim belirtecini, yenileme belirtecini, kullanıcıyı ve izin listesini bellekte tutar ve erişim belirtecini sonraki her isteğe ekler (src/cluster_erp/desktop/core/api_client.py:134-163). Belirteçler ayar deposuna yazılmaz: istemcinin yazdığı ayar anahtarlarının tamamı diller, temalar ve erişilebilirlik sayfasında listelenir. logout dördünü de bellekte temizler (src/cluster_erp/desktop/core/api_client.py:165-171). Sunucudaki belirteç işleme kimlik doğrulama ve oturumlar sayfasında açıklanır.

_request tek bir istek gönderir. Yanıt 401 olduğunda _try_refresh_token işlevini bir kez çağırır ve yenileme başarılıysa isteği bir kez yineler (src/cluster_erp/desktop/core/api_client.py:335-349). Başarısız bir yenileme belirteçleri temizler ve sinyal veri yolunda session_expired yayar (src/cluster_erp/desktop/core/api_client.py:173-211). 204 yanıtı None döndürür; diğer her başarı ayrıştırılmış JSON döndürür (src/cluster_erp/desktop/core/api_client.py:350-353). download aynı yenileme kuralını izler ve baytları, içerik türünü ve dosya adını döndürür (src/cluster_erp/desktop/core/api_client.py:296-324).

ApiClient içindeki kilit tüm gidiş-dönüş boyunca değil, yalnızca geçerli httpx.Client okunurken ve bir belirteç yenilemesi sırasında tutulur. Yorum, aksi halde yavaş bir arka plan isteğinin GUI iş parçacığından gelen çağrıları donduracağını belirtir (src/cluster_erp/desktop/core/api_client.py:336-341).

Hata sınıfları¶

_parse_error_response durum kodunu bir istisna sınıfına eşler ve sunucunun hata gövdesini okur. error nesnesi olan bir gövde message, code, trace_id ve details alanlarını doldurur; başka bir gövde yalnızca detail alanından iletiyi doldurur (src/cluster_erp/desktop/core/api_client.py:64-77). Bir aktarım hatası durum 0 ve CONNECTION_ERROR koduyla ApiError fırlatır (src/cluster_erp/desktop/core/api_client.py:359-364).

Sunucunun hata kodları hatalar ve istisnalar sayfasında listelenir.

Çalışan iş parçacığı modeli¶

Diyagram, ApiMixin karıştıran bir ekrandan yapılan tek bir çağrıyı gösterir.

sequenceDiagram
  participant V as ApiMixin içeren ekran
  participant W as ApiWorker QThread
  participant A as ApiClient
  participant S as Sunucu
  V->>W: call_api(func, args, on_success, on_error)
  V->>W: start
  W->>A: func(args)
  A->>S: HTTP isteği
  S-->>A: yanıt
  A-->>W: sonuç veya ApiError
  W-->>V: finished(result) veya error(msg, status, code, details, trace_id)
  V->>V: canlılık denetimi, sonra on_success veya on_error veya bildirim
  V->>V: çalışanı listeden çıkar

Sözcüklerle:

1. call_api, işlev ve bağımsız değişkenleriyle bir ApiWorker oluşturur, geri çağrıları bağlar, çalışanı ekranın listesine ekler ve başlatır (src/cluster_erp/desktop/core/api_worker.py:187-259).
2. ApiWorker.run işlevi çalışan iş parçacığında çağırır. Sonuçla finished ya da ileti, durum, kod, ayrıntılar ve iz kimliğiyle error yayar (src/cluster_erp/desktop/core/api_worker.py:43-65).
3. Her geri çağrı önce ekranın Qt nesnesinin hâlâ var olduğunu denetler. Yorum, aksi halde kapatılmış bir sekmenin silinmiş nesne hatası vereceğini belirtir (src/cluster_erp/desktop/core/api_worker.py:197-209).
4. Hata durumunda format_api_error yerelleştirilmiş bir ileti kurar. Ekran on_error vermediyse ileti bir hata bildirimi olarak görünür (src/cluster_erp/desktop/core/api_worker.py:219-249).
5. Ekran yok edildiğinde _stop_all_workers çalışan her çalışan için en çok 5.000 ms bekler ve hiçbirini zorla sonlandırmaz (src/cluster_erp/desktop/core/api_worker.py:25, src/cluster_erp/desktop/core/api_worker.py:265-289).

src/cluster_erp/desktop/ altında otuz üç sınıf ApiMixin karıştırır; sayı, ApiMixin adını taşıyan sınıf tanımları aranarak çıkarıldı. İki yer ApiWorker nesnesini doğrudan oluşturur: giriş iletişim kutusu ve durum çubuğu (src/cluster_erp/desktop/widgets/login_dialog.py:306, src/cluster_erp/desktop/widgets/status_bar.py:57).

Yerelleştirilmiş hata iletileri¶

format_api_error iletiyi şu sırayla seçer (src/cluster_erp/desktop/core/api_worker.py:108-176):

1. fields listesi olan VALIDATION_ERROR için alan başına bir satır; alan etiketi field.<ad> anahtarından, neden _REASON_KEYS üzerinden eşlenir (src/cluster_erp/desktop/core/api_worker.py:85-105, src/cluster_erp/desktop/core/api_worker.py:123-132).
2. details.missing listesi için eksik öğe başına bir satır, etiket geçerli dilde (src/cluster_erp/desktop/core/api_worker.py:134-146).
3. Skaler ayrıntılarla doldurulmuş error.<code> çevirisi. Bir resource ayrıntısı resource.<ad> üzerinden çevrilir (src/cluster_erp/desktop/core/api_worker.py:148-165).
4. error.unknown çevirisi (src/cluster_erp/desktop/core/api_worker.py:167-168).

Varsa iz kimliği ayrı bir satır olarak eklenir (src/cluster_erp/desktop/core/api_worker.py:170-174).

GenericApi sınıfı¶

GenericApi(client, module_name, entity_meta) her yolun başına /<module> ekler ve {id}, {parent_id}, {scope_id} yer tutucularını değiştirir. Metadata'nın bildirmediği bir uç anahtarı ValueError fırlatır (src/cluster_erp/desktop/core/generic_api.py:10-31).

Sunucu tarafında silme bir kullanımdan kaldırmadır; bkz. yumuşak silme ve kullanımdan kaldırma. GenericApi.delete kullanımdan kaldırma nedeni göndermez.

Ortak sarmalayıcılar¶

core_api.py, ekranların kesişen özellikler için kullandığı üç sarmalayıcıyı içerir.

Notların ve eklerin sunucu tarafı ekler, notlar ve depolama sayfasındadır. E-posta rotaları PDF ve sistem postası sayfasındadır.

Neden böyle kurulmuştur¶

• Olay döngüsü yerine çalışan iş parçacıkları: projenin yazılı mühendislik kuralları, istemcinin QThread çalışanlarıyla eşzamanlı bir httpx istemcisi kullandığını ve karmaşıklıktan kaçınmak için eşzamansız olay döngüsünden uzak durduğunu belirtir.
• Çalışanı zorla sonlandırmama: src/cluster_erp/desktop/core/api_worker.py:277-283 içindeki yorum, engellenmiş bir çalışanı sonlandırmanın istemci kilidini tutulu bırakacağını ve sonraki her çağrıyı engelleyeceğini belirtir.
• Güncelleme fiilinin metadata'dan gelmesi: src/cluster_erp/desktop/core/generic_api.py:77-78 içindeki yorum, web istemcisinin aynı bildirimi okuduğunu belirtir.

Kurallar ve sınırlar¶

• Metadata güdümlü varlıkların yolları metadata'dan gelir. GenericApi._path bildirilmemiş bir uç anahtarını reddeder (src/cluster_erp/desktop/core/generic_api.py:24-28).
• İstemcideki izin denetimleri görüntü yardımcısıdır. has_permission girişte dönen listeden yanıt verir (src/cluster_erp/desktop/core/api_client.py:131-132); her izni sunucu uygular, bkz. roller ve izinler.

Diğer parçalarla etkileşim¶

• Metadata'dan kurulan her ekran GenericApi kullanır; bkz. genel bileşenler.
• FkCache, seçenek listelerini yüklemek için ApiClient.get işlevini doğrudan çağırır; bkz. metadata deposu ve yabancı anahtar önbelleği.
• Elle yazılmış ekranlar ApiClient nesnesini doğrudan, çoğunlukla call_api üzerinden çağırır; bkz. modül ekranları.

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

• Bazı çağrılar çalışan olmadan GUI iş parçacığında yürür: açılıştaki metadata yüklemesi (src/cluster_erp/desktop/main.py:196-200), yabancı anahtar seçenek yüklemeleri (src/cluster_erp/desktop/widgets/generic/generic_form.py:328-343) ve sohbet bileşeninin liste ve sayı sorguları (src/cluster_erp/desktop/widgets/chat/chat_widget.py:1651, src/cluster_erp/desktop/widgets/chat/chat_widget.py:1758).
• bulk_delete, çağrıdan sonra her kimlik için bir kez entity_deleted yayar; POST ile execute_action bir kayıt aksiyonunda entity_updated, hedefsiz bir aksiyonda entity_created yayar; ikisi de emit_entity_change işlevini kendisi çağırır (src/cluster_erp/desktop/core/generic_api.py:92-99, src/cluster_erp/desktop/core/generic_api.py:101-121).
• execute_action, POST dışındaki her yöntem için GET gönderir (src/cluster_erp/desktop/core/generic_api.py:113-122). Liste ekranları PUT de işleyen kendi aksiyon yardımcılarını kullanır (src/cluster_erp/desktop/widgets/generic/generic_list_view.py:774-787).
• src/cluster_erp/desktop/core/api_worker.py:277-280 içindeki yorum, engellenmiş bir çalışanın istemci kilidini tüm istek boyunca tuttuğunu söyler. _request kilidi yalnızca istemci okunurken ve bir yenileme sırasında tutar (src/cluster_erp/desktop/core/api_client.py:336-347).

Tanıtılan terimler¶

İlgili sayfalar¶

• Masaüstü istemci
• Sinyal veri yolu ve watch_entity
• Genel bileşenler
• Açılış, oturum ve API çağrıları
• Hatalar ve istisnalar

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