الانتقال إلى المحتوى الرئيسي

​
متى تستخدم هذه الدوال؟

استخدم هذه الدوال عندما تكون القيمة مبلغاً بعملة محددة. تحتفظ القيمة المالية بعملتها، وتُجمع وتُقارن بدقة تامة، وترفض خلط عملتين دون تحويل. تفهم العمليات الحسابية وعمليات المقارنة القيم المالية أيضاً، أما الأرقام العادية فتبقى على سلوكها السابق تماماً.

​
طريقة الكتابة

استخدم الدالة بصيغة roundMoney($.unit_price * $.quantity). لا تكون كل دالة متاحة في كل مكان: دوال التحقق ودوال النموذج ودوال قالب المستند لها عقود سياق مختلفة. لا تفترض أن اقتراح المحرر يعني أن الدالة مدعومة وقت التشغيل.

​
مرجع الدوال الكامل

​
allocate

توزّع مبلغاً حسب أوزان بحيث يساوي مجموع الأجزاء الإجمالي تماماً بعد تقريبه إلى منازل العملة (منزلتان للرقم العادي). تذهب الوحدات المتبقية إلى الأجزاء ذات الباقي الأكبر، والأسبق أولاً عند التساوي. الأوزان الصفرية كلها تعطي أجزاء صفرية، والأوزان التي ليست قائمة تعطي قائمة فارغة. لا تحمل الأجزاء معادلاً بعملة الأساس.التوقيع: allocate(value, weights)مثال:
التوافر: متاحة في لغة تعبيرات المنشئ المشتركة وفي قوالب المستندات بصيغتي الدالة والتحويل. لا تتوفر منازل عملات المؤسسة ونمط التقريب وعملة الأساس وقيم حقول المبالغ المالية إلا في الحقول المحسوبة للكيانات التي يقيّمها الخادم عند إنشاء السجل أو حفظه.ملاحظة: يمكن أيضاً كتابتها كتحويل عندما تكون القيمة الأولى هي المدخل: value | allocate(...).

​
base

مع قيمة مالية تعيد معادلها الملتقط بعملة الأساس كرقم، أو null إذا لم يُلتقط معادل. ومن دون وسيط تعيد رمز عملة الأساس للمؤسسة داخل الحقل المحسوب، وnull في غير ذلك. وأي قيمة أخرى تعطي null.التوقيع: base(value?)مثال:
التوافر: متاحة في لغة تعبيرات المنشئ المشتركة وفي قوالب المستندات بصيغتي الدالة والتحويل. لا تتوفر منازل عملات المؤسسة ونمط التقريب وعملة الأساس وقيم حقول المبالغ المالية إلا في الحقول المحسوبة للكيانات التي يقيّمها الخادم عند إنشاء السجل أو حفظه.ملاحظة: يمكن أيضاً كتابتها كتحويل عندما تكون القيمة الأولى هي المدخل: value | base(...).

​
convert

تحوّل قيمة مالية إلى عملة أخرى بسعر المؤسسة (options.type وoptions.on كما في rateOn) وتقرّب النتيجة إلى منازل عملة الهدف بنمط التقريب في المؤسسة. تعيد القيمة كما هي إذا كانت بتلك العملة أصلاً، وnull إذا لم يكن الوسيط الأول قيمة مالية أو لم يكن to نصاً. وتتوقف بالخطأ MONEY_RATE_MISSING عندما لا يتوفر سعر مقبول. تسجل النتيجة السعر ونوعه ولكن بلا معادل بعملة الأساس.التوقيع: convert(value, to, options?)مثال:
التوافر: لا تقرأ أسعار صرف المؤسسة إلا في الحقول المحسوبة للكيانات التي يقيّمها الخادم عند إنشاء السجل أو حفظه. وفي غير ذلك تعيد rateOn وfx القيمة null وتتوقف convert بالخطأ MONEY_RATE_MISSING. صيغتا الدالة والتحويل متاحتان.ملاحظة: يمكن أيضاً كتابتها كتحويل عندما تكون القيمة الأولى هي المدخل: value | convert(...).

​
currencyOf

تعيد رمز عملة القيمة المالية وفق ISO، أو null لأي قيمة أخرى.التوقيع: currencyOf(value)مثال:
التوافر: متاحة في لغة تعبيرات المنشئ المشتركة وفي قوالب المستندات بصيغتي الدالة والتحويل. لا تتوفر منازل عملات المؤسسة ونمط التقريب وعملة الأساس وقيم حقول المبالغ المالية إلا في الحقول المحسوبة للكيانات التي يقيّمها الخادم عند إنشاء السجل أو حفظه.ملاحظة: يمكن أيضاً كتابتها كتحويل عندما تكون القيمة الأولى هي المدخل: value | currencyOf(...).

​
fx

اسم مختصر للدالة rateOn بالوسائط والقيم الافتراضية والنتيجة نفسها.التوقيع: fx(currency, on?, type?, to?)مثال:
التوافر: لا تقرأ أسعار صرف المؤسسة إلا في الحقول المحسوبة للكيانات التي يقيّمها الخادم عند إنشاء السجل أو حفظه. وفي غير ذلك تعيد rateOn وfx القيمة null وتتوقف convert بالخطأ MONEY_RATE_MISSING. صيغتا الدالة والتحويل متاحتان.ملاحظة: يمكن أيضاً كتابتها كتحويل عندما تكون القيمة الأولى هي المدخل: value | fx(...).

​
isMoney

تتحقق مما إذا كانت القيمة قيمة مالية. لا يكون حقل المبلغ قيمة مالية إلا حيث تضعه العمليات المدركة للمبالغ المالية في سياق الحقل المحسوب؛ وإلا فهو رقم عادي.التوقيع: isMoney(value)مثال:
التوافر: متاحة في لغة تعبيرات المنشئ المشتركة وفي قوالب المستندات بصيغتي الدالة والتحويل. لا تتوفر منازل عملات المؤسسة ونمط التقريب وعملة الأساس وقيم حقول المبالغ المالية إلا في الحقول المحسوبة للكيانات التي يقيّمها الخادم عند إنشاء السجل أو حفظه.ملاحظة: يمكن أيضاً كتابتها كتحويل عندما تكون القيمة الأولى هي المدخل: value | isMoney(...).

​
money

تنشئ قيمة مالية من مبلغ (رقم أو نص عشري) ورمز عملة وفق ISO من ثلاثة أحرف لاتينية كبيرة. تعيد null إذا لم يكن المبلغ رقمياً أو لم يكن الرمز ثلاثة أحرف كبيرة. ويُحفظ مفتاح الفئة النقدية الاختياري مع القيمة.التوقيع: money(amount, currency, denomination?)مثال:
التوافر: متاحة في لغة تعبيرات المنشئ المشتركة وفي قوالب المستندات بصيغتي الدالة والتحويل. لا تتوفر منازل عملات المؤسسة ونمط التقريب وعملة الأساس وقيم حقول المبالغ المالية إلا في الحقول المحسوبة للكيانات التي يقيّمها الخادم عند إنشاء السجل أو حفظه.ملاحظة: يمكن أيضاً كتابتها كتحويل عندما تكون القيمة الأولى هي المدخل: value | money(...).

​
rateOn

تعيد سعر الصرف من عملة إلى عملة الهدف (عملة الأساس للمؤسسة عند حذف to) كرقم. الوسيط on تاريخ نصي أو كائن تاريخ، وقيمته الافتراضية لحظة التقييم؛ والوسيط type مفتاح نوع السعر، وقيمته الافتراضية نوع السعر الافتراضي للمؤسسة. تعيد 1 عندما تكون العملة هي عملة الهدف، وnull عندما لا يتوفر سعر مقبول. البحث غير متزامن، وينتظره التعبير.التوقيع: rateOn(currency, on?, type?, to?)مثال:
التوافر: لا تقرأ أسعار صرف المؤسسة إلا في الحقول المحسوبة للكيانات التي يقيّمها الخادم عند إنشاء السجل أو حفظه. وفي غير ذلك تعيد rateOn وfx القيمة null وتتوقف convert بالخطأ MONEY_RATE_MISSING. صيغتا الدالة والتحويل متاحتان.ملاحظة: يمكن أيضاً كتابتها كتحويل عندما تكون القيمة الأولى هي المدخل: value | rateOn(...).

​
roundMoney

تقرّب القيمة المالية إلى عدد منازل عملتها، وتقرّب الرقم العادي إلى منزلتين أو إلى منازل رمز العملة الذي تمرره. إذا كان الوسيط الثاني رقماً فهو عدد المنازل. النمط أحد half_up أو half_even أو half_down أو up أو down؛ ومن دونه يُطبَّق نمط التقريب في المؤسسة. تحتفظ القيمة المالية المقرّبة بعملتها ومعادلها، وتُعاد القيمة غير الرقمية كما هي.التوقيع: roundMoney(value, currencyOrDecimals?, mode?)مثال:
التوافر: متاحة في لغة تعبيرات المنشئ المشتركة وفي قوالب المستندات بصيغتي الدالة والتحويل. لا تتوفر منازل عملات المؤسسة ونمط التقريب وعملة الأساس وقيم حقول المبالغ المالية إلا في الحقول المحسوبة للكيانات التي يقيّمها الخادم عند إنشاء السجل أو حفظه.ملاحظة: يمكن أيضاً كتابتها كتحويل عندما تكون القيمة الأولى هي المدخل: value | roundMoney(...).

​
sumBase

تجمع معادلات عملة الأساس الملتقطة للقيم المالية في القائمة، مهما اختلفت عملاتها، وتعيد رقماً عادياً. تتجاوز القيم المالية التي لا معادل لها والأرقام العادية؛ والقائمة الفارغة أو القيمة التي ليست قائمة تعطي 0.التوقيع: sumBase(list)مثال:
التوافر: متاحة في لغة تعبيرات المنشئ المشتركة وفي قوالب المستندات بصيغتي الدالة والتحويل. لا تتوفر منازل عملات المؤسسة ونمط التقريب وعملة الأساس وقيم حقول المبالغ المالية إلا في الحقول المحسوبة للكيانات التي يقيّمها الخادم عند إنشاء السجل أو حفظه.ملاحظة: يمكن أيضاً كتابتها كتحويل عندما تكون القيمة الأولى هي المدخل: value | sumBase(...).

​
sumMoney

تجمع عناصر القائمة بدقة تامة. يجب أن تكون القيم المالية بعملة واحدة (وإلا ظهر الخطأ MONEY_CURRENCY_MISMATCH) والنتيجة قيمة مالية، وتُضاف الأرقام العادية في القائمة إلى مبلغها. قائمة الأرقام العادية تعطي رقماً، والقائمة الخالية من القيم الرقمية تعطي 0، والقيمة التي ليست قائمة تعطي null. لا يحتفظ المجموع بمعادل عملة الأساس إلا إذا كان لكل قيمة مالية معادل ولم تتضمن القائمة أرقاماً عادية.التوقيع: sumMoney(list)مثال:
التوافر: متاحة في لغة تعبيرات المنشئ المشتركة وفي قوالب المستندات بصيغتي الدالة والتحويل. لا تتوفر منازل عملات المؤسسة ونمط التقريب وعملة الأساس وقيم حقول المبالغ المالية إلا في الحقول المحسوبة للكيانات التي يقيّمها الخادم عند إنشاء السجل أو حفظه.ملاحظة: يمكن أيضاً كتابتها كتحويل عندما تكون القيمة الأولى هي المدخل: value | sumMoney(...).

​
التفاصيل التشغيلية والحالات الطرفية

​
القيم المالية وحقول المبالغ

القيمة المالية (MoneyValue) مبلغ مقترن بعملة. أنشئها بالدالة money(amount, currency). في الحقل المحسوب لكيان عندما يقيّمه الخادم، يُقرأ حقل المبلغ المالي كقيمة مالية إذا فعّلت المؤسسة العمليات المدركة للمبالغ المالية؛ وإلا يبقى رقماً عادياً وتعامله الدوال على هذا الأساس. تتيح القيمة المالية الخصائص التالية: تعطي .rateDate و.rateType تاريخ ذلك السعر ونوعه. عندما تكون نتيجة الحقل المحسوب قيمة مالية، يخزن الحقل مبلغها.

​
العمليات على القيم المالية

يعكس السالب الأحادي إشارة القيمة المالية. وتعطي القسمة على صفر Infinity كما في الأرقام العادية. ومقارنة قيمة مالية بقيمة غير رقمية مثل null تعطي false مع == وعمليات الترتيب، وtrue مع !=. وعندما لا يكون أي من الطرفين قيمة مالية، تعمل كل العمليات كما كانت تماماً.

​
عملة واحدة في كل عملية

جمع قيمتين ماليتين بعملتين مختلفتين أو طرح إحداهما من الأخرى أو قسمتها عليها أو مقارنتهما يوقف التعبير بالخطأ MONEY_CURRENCY_MISMATCH («لا يمكن جمع USD وEUR: حوّل إحداهما أولاً.»). وتطبق sumMoney القاعدة نفسها. حوّل أحد الطرفين أولاً:
عندما يتوقف تعبير حقل محسوب بخطأ، يحتفظ الحقل بقيمته المخزنة سابقاً.

​
حساب عشري دقيق

تعمل حسابات المبالغ على أعداد عشرية دقيقة لا على أعداد الفاصلة العائمة، فلا تنحرف المبالغ:
لا تُقرَّب النتائج تلقائياً: تحتفظ money(10, "USD") / 3 بما يصل إلى 18 منزلة عشرية، وتحتفظ نسبة مبلغ إلى مبلغ بما يصل إلى 10 منازل. ولا تقرّب النتيجة لك إلا convert وallocate. قرّب بالدالة round(m) أو roundMoney قبل عرض مبلغ أو مقارنته أو تخزينه إذا وجب أن يطابق دقة عملته.

​
التقريب

تقرّب round(m) وroundMoney(m) القيمة المالية إلى عدد منازل عملتها، ويبقى سلوك round(number, decimals) على الرقم العادي كما هو. في الحقل المحسوب الذي يقيّمه الخادم، تأتي المنازل العشرية من قائمة عملات المؤسسة ويأتي نمط التقريب من إعداد التقريب في المؤسسة. وفي غير ذلك يستخدم KayanOS منازل مدمجة (3 لكل من KWD وJOD وBHD وOMR وTND وLYD وIQD؛ و0 لكل من JPY وKRW وCLP وVND وISK؛ و2 لغيرها) مع نمط half_up. إذا ضُبط حقل المبلغ على عدد ثابت من المنازل يختلف عن منازل عملته، فمرر هذا العدد: roundMoney($.unit_price * $.quantity, 4). ولا تمرر نمط التقريب إلا عندما تفرضه قاعدة عمل، مثل roundMoney(m, 2, "half_even").

​
أسعار الصرف

لا تقرأ rateOn وfx وconvert أسعار صرف المؤسسة إلا في حقل محسوب لكيان يقيّمه الخادم. ويعتمد البحث على:
  • نوع السعر: النوع الذي تمرره، وإلا نوع السعر الافتراضي للمؤسسة.
  • التاريخ: تاريخ on الذي تمرره، وإلا لحظة تشغيل التعبير. لا تقرأ الدوال تاريخ مستند السجل من تلقاء نفسها؛ مرره صراحةً كما في convert(m, "USD", { on: $.invoice_date }).
  • سياسة السعر المفقود: تحدد سياسة نوع السعر أقصى عمر مقبول للسعر. في سياسة اليوم نفسه لا يُقبل إلا سعر ذلك اليوم، وفي سياسة أحدث سعر سابق يُقبل أحدث سعر سابق ضمن عدد الأيام المسموح. يغطي سعر النوع الشهري شهره كاملاً، وتُجرَّب أنواع الأسعار البديلة للنوع بالترتيب.
عندما لا يتوفر سعر مقبول، تعيد rateOn وfx القيمة null وتتوقف convert بالخطأ MONEY_RATE_MISSING. يجري كل تقييم لسجل 200 عملية بحث مختلفة عن الأسعار على الأكثر، ولا تجد عمليات البحث الإضافية سعراً. وخارج الحقل المحسوب الذي يقيّمه الخادم، كما في القواعد وقوالب المستندات وإعادة الحساب في الخلفية، لا تتوفر أسعار: تعيد rateOn القيمة null وتتوقف convert بالخطأ MONEY_RATE_MISSING ما لم تكن القيمة بالعملة المطلوبة أصلاً.

​
متى تكون .base فارغة

يُلتقط المعادل بعملة الأساس عند حفظ السجل بسعر صرف. وتكون .base وbase(m) بقيمة null عندما لم يُلتقط سعر لتلك القيمة، وكذلك للقيم المالية المنشأة داخل التعبير: money() وconvert() وallocate() وجمع مبلغ مع رقم عادي أو طرح أحدهما من الآخر. يغيّر الضرب في رقم أو القسمة عليه المعادل بالنسبة نفسها، ولا يحتفظ جمع قيمتين ماليتين بالمعادل إلا عندما يملكه الطرفان. تتجاوز sumBase القيم التي لا معادل لها، فقد يأتي المجموع أقل من الحقيقي؛ اختبر base(m) == null قبل الاعتماد عليه.

​
قائمة تحقق قبل النشر

  • ابدأ بقيمة معروفة وتحقق من النتيجة المتوقعة.
  • تعامل صراحةً مع القيم الفارغة وnull والقوائم الفارغة.
  • لا تضع أسراراً أو رموز وصول أو بيانات شخصية حساسة داخل تعبير.
  • راجع سياقات وتوافر التعبيرات قبل نسخ تعبير بين ميزتين.
دوال المبالغ المالية في KayanOS