Modül yaşam döngüsü

Cluster ERP'nin her iş özelliği bir modüldür: src/cluster_erp/modules/ altında, Module sınıfı ModuleBase'den türeyen bir module.py dosyası taşıyan bir paket. Bu sayfa core/module_base.py içindeki sözleşmeyi ve core/module_registry.py'nin modülleri nasıl bulduğunu, yüklediğini ve kapattığını anlatır. Modüllerin kendileri modüller bölümünde belgelenir.

Kısaca¶

• ModuleBase üç soyut özellik (name, version, description) ve beş soyut yöntem (initialize, register_routes, register_events, shutdown, get_metadata) bildirir (src/cluster_erp/core/module_base.py:24-74).
• Bir modülün API öneki /api/v1/<name>'dir (src/cluster_erp/core/module_base.py:36-38).
• Kayıt cluster_erp.modules.<name>.module modülünü içe aktarır, Module sınıfından örnek oluşturur ve initialize, register_routes ve register_events yöntemlerini bu sırayla çağırır (src/cluster_erp/core/module_registry.py:32-56).
• Modüller enabled_modules ayarındaki sırayla yüklenir (src/cluster_erp/core/module_registry.py:58-72, src/cluster_erp/config/settings.py:535-564).
• Kapanışta kayıt, yüklü her modülde shutdown çağırır ve hataları yükseltmeden günlüğe yazar (src/cluster_erp/core/module_registry.py:74-80).

Nasıl çalışır¶

Sözleşme¶

Bulma ve yükleme¶

Durum şeması bir modülün sunucu süreci içindeki ömrünü gösterir.

stateDiagram-v2
 [*] --> Imported: import cluster_erp.modules.name.module
 Imported --> Instantiated: Module()
 Instantiated --> Initialized: initialize(database)
 Initialized --> Routed: register_routes(app)
 Routed --> Wired: register_events(bus)
 Wired --> Serving: kayda eklendi
 Serving --> Stopped: shutdown()
 Stopped --> [*]

Düz metinle:

1. discover(), cluster_erp.modules altındaki alt paketleri pkgutil.iter_modules ile listeler (src/cluster_erp/core/module_registry.py:26-30).
2. load_all(), ayarlanmışsa enabled_modules listesini, değilse bulunan listeyi alır. Etkin olup bulunamayan bir ad bir uyarıyla atlanır (src/cluster_erp/core/module_registry.py:58-71).
3. load_module(), cluster_erp.modules.<name>.module modülünü içe aktarır. İçe aktarma hatası ModuleLoadError yükseltir. Module sınıfı olmayan bir dosya da ModuleLoadError yükseltir (src/cluster_erp/core/module_registry.py:39-47).
4. Module() örneğini oluşturur ve initialize(database) çağrısını bekler, ardından register_routes(app) ve register_events(bus) çağırır (src/cluster_erp/core/module_registry.py:49-52).
5. Örneği instance.name altında saklar ve yüklemeyi günlüğe yazar (src/cluster_erp/core/module_registry.py:54-56).

load_all, ModuleLoadError yakalamaz (src/cluster_erp/core/module_registry.py:58-72). Lifespan load_all çağrısını bir işleyici olmadan yapar (src/cluster_erp/server/app.py:140); bu yüzden başarısız bir modül açılışı durdurur.

Modüllerin her adımda yaptığı¶

• initialize veritabanı tutamacını saklar, modülün modellerini içe aktarır ve referans veri tohumlayabilir. parties modülü kanal türlerini ve ülkeleri tohumlar (src/cluster_erp/modules/parties/module.py:37-42). logs modülü yalnızca modellerini içe aktarır (src/cluster_erp/modules/logs/module.py:28-29).
• register_routes, prefix=self.api_prefix ile bir APIRouter kurar ve alt modül yönlendiricilerini ekler. 28 module.py dosyasının 20'si yönlendirici bağımlılığı olarak require_app(self.name) verir (grep -l "require_app(" ile sayıldı); örnek: src/cluster_erp/modules/currencies/module.py:64-82. Uygulama hakları uygulama mağazası, lisanslama ve haklar sayfasında belgelenir.
• register_events işleyicileri bağlar. Bkz. olay veri yolu.
• shutdown, 28 modülün 25'inde pass'tir (async def shutdown satırından sonraki satırdan sayıldı).

Metadata'yı kim okur¶

get_metadata() açılışta kiracı alanı tanımlarını kurmak ve izinleri tohumlamak için (src/cluster_erp/server/app.py:151-152), istek anında ise GET /api/v1/_meta tarafından okunur (src/cluster_erp/server/app.py:1531-1534). Bkz. metadata modeli.

Neden böyle kurulmuştur¶

• ModuleBase belge dizgisi tarifi verir: bir paket oluştur, Module adlı sınıfı içeren module.py ekle, soyut yöntemleri uygula; modül açılışta bulunur ve yüklenir (src/cluster_erp/core/module_base.py:15-22).
• request_database belge dizgisi neden var olduğunu belirtir: modüller varsayılan veritabanıyla bir kez başlatılır, ama çok kiracılı kipte bir istek kendi kiracısının veritabanında çalışır; bu yüzden bir işleyici isteğin veritabanını kullanmalıdır (src/cluster_erp/core/module_base.py:41-53).
• Projenin yazılı mühendislik kuralları aynı dört adımlı yaşam döngüsünü belirtir.

Kurallar ve sınırlar¶

• Her modül klasöründe bir module.py vardır ve her modül en az bir rota dekoratörü bildirir. İkisini de tests/test_architecture_boundaries.py:60-72 zorlar.
• Bir modül, cluster_erp.modules.auth.guards dışında başka bir modülü içe aktarmaz. Bunu tests/test_architecture_boundaries.py:46-57 zorlar.

Diğer parçalarla etkileşim¶

• Sunucu kaydı oluşturur ve lifespan içinde load_all ile shutdown_all çağırır (src/cluster_erp/server/app.py:63, src/cluster_erp/server/app.py:140, src/cluster_erp/server/app.py:220). Bkz. sunucu açılışı ve uygulama fabrikası.
• GET /api/v1/modules, oturum açmış bir çağırana yüklü her modülün adını, sürümünü ve açıklamasını döndürür (src/cluster_erp/server/app.py:1506-1515).

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

• Kayıtta modüller arası bağımlılık sıralaması yoktur; sıra listenin sırasıdır. Bir modülün başka bir modülün initialize adımının önce çalışmış olmasına dayanıp dayanmadığı koddan belirlenemedi.
• registry.get(name) bilinmeyen bir ad için ModuleNotRegisteredError yükseltir (src/cluster_erp/core/module_registry.py:82-86). Çağıranları bu sayfa için listelenmedi.

Tanıtılan terimler¶

İlgili sayfalar¶

• Platform çekirdeği
• Sunucu açılışı ve uygulama fabrikası
• Olay veri yolu
• Metadata modeli
• Bir arka uç modülü yazın

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