API kuralları

Bu sayfa Cluster ERP yollarının paylaştığı kuralları belirtir: yöntemler ve durum kodları, liste sayfalaması, arama ve filtreler, kimlikler, para değerleri, silme yerine kullanımdan kaldırma, toplu işlemler, eylem uç noktaları ve iyimser eşzamanlılık. Bu sayfadaki sayılar src/cluster_erp/modules/ ve src/cluster_erp/server/routes/ içindeki 1.364 yolu kapsar ve modül sayfalarıyla aynı taramadan gelir. src/cluster_erp/server/app.py içinde bildirilen yedi yol Sistem uç noktaları sayfasındadır.

Yöntemler¶

263 yolda koleksiyon yolları eğik çizgiyle biter; örneğin /api/v1/inventory/warehouses/ (src/cluster_erp/modules/inventory/warehouses/routes.py:66). Modül sayfaları her yolun tam yolunu gösterir.

Durum kodları¶

Bazı işleyiciler kendi Response nesnesini döndürür ve durumu orada belirler; örneğin oturum kapatma (src/cluster_erp/modules/auth/login/routes.py:373-432). Hata durumları Hatalar sayfasında listelenir.

Sayfalama¶

Liste yolları limit ve offset sorgu parametrelerini alır (111 yol limit, 105 yol offset alır). Her yol sınırlarını Query(...) içinde kendisi belirler; örneğin depo listesi varsayılan 50, en az 1 ve en çok 200 kullanır (src/cluster_erp/modules/inventory/warehouses/routes.py:66-73).

Sayfalanan bir liste bir zarfla yanıt verir. src/cluster_erp/modules/inventory/warehouses/routes.py:84-96 içinden:

    return {
        "items": await redact_extra_items(
            session,
            [WarehouseListRead.model_validate(w) for w in items],
            "warehouse",
            "warehouse",
            await actor_allowed(session),
        ),
        "total": total,
        "total_capped": svc.last_count_capped,
        "limit": limit,
        "offset": offset,
    }

Tavan list_count_cap ayarıdır; 0 tam sayım demektir (src/cluster_erp/config/settings.py:324, src/cluster_erp/core/pagination.py:27-30). Her liste yolu bu zarfı kullanmaz: response_model=list[...] taşıyan yollar çıplak bir dizi döndürür. Modül sayfaları her yolun yanıt modelini gösterir.

Arama ve filtreler¶

Hiçbir yol sıralama için adlandırılmış bir parametre almaz: tüm sorgu parametresi adlarının taranmasında sort veya order_by içeren bir ad bulunmadı. Bir listenin sırası hizmeti tarafından sabitlenir. Arama motoru Arama, sayfalama ve toplu işlemler sayfasında anlatılır.

Kimlikler¶

{warehouse_id} gibi yol kimlikleri UUID'dir. BaseModel sınıfından türeyen her model birincil anahtarını new_ulid ile alır; kimlikler UUID olarak saklanan ULID değerleridir (src/cluster_erp/core/models.py:20-24). Kimlik şeması Temel model ve kimlikler sayfasında anlatılır. Birkaç yol bunun yerine bir kod veya anahtar alır; örneğin posta OAuth uygulamalarında {provider} ve operatör konsolunda {key} (modül sayfaları ve Sistem uç noktaları).

Para değerleri¶

Projenin yazılı mühendislik kuralları para için Decimal, veritabanında Numeric ve JSON'da dizge ister. Modül şemaları 55 schemas.py dosyasında Decimal açıklamalı 774 alan veya parametre bildirir (src/cluster_erp/modules/**/schemas.py içinde : Decimal ile eşleşen satır sayısı). Bazı okuma şemaları açık bir dizge serileştiricisi bildirir; örneğin ExchangeRateRead (src/cluster_erp/core/currencies.py:186-190). Genel kayıt yolları Decimal değerini kendisi dizgeye çevirir (src/cluster_erp/modules/records/lifecycle_routes.py:47-57).

response_model=dict taşıyan her yolun Decimal değerlerini dizge olarak gönderip göndermediği koddan belirlenemedi; bu sayfa response_model=dict bildiren 323 yolun her birini denetlemedi. İstemciler parayı JSON dizgesi olarak gönderir; Decimal alanı bunu kabul eder. Kural Para ve ondalık sayfasında anlatılır.

Silme yerine kullanımdan kaldırma¶

Bir kayıt yolundaki DELETE kaydı kullanımdan kaldırır: hizmet deleted_at değerini yazar ve yol 204 yanıtlar (src/cluster_erp/modules/inventory/warehouses/services.py:137-143, src/cluster_erp/modules/inventory/warehouses/routes.py:146-154). Listeler deleted_at değeri dolu satırları dışarıda bırakır (src/cluster_erp/modules/inventory/warehouses/services.py:47). İstemci nedeni ve notu X-Deact-Reason ve X-Deact-Note başlıklarıyla gönderebilir; değişiklik geçmişi onları satıra basar (src/cluster_erp/server/dependencies.py:63-72).

Kullanımdan kaldırılmış satırlar genel kayıt yollarıyla okunur ve yeniden etkinleştirilir: GET /api/v1/records/{module}/{entity}/inactive, GET /api/v1/records/{module}/{entity}/labels ve POST /api/v1/records/{module}/{entity}/{record_id}/activate (src/cluster_erp/modules/records/lifecycle_routes.py:113-240). Kural Geçici silme ve kullanımdan kaldırma sayfasında anlatılır.

Toplu işlemler¶

72 yol /bulk-delete ile biter. ids taşıyan BulkDeleteRequest alırlar ve deleted_count taşıyan BulkDeleteResponse yanıtlarlar (src/cluster_erp/core/bulk_operations.py:12-17). bulk_soft_delete yardımcısı her satırı ORM üzerinden yükler ve deleted_at yazar; böylece her satır değişiklik geçmişine düşer (src/cluster_erp/core/bulk_operations.py:20-57).

BulkDeleteRequest (src/cluster_erp/core/bulk_operations.py:12-13) şemasından kurulan örnekleyici istek:

POST /api/v1/bom/boms/bulk-delete HTTP/1.1
Host: erp.example.com
Authorization: Bearer <access_token>
Content-Type: application/json

{
 "ids": ["<bom_id>", "<bom_id>"]
}

Yukarıdaki yol yalnız biçimi gösterir; hangi varlıkların toplu yolu olduğunu modül sayfaları listeler.

Eylem uç noktaları¶

Durum değişiklikleri bir güncelleme gövdesindeki alanlar değil, ayrı POST yollarıdır. İki biçim vardır:

İyimser eşzamanlılık¶

Her modelin bir version sütunu vardır (src/cluster_erp/core/models.py:73). Birçok varlığın güncelleme şeması bir version alanı taşır; hizmet check_version çağırır ve değerler farklıysa bu fonksiyon CONCURRENCY_VERSION_CONFLICT, details.expected_version ve details.current_version ile 409 atar (src/cluster_erp/core/errors.py:411-430). Tarama bu kodun 60 atma konumunu buldu. version taşımayan bir istek denetimi atlar (src/cluster_erp/core/errors.py:428-430).

Kiracı alanı değerleri¶

Kiracı tanımlı alanları destekleyen okuma şemaları onları extra içinde taşır; yol yanıt vermeden önce çağıranın göremeyeceği değerleri redact_extra ve redact_extra_items ile çıkarır (src/cluster_erp/core/tenant_fields.py:2478, src/cluster_erp/modules/inventory/warehouses/routes.py:53-63). Mekanizma Kiracı alanları sayfasında anlatılır.

Tanıtılan terimler¶

İlgili sayfalar¶

• API başvurusu
• API'ye genel bakış
• Hatalar
• Arama, sayfalama ve toplu işlemler
• Geçici silme ve kullanımdan kaldırma
• Para ve ondalık

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