API'ye genel bakış

Cluster ERP sunucusu, create_app fonksiyonunun src/cluster_erp/server/app.py içinde kurduğu tek bir FastAPI uygulamasıdır. Bu sayfa HTTP yollarının nasıl oluştuğunu, etkileşimli API belgelerinin nerede bulunduğunu, yolların hangi içerik türlerini kullandığını ve bir isteğin soketten hizmete kadar başına neler geldiğini açıklar. Uç noktaları listelemez; API başvurusu her yol grubu için bir sayfaya bağlanır.

Kısaca¶

• Her arka uç modülü yollarını ModuleBase.api_prefix değeri olan /api/v1/<module> altına bağlar (src/cluster_erp/core/module_base.py:37-38). fleet ve intranet modülleri aynı öneki sabit metin olarak yazar (src/cluster_erp/modules/fleet/module.py:310, src/cluster_erp/modules/intranet/module.py:172).
• Modül kayıt defteri her modülü yüklerken onun register_routes metodunu çağırır (src/cluster_erp/core/module_registry.py:49-51).
• Modüller dışındaki paylaşılan yollar src/cluster_erp/server/routes/ içindedir ve create_app tarafından eklenir (src/cluster_erp/server/app.py:1432-1450).
• Etkileşimli belge sayfaları yalnız debug ayarı açıkken vardır (src/cluster_erp/server/app.py:1296-1303).
• İstek ve yanıt gövdeleri JSON'dur; dosya yüklemeleri (çok parçalı form verisi) ve dosya indirmeleri bunun dışındadır.

Temel yollar¶

Tablo sunucunun yanıtladığı yolları gruplar. Modül ve paylaşılan yol sayıları API başvurusu sayfasındadır.

Modül önekleri¶

Çoğu modül prefix=self.api_prefix ile bir module_router oluşturur, alt modül yönlendiricilerini ona ekler ve onu bir yetkilendirme bağımlılığıyla uygulamaya ekler. Inventory modülü buna örnektir (src/cluster_erp/modules/inventory/module.py:52-62). Bazı modüller module_router kullanmaz ve öneki doğrudan app.include_router çağrısına verir; örneğin analytics, app_store, logs, mail, privacy ve records (src/cluster_erp/modules/analytics/module.py:55, src/cluster_erp/modules/records/module.py:50-52).

Bir alt modül yönlendiricisi kendi prefix değerini ekler; örneğin /warehouses (src/cluster_erp/modules/inventory/warehouses/routes.py:33). Bazı yönlendiricilerin öneki yoktur ve kaynak bölümünü her yolun içine yazar: crm yönlendiricileri, calendars yönlendiricisi, parties yönlendiricileri, satış siparişi yönlendiricileri, para birimi yönlendiricisi ve müşteri aboneliği yönlendiricisi (src/cluster_erp/modules/crm/customers/routes.py:28, src/cluster_erp/modules/calendars/routes.py:44, src/cluster_erp/modules/parties/parties/routes.py:28, src/cluster_erp/modules/sales_orders/orders/routes.py:33, src/cluster_erp/server/routes/currencies.py:18, src/cluster_erp/modules/subscriptions/customer_subscriptions/routes.py:30-34). Modül sayfaları her yolun tam yolunu gösterir; okurun parçaları toplaması gerekmez.

OpenAPI erişilebilirliği¶

create_app, docs_url="/api/docs" ve redoc_url="/api/redoc" değerlerini yalnız settings.debug doğruyken verir; aksi halde ikisi de None olur (src/cluster_erp/server/app.py:1296-1303). debug ayarının varsayılanı False değeridir (src/cluster_erp/config/settings.py:176). Çağrı openapi_url bağımsız değişkeni vermez; çatının varsayılanı geçerlidir, bkz. FastAPI başvurusu. İki yol include_in_schema=False ile şemadan çıkarılır: kapalı kayıt yoklaması ve /.well-known/security.txt (src/cluster_erp/server/app.py:1455, src/cluster_erp/server/app.py:1459). Her yönlendirici, üretilen şemada işlemleri gruplayan tags verir; örneğin tags=["inventory-warehouses"] (src/cluster_erp/modules/inventory/warehouses/routes.py:33).

İçerik türleri¶

Bir isteğin yolu¶

Diyagram, bir modül yoluna giden kimliği doğrulanmış bir isteği izler. Zamanlamayı değil, kodun ne yaptığını gösterir. Çatının bir yolun bağımlılıklarını hangi sırayla çözdüğü projenin kodunda belirtilmez; bu yüzden üç bağımlılık birlikte gösterilir.

sequenceDiagram
 participant Client
 participant Middleware
 participant Dependencies
 participant Handler
 participant Service
 participant Database
 Client->>Middleware: HTTP isteği
 Note over Middleware: _security_headers aşırı büyük gövdeyi 413 ile reddeder
 Middleware->>Dependencies: yolu çağır
 Note over Dependencies: get_db_session, require_app, require_permission
 Dependencies->>Database: kiracı oturumunu aç, denetim bağlamını yaz
 Dependencies->>Handler: kullanıcı ve oturum ya da 401, 403, 422
 Handler->>Service: doğrulanmış şema
 Service->>Database: sorgu ve flush
 Service-->>Handler: sonuç veya AppError
 Handler-->>Middleware: yanıt modeli
 Note over Middleware: ilk bayttan önce commit, etkinlik günlüğü, güvenlik başlıkları
 Middleware-->>Client: JSON yanıtı

Aynı adımlar düz metinle:

Ara katman sırası ve her katman İstek hattı ve ara katmanlar sayfasında anlatılır.

Tanıtılan terimler¶

İlgili sayfalar¶

• API başvurusu
• Kimlik doğrulama ve başlıklar
• API kuralları
• Hatalar
• Sunucu başlatma ve uygulama fabrikası
• Modül yaşam döngüsü

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