Masaüstü istemciye genel bakış

Masaüstü istemci, src/cluster_erp/desktop/ içinde yer alan ve bir Cluster ERP sunucusuyla HTTP API'si üzerinden konuşan bir Qt uygulamasıdır. Bu sayfa klasör yapısını, desktop/main.py içindeki açılış ve giriş sırasını, desktop kurulum ekini ve PySide6 sürüm notunu açıklar. İstemcinin her parçasının masaüstü bölümünde kendi sayfası vardır. Nasıl başlatıldığı masaüstü istemciyi çalıştırın sayfasındadır.

Kısaca¶

• Giriş noktası src/cluster_erp/desktop/main.py:110-130 içindeki main() işlevidir. pyproject.toml:88 onu ayrıca cluster-erp-desktop konsol betiği olarak kurar.
• Açılış; ayar deposunu, tema motorunu, erişilebilirliği, çevirmeni, API istemcisini ve sinyal veri yolunu oluşturur, ardından giriş iletişim kutusunu gösterir (src/cluster_erp/desktop/main.py:162-190).
• Girişten sonra istemci sunucu metadata'sını en çok üç denemeyle yükler ve hepsi başarısız olursa kapanır (src/cluster_erp/desktop/main.py:194-222).
• Ekranlar metadata'dan genel bileşenlerle kurulur. On bölüm anahtarı elle yazılmış ekranlara eşlenir (src/cluster_erp/desktop/widgets/main_window.py:501-528).
• PySide6, desktop ekindeki isteğe bağlı bir bağımlılıktır; böylece sunucu kurulumu GUI araç takımı taşımaz (pyproject.toml:68-74).

Nasıl çalışır¶

Klasör yapısı¶

Paketin beş klasörü vardır. Aşağıdaki sayılar doğrulanan commit'te src/cluster_erp/desktop/ listelenerek çıkarıldı: 86 Python dosyası, bunların 69'u boş değil, toplam 34.331 satır Python.

Açılış ve giriş sırası¶

Diyagram main() işlevinden görünür ana pencereye kadar olan yolu gösterir.

sequenceDiagram
  participant M as main
  participant L as LoginDialog
  participant A as ApiClient
  participant S as Sunucu
  participant MS as MetadataStore
  participant W as MainWindow
  M->>M: purge_stale_previews, QApplication, yazı tipi
  M->>M: SettingsStore, ThemeEngine, AccessibilityManager, Translator
  M->>A: ApiClient(api_url), set_language, set_signal_bus
  M->>L: exec
  L->>A: ApiWorker içinde login
  A->>S: POST /auth/login
  S-->>A: belirteçler, kullanıcı, izinler
  L-->>M: Accepted
  M->>MS: load, en çok 3 deneme
  MS->>S: GET /_meta, /_switches, /_overlay, /app_store/registry
  M->>W: MainWindow, show, restore_pane_layout
  M->>M: app.exec

Sözcüklerle:

1. main() günlük kaydını yapılandırır ve _global_exception_handler işlevini sys.excepthook olarak kurar (src/cluster_erp/desktop/main.py:110-116).
2. _run_app() önceki bir süreçten kalan ek önizleme klasörlerini siler, QApplication nesnesini oluşturur ve sabit bir listeden kurulu ilk yazı tipini seçer (src/cluster_erp/desktop/main.py:133-160).
3. SettingsStore, ThemeEngine ve AccessibilityManager nesnelerini oluşturur ve erişilebilirlik ayarlarını henüz hiçbir pencere yokken uygular (src/cluster_erp/desktop/main.py:162-165).
4. Translator nesnesini oluşturur, sunucu adresini api_url ayarından okur ve ApiClient nesnesini geçerli dil ve SignalBus ile oluşturur (src/cluster_erp/desktop/main.py:166-175).
5. LoginDialog kipli çalışır. Giriş yapmadan kapatmak süreci 0 çıkış koduyla bitirir (src/cluster_erp/desktop/main.py:182-190).
6. İstemci user_logged_in yayar ve MetadataStore oluşturur. Başarısız bir yükleme yeniden deneme sorusu gösterir. Üçüncü başarısızlıktan ya da iptalden sonra son bir hata görünür ve süreç 1 çıkış koduyla kapanır (src/cluster_erp/desktop/main.py:192-222).
7. FkCache oluşturur, metadata etiketlerini çevirmene kaydeder, MainWindow kurar, gösterir ve kayıtlı bölme yerleşimini geri yükler (src/cluster_erp/desktop/main.py:224-238).

Hata işleme¶

_global_exception_handler iz kaydını günlüğe yazar, platform değeri desktop olarak POST /logs/errors/client ucuna gönderir ve teknik ayrıntıyı bir ayrıntı düğmesinin arkasında tutan bir iletişim kutusu gösterir (src/cluster_erp/desktop/main.py:45-107). Bir bayrak, raporun kendisi başarısız olursa raporlamanın kendini yeniden çağırmasını engeller (src/cluster_erp/desktop/main.py:50-68). Açılış sırasındaki bir hata iz kaydını kritik bir ileti kutusunda gösterir ve 1 çıkış koduyla kapanır (src/cluster_erp/desktop/main.py:118-130).

Paketleme ve Qt sürümü¶

desktop eki PySide6>=6.7.0 ekler. Üstündeki yorum, ekin GUI araç takımını sunucu düğümlerinden uzak tuttuğunu, Windows'ta bilinen iyi sürümün 6.8.3 olduğunu ve 6.11.0'ın bir DLL hatasıyla başarısız olduğunu belirtir (pyproject.toml:68-74). CI lint işi, mypy src istemciyi de denetlesin diye PySide6==6.8.3 kurar (.github/workflows/ci.yml:48-50). Paket verisi dil dosyalarını ve stil sayfasını taşır (pyproject.toml:93-95).

Neden böyle kurulmuştur¶

• desktop eki: pyproject.toml:68-71 içindeki yorum, bir sunucu düğümünün asla GUI araç takımı kurmadığını belirtir.
• Çökme raporlama: src/cluster_erp/desktop/main.py:48-49 içindeki belge dizgesi, bir istemci çökmesinin sunucu taraflı hatalarla aynı hata günlüğüne düştüğünü belirtir.
• Çalışan iş parçacıklarıyla eşzamanlı HTTP: projenin yazılı mühendislik kuralları, karmaşıklıktan kaçınmak için istemcinin QThread çalışanlarıyla eşzamanlı bir httpx istemcisi kullandığını ve eşzamansız olay döngüsü kullanmadığını belirtir. ApiClient bir httpx.Client sarar (src/cluster_erp/desktop/core/api_client.py:86-91) ve ApiWorker, QThread alt sınıfıdır (src/cluster_erp/desktop/core/api_worker.py:28).

Kurallar ve sınırlar¶

• İstemci hiçbir arka uç modül paketini içe aktarmaz. src/cluster_erp/desktop/ içinde cluster_erp.modules, cluster_erp.core veya cluster_erp.server içe aktarmaları arandığında eşleşme çıkmaz. Sohbet bileşeni cluster_erp.ai içe aktarır (src/cluster_erp/desktop/widgets/chat/chat_widget.py:47); bkz. sohbet bileşeni.
• Ekranlar arasındaki her yenileme istemci tarafındaki SignalBus üzerinden gider; bkz. sinyal veri yolu ve watch_entity.
• Testler istemcinin parçalarını sabitler: tests/test_desktop_app_scope.py, tests/test_desktop_datetime_field.py, tests/test_desktop_table_text_insets.py ve tests/test_order_shipment_chain.py:201 (web ve masaüstü aynı metadata biçimlerini budar). web-client/_desktop_visual.py, web-client/_desktop_survey.py, web-client/_desktop_tenant_fields.py ve web-client/_desktop_intranet_check.py sondaları gerçek bileşenleri ekransız Qt platformunda çalıştırır. Bunlar geliştirici araçları ve betikler sayfasında listelenir.

Diğer parçalarla etkileşim¶

• Giriş POST /auth/login ve POST /auth/refresh uçlarını kullanır (src/cluster_erp/desktop/core/api_client.py:134-205). Sunucu tarafı kimlik doğrulama ve oturumlar sayfasında açıklanır.
• Metadata GET /_meta, GET /_switches, GET /_overlay ve GET /app_store/registry uçlarından gelir (src/cluster_erp/desktop/core/metadata_store.py:19-82). Sözleşme metadata modeli sayfasında açıklanır.
• Bağlantı göstergesi her 15 saniyede bir sunucu kökündeki GET /health ucunu çağırır (src/cluster_erp/desktop/widgets/status_bar.py:49-63, src/cluster_erp/desktop/core/api_client.py:326-333).

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

• MainWindow ve durum çubuğu, main() işlevi user_logged_in yaydıktan sonra oluşturulur (src/cluster_erp/desktop/main.py:192, src/cluster_erp/desktop/main.py:227-236). Durum çubuğu bu sinyale yapıcısında bağlanır (src/cluster_erp/desktop/widgets/status_bar.py:44); bu yüzden ilk girişten sonra giriş yapan kullanıcının adı görünmez. Süresi dolmuş bir oturumun ardından yapılan girişten sonra görünür (src/cluster_erp/desktop/widgets/main_window.py:263-264).
• Uygulama sürümü sabit 0.1.0 değerine ayarlanır (src/cluster_erp/desktop/main.py:150); bu, pyproject.toml:7 içindeki version ile aynı değerdir. Durum çubuğu bunu gösterir (src/cluster_erp/desktop/widgets/status_bar.py:73-75).
• pyproject.toml:93-95 içindeki paket verisi yalnızca *.json ve *.qss listeler. src/cluster_erp/desktop/widgets/chat/assets/ içindeki sohbet arka plan görselleri listelenmez. Düzenlenebilir olmayan bir kurulumun bunları içerip içermediği: Koddan belirlenemedi. pyproject.toml içindeki paket verisi arandı ve depoda MANIFEST.in yoktur.

Tanıtılan terimler¶

İlgili sayfalar¶

• Masaüstü istemci
• Masaüstü istemciyi çalıştırın
• API istemcisi ve çalışanlar
• Mimariye genel bakış
• Sunucu açılışı ve uygulama fabrikası

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