Para ve Decimal

Bu sayfa Cluster ERP'de paranın nasıl işlendiğini anlatır: proje kuralı, core/currencies.py içindeki kod, tutarları hesaplayan servisler ve kuralı koruyan testler. Para birimlerini ve döviz kurlarını yalnızca tutarları etkilediği ölçüde kapsar; gerisini currencies modül sayfası kapsar.

Kısaca¶

• Projenin yazılı mühendislik kuralları her para değeri için Decimal, veritabanında Numeric, JSON'da dizgi ve bankacı yuvarlaması (ROUND_HALF_EVEN) ister.
• Bir para biriminin ondalık basamak sayısı bir sabit değil, core_currencies.decimal_places içindeki referans veridir (src/cluster_erp/core/currencies.py:86).
• Döviz kurları Numeric(18, 6) sütunlarıdır ve dizgi olarak serileştirilir (src/cluster_erp/core/currencies.py:110-121, src/cluster_erp/core/currencies.py:186-190).
• ROUND_HALF_EVEN, src/cluster_erp altındaki 16 Python dosyasında içe aktarılır (grep -rln ROUND_HALF_EVEN ile sayıldı); ROUND_HALF_UP hiçbirinde geçmez.
• Bir test, her parasal analitik ölçüsünün Float değil Numeric sütun üzerinde durduğunu denetler (tests/test_analytics_contributions.py:120-133).

Nasıl çalışır¶

Referans veriden para birimi hassasiyeti¶

Currency satırları code, numeric_code, name, symbol, decimal_places, translations ve is_active alanlarını taşır (src/cluster_erp/core/currencies.py:57-89). Satırlar ISO 4217 kümesinden tohumlanır: simgeleri ve çevirileri olan düzenlenmiş bir liste, pycountry paketiyle tamamlanır (src/cluster_erp/core/currencies.py:559, src/cluster_erp/core/currencies.py:1811-1852). Bkz. referans veriler ve çekirdek i18n.

Bir para toplamını yuvarlayan servisler hassasiyeti bu tablodan okur. quotations modülündeki money_scale, belge para birimi için Currency.decimal_places değerini arar ve Decimal(1).scaleb(-decimals) döndürür; para birimi bilinmiyor veya boşsa 2 basamağa düşer (src/cluster_erp/modules/quotations/rollup.py:31-46). sales_orders modülünün kendi money_scale işlevi vardır (src/cluster_erp/modules/sales_orders/rollup.py:24).

Yuvarlama¶

Parayı nicemleyen (quantize) dosyalar ROUND_HALF_EVEN içe aktarır; örneğin src/cluster_erp/modules/quotations/rollup.py:21. En çok geçtiği modüller procurement (MRP motoru ve rotaları), costing, projects, nesting ve bom'dur (grep -rn ROUND_HALF_EVEN ile sayılıp dosyaya göre gruplandı).

Döviz kuru dönüşümü, açık bir yuvarlama argümanı olmadan quantize(Decimal("0.000001")) ile altı ondalık basamağa nicemler (src/cluster_erp/core/currencies.py:423-443). Yuvarlama kipi bu durumda etkin decimal bağlamından gelir. src/cluster_erp içindeki hiçbir kod decimal bağlamını değiştirmez (getcontext, localcontext ve setcontext arandı). Python decimal modülünün varsayılan bağlamı Python belgelerinde anlatılır.

Miktarlar para değildir ve kodun gerektirdiği yerde başka kipler kullanır; örneğin gereken stok birimi sayısı için ROUND_CEILING (src/cluster_erp/core/stock_conversion.py:65-67).

Dizgi olarak JSON taşıma¶

• ExchangeRateRead ve ConvertResult, Decimal değerlerini dizgiye çeviren alan serileştiricileri bildirir (src/cluster_erp/core/currencies.py:173-204).
• decimal türündeki bir kiracı alanı JSONB içinde float olarak değil, dizgi olarak saklanır (src/cluster_erp/core/tenant_fields.py:875-877). tests/test_tenant_fields.py:59-61 testi coerce_value işlevinin hem "12.50" hem 3 için dizgi döndürdüğünü denetler.
• Değişiklik geçmişi JSON farkında Decimal değerlerini dizgiye çevirir (src/cluster_erp/core/change_history.py:108-109).

Para birimi kodları var olmalıdır¶

assert_known_currency, core_currencies içinde etkin bir satır olmayan para birimi kodunu CURRENCY_UNKNOWN hata koduyla ve HTTP 422 ile reddeder (src/cluster_erp/core/currencies.py:27-49). Belge dizgisi nedeni belirtir: yalnızca biçim denetimi, doğrudan bir API çağrısının ZZZ gibi bir kodu saklamasına izin verirdi (src/cluster_erp/core/currencies.py:31-36).

Sayısal girdiden doğan hatalar¶

Bir istek işlenirken yükselen decimal.InvalidOperation, HTTP 422 ile VALIDATION_ERROR olur; bir veritabanı DataError hatası (örneğin sayısal taşma) da HTTP 422 ile VALIDATION_ERROR olur (src/cluster_erp/server/error_handler.py:133-148). Bkz. hatalar ve istisnalar.

Neden böyle kurulmuştur¶

Projenin yazılı mühendislik kuralları kuralı, kuralın kendisinin ötesinde bir gerekçe vermeden belirtir. test_monetary_measures_are_not_float_backed belge dizgisi onu "an absolute project rule" (mutlak bir proje kuralı) olarak adlandırır (tests/test_analytics_contributions.py:121-123). assert_known_currency belge dizgisi para birimi kodlarının neden referans veriden gelmesi gerektiğini belirtir (src/cluster_erp/core/currencies.py:31-36). Bankacı yuvarlamasının seçilme gerekçesi koddan belirlenemez.

Kurallar ve sınırlar¶

• Para Python'da Decimal, veritabanında Numeric'tir. Analitik testi parasal ölçüler için Numeric'i zorlar (tests/test_analytics_contributions.py:120-133).
• Para birimi simgeleri, ondalık basamakları ve adları core_currencies'ten gelir (src/cluster_erp/core/currencies.py:57-89).
• Bu wiki'deki API örneklerinde para değerleri, belgeleme standardına uygun olarak JSON dizgileridir.

Diğer parçalarla etkileşim¶

• currencies modülü para birimi rotalarını bağlar ve döviz kurlarına ve ödeme koşullarına sahiptir (src/cluster_erp/modules/currencies/module.py:64-82). Bkz. currencies.
• Analitik, parasal ölçüleri bir currency_field ile bildirir (tests/test_analytics_contributions.py:127-128). Bkz. analitik olguları.

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

• Para gibi görünen bazı ayarların türü farklıdır: pr_approval_threshold_amount bir int, mrp_eoq_ordering_cost bir str'dir (src/cluster_erp/config/settings.py:603, src/cluster_erp/config/settings.py:623). Her birinin okunduğu yerde nasıl dönüştürüldüğü bu sayfa için izlenmedi.
• Para taşıyan her Pydantic şemasının onu dizgi olarak serileştirip serileştirmediği bu sayfa için denetlenmedi. Burada koddan belirlenemedi.

Tanıtılan terimler¶

İlgili sayfalar¶

• Platform çekirdeği
• Referans veriler ve çekirdek i18n
• Hatalar ve istisnalar
• Currencies
• Decimal para

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