Bir satış uygulamasında kullanıcının en hızlı fark ettiği hata, bir kuruşluk farktır. Teklif ekranında 12.480,37 TL görünen tutar faturada 12.480,38 çıkarsa, kalan her şeyin doğruluğu sorgulanır. GİB'e giden e-Faturada ise bu bir kuruş, belgenin reddedilmesi demek.
Yapı malzemesi satış uygulamamda tüm para ve KDV hesapları, hem istemcinin hem sunucunun kullandığı tek bir paylaşılan pakette yaşıyor. Bu yazı o paketin kurallarını anlatıyor.
Kural 1: Para asla number olmaz
JavaScript'te 0.1 + 0.2 işleminin sonucu 0.30000000000000004. Para için kabul edilemez. Bu yüzden:
- Veritabanında
NUMERIC(18,4), - uygulamada
Decimal(decimal.js), - JSON taşımasında ondalık string (
"1234.56") kullanılıyor.
Decimal sınıfı paket dışında doğrudan kullanılmıyor; tüm hesaplar addMoney, percentOf, roundMoney gibi yardımcılardan geçiyor. Geçersiz bir girdi sessizce 0'a dönüşmüyor, hata fırlatıyor.
// Yuvarlama: yarım yukarı (Türk mali uygulamasının beklentisi).
// Hassasiyet, ara çarpımlarda birikimli hata bırakmayacak kadar geniş.
Decimal.set({ precision: 34, rounding: Decimal.ROUND_HALF_UP })
export const MONEY_SCALE = 2 // tutarlar
export const QUANTITY_SCALE = 4 // m², ton, kg gibi miktarlar
Kural 2: KDV satır bazında hesaplanır
KDV'yi toplam matrah üzerinden tek seferde hesaplamak daha basit görünür ama farklı sonuç verir. Üç satırlık, satır matrahı 0,03 TL olan, %20 KDV'li bir belge düşünün:
| Yöntem | Hesap | KDV |
|---|---|---|
| Satır bazında | 3 × yuvarla(0,03 × %20 = 0,006) = 3 × 0,01 | 0,03 TL |
| Toplam üzerinden | yuvarla(0,09 × %20 = 0,018) | 0,02 TL |
Çok oranlı gerçek belgelerde bu sapmalar büyür. GİB'in UBL-TR doğrulaması satır bazlı hesabı beklediği için çekirdek KDV'yi her satırda hesaplıyor ve toplamları satırlardan topluyor. Belge toplamı hiçbir zaman ayrıca hesaplanmıyor.
Kural 3: Belge iskontosu dağıtılırken kuruş kaybolmaz
Belge geneline verilen 100 TL'lik iskontoyu eşit tutarlı üç satıra dağıtın: her satıra 33,33 TL düşer, toplam 99,99 TL eder. Bir kuruş kayboldu.
Çekirdekteki allocate fonksiyonu, iskontoyu satırlara tutarlarıyla orantılı dağıtıyor ve yuvarlama artığını en büyük paya ekliyor. Eşitlik varsa artık son satıra düşüyor: 33,33 + 33,33 + 33,34 = 100,00. Toplam her durumda birebir tutuyor.
const parts = weights.map((w) => roundMoney(amount.times(w).dividedBy(weightSum)))
const remainder = amount.minus(sum(parts))
if (!remainder.isZero()) {
// Eşitlikte SON pay kazanır: kullanıcının çıktıda beklediği davranış.
parts[indexOfLargestWeight] = parts[indexOfLargestWeight].plus(remainder)
}
Kural 4: Nakliye iskontoya girmez
Yapı malzemesinde nakliye ciddi bir kalem. Müşteriye verilen indirim mala uygulanır, taşımaya değil. Bu yüzden nakliye malzeme satırlarından ayrı tutuluyor:
- Belge iskontosuna girmiyor,
- matraha ve KDV'ye dahil oluyor,
- KDV'si kendi oranıyla hesaplanıyor ve aynı oranda bir malzeme satırı varsa KDV kırılımında onunla birleşiyor, çünkü GİB oran başına tek satır bekliyor.
Bu davranış 12 testle korunuyor. En kritiği tek cümlelik bir test: "belge iskontosu nakliyeye uygulanmaz."
Kural 5: Belgeye yazılan değer, sonradan değişmez
Fiyat, kur ve birim dönüşüm katsayısı belge oluşturulduğu anda belgeye kopyalanıyor. Ürün kartındaki fiyat ya da "1 M³ kum = 1,6 TON" katsayısı sonradan değişse bile geçmiş bir faturanın tutarı veya sevkiyat ağırlığı değişmiyor.
Birim dönüşümünde de aynı sadelik var. Kum için yoğunluk, çimento için ambalaj miktarı, demir için metre ağırlığı gibi ayrı sütunlar açmak yerine tek bir katsayı kullanılıyor; yeni bir malzeme tipi şema değişikliği gerektirmiyor.
Tek kaynak, iki çağıran
Çekirdeğin başındaki yorum aslında tüm tasarımı özetliyor:
KDV / indirim / toplam hesaplama mantığı yalnızca bu paket içinde yaşar; hem istemci (anlık gösterim) hem sunucu (kesin kayıt) aynı fonksiyonu çağırır. Bu dosyayı kopyalamayın, içe aktarın.
Kullanıcı satır eklerken ekranda gördüğü toplam, sunucunun veritabanına yazdığı toplam ve e-Fatura XML'indeki toplam aynı fonksiyondan çıkıyor. Bir kuruşluk farkın saklanabileceği ikinci bir yer yok.