> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kayanos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# دوال المبالغ المالية

> جميع دوال المبالغ المالية المسجلة، مع التواقيع والأمثلة للمبالغ بعملة محددة والمجاميع الدقيقة والتقريب والتوزيع وأسعار الصرف.

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

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

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

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

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

> **allocate**
>
> ### `allocate`
>
> توزّع مبلغاً حسب أوزان بحيث يساوي مجموع الأجزاء الإجمالي تماماً بعد تقريبه إلى منازل العملة (منزلتان للرقم العادي). تذهب الوحدات المتبقية إلى الأجزاء ذات الباقي الأكبر، والأسبق أولاً عند التساوي. الأوزان الصفرية كلها تعطي أجزاء صفرية، والأوزان التي ليست قائمة تعطي قائمة فارغة. لا تحمل الأجزاء معادلاً بعملة الأساس.
>
> **التوقيع:** `allocate(value, weights)`
>
> **مثال:**
>
> ```txt theme={null}
> allocate(money(100, "USD"), [1, 1, 1]) // [33.34, 33.33, 33.33] USD
> ```
>
> **التوافر:** متاحة في لغة تعبيرات المنشئ المشتركة وفي قوالب المستندات بصيغتي الدالة والتحويل. لا تتوفر منازل عملات المؤسسة ونمط التقريب وعملة الأساس وقيم حقول المبالغ المالية إلا في الحقول المحسوبة للكيانات التي يقيّمها الخادم عند إنشاء السجل أو حفظه.
>
> **ملاحظة:** يمكن أيضاً كتابتها كتحويل عندما تكون القيمة الأولى هي المدخل: `value | allocate(...)`.

> **base**
>
> ### `base`
>
> مع قيمة مالية تعيد معادلها الملتقط بعملة الأساس كرقم، أو `null` إذا لم يُلتقط معادل. ومن دون وسيط تعيد رمز عملة الأساس للمؤسسة داخل الحقل المحسوب، و`null` في غير ذلك. وأي قيمة أخرى تعطي `null`.
>
> **التوقيع:** `base(value?)`
>
> **مثال:**
>
> ```txt theme={null}
> base($.contract_value) // captured base equivalent, or null
> base() // the organization’s base currency code, such as "SYP"
> ```
>
> **التوافر:** متاحة في لغة تعبيرات المنشئ المشتركة وفي قوالب المستندات بصيغتي الدالة والتحويل. لا تتوفر منازل عملات المؤسسة ونمط التقريب وعملة الأساس وقيم حقول المبالغ المالية إلا في الحقول المحسوبة للكيانات التي يقيّمها الخادم عند إنشاء السجل أو حفظه.
>
> **ملاحظة:** يمكن أيضاً كتابتها كتحويل عندما تكون القيمة الأولى هي المدخل: `value | base(...)`.

> **convert**
>
> ### `convert`
>
> تحوّل قيمة مالية إلى عملة أخرى بسعر المؤسسة (`options.type` و`options.on` كما في `rateOn`) وتقرّب النتيجة إلى منازل عملة الهدف بنمط التقريب في المؤسسة. تعيد القيمة كما هي إذا كانت بتلك العملة أصلاً، و`null` إذا لم يكن الوسيط الأول قيمة مالية أو لم يكن `to` نصاً. وتتوقف بالخطأ `MONEY_RATE_MISSING` عندما لا يتوفر سعر مقبول. تسجل النتيجة السعر ونوعه ولكن بلا معادل بعملة الأساس.
>
> **التوقيع:** `convert(value, to, options?)`
>
> **مثال:**
>
> ```txt theme={null}
> convert($.contract_value, "USD", { on: $.invoice_date, type: "market" })
> ```
>
> **التوافر:** لا تقرأ أسعار صرف المؤسسة إلا في الحقول المحسوبة للكيانات التي يقيّمها الخادم عند إنشاء السجل أو حفظه. وفي غير ذلك تعيد `rateOn` و`fx` القيمة `null` وتتوقف `convert` بالخطأ `MONEY_RATE_MISSING`. صيغتا الدالة والتحويل متاحتان.
>
> **ملاحظة:** يمكن أيضاً كتابتها كتحويل عندما تكون القيمة الأولى هي المدخل: `value | convert(...)`.

> **currencyOf**
>
> ### `currencyOf`
>
> تعيد رمز عملة القيمة المالية وفق ISO، أو `null` لأي قيمة أخرى.
>
> **التوقيع:** `currencyOf(value)`
>
> **مثال:**
>
> ```txt theme={null}
> currencyOf(money(5, "EUR")) // "EUR"
> ```
>
> **التوافر:** متاحة في لغة تعبيرات المنشئ المشتركة وفي قوالب المستندات بصيغتي الدالة والتحويل. لا تتوفر منازل عملات المؤسسة ونمط التقريب وعملة الأساس وقيم حقول المبالغ المالية إلا في الحقول المحسوبة للكيانات التي يقيّمها الخادم عند إنشاء السجل أو حفظه.
>
> **ملاحظة:** يمكن أيضاً كتابتها كتحويل عندما تكون القيمة الأولى هي المدخل: `value | currencyOf(...)`.

> **fx**
>
> ### `fx`
>
> اسم مختصر للدالة `rateOn` بالوسائط والقيم الافتراضية والنتيجة نفسها.
>
> **التوقيع:** `fx(currency, on?, type?, to?)`
>
> **مثال:**
>
> ```txt theme={null}
> fx("EUR", $.invoice_date) // same as rateOn("EUR", $.invoice_date)
> ```
>
> **التوافر:** لا تقرأ أسعار صرف المؤسسة إلا في الحقول المحسوبة للكيانات التي يقيّمها الخادم عند إنشاء السجل أو حفظه. وفي غير ذلك تعيد `rateOn` و`fx` القيمة `null` وتتوقف `convert` بالخطأ `MONEY_RATE_MISSING`. صيغتا الدالة والتحويل متاحتان.
>
> **ملاحظة:** يمكن أيضاً كتابتها كتحويل عندما تكون القيمة الأولى هي المدخل: `value | fx(...)`.

> **isMoney**
>
> ### `isMoney`
>
> تتحقق مما إذا كانت القيمة قيمة مالية. لا يكون حقل المبلغ قيمة مالية إلا حيث تضعه العمليات المدركة للمبالغ المالية في سياق الحقل المحسوب؛ وإلا فهو رقم عادي.
>
> **التوقيع:** `isMoney(value)`
>
> **مثال:**
>
> ```txt theme={null}
> isMoney(money(5, "EUR")) // true
> isMoney(5) // false
> ```
>
> **التوافر:** متاحة في لغة تعبيرات المنشئ المشتركة وفي قوالب المستندات بصيغتي الدالة والتحويل. لا تتوفر منازل عملات المؤسسة ونمط التقريب وعملة الأساس وقيم حقول المبالغ المالية إلا في الحقول المحسوبة للكيانات التي يقيّمها الخادم عند إنشاء السجل أو حفظه.
>
> **ملاحظة:** يمكن أيضاً كتابتها كتحويل عندما تكون القيمة الأولى هي المدخل: `value | isMoney(...)`.

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

> **rateOn**
>
> ### `rateOn`
>
> تعيد سعر الصرف من عملة إلى عملة الهدف (عملة الأساس للمؤسسة عند حذف `to`) كرقم. الوسيط `on` تاريخ نصي أو كائن تاريخ، وقيمته الافتراضية لحظة التقييم؛ والوسيط `type` مفتاح نوع السعر، وقيمته الافتراضية نوع السعر الافتراضي للمؤسسة. تعيد 1 عندما تكون العملة هي عملة الهدف، و`null` عندما لا يتوفر سعر مقبول. البحث غير متزامن، وينتظره التعبير.
>
> **التوقيع:** `rateOn(currency, on?, type?, to?)`
>
> **مثال:**
>
> ```txt theme={null}
> rateOn("USD", $.invoice_date, "market") // USD to the base currency on the invoice date, or null
> ```
>
> **التوافر:** لا تقرأ أسعار صرف المؤسسة إلا في الحقول المحسوبة للكيانات التي يقيّمها الخادم عند إنشاء السجل أو حفظه. وفي غير ذلك تعيد `rateOn` و`fx` القيمة `null` وتتوقف `convert` بالخطأ `MONEY_RATE_MISSING`. صيغتا الدالة والتحويل متاحتان.
>
> **ملاحظة:** يمكن أيضاً كتابتها كتحويل عندما تكون القيمة الأولى هي المدخل: `value | rateOn(...)`.

> **roundMoney**
>
> ### `roundMoney`
>
> تقرّب القيمة المالية إلى عدد منازل عملتها، وتقرّب الرقم العادي إلى منزلتين أو إلى منازل رمز العملة الذي تمرره. إذا كان الوسيط الثاني رقماً فهو عدد المنازل. النمط أحد `half_up` أو `half_even` أو `half_down` أو `up` أو `down`؛ ومن دونه يُطبَّق نمط التقريب في المؤسسة. تحتفظ القيمة المالية المقرّبة بعملتها ومعادلها، وتُعاد القيمة غير الرقمية كما هي.
>
> **التوقيع:** `roundMoney(value, currencyOrDecimals?, mode?)`
>
> **مثال:**
>
> ```txt theme={null}
> roundMoney(money(2.675, "USD"), 2, "half_even") // 2.68 USD
> roundMoney(12.3456, "KWD") // 12.346
> ```
>
> **التوافر:** متاحة في لغة تعبيرات المنشئ المشتركة وفي قوالب المستندات بصيغتي الدالة والتحويل. لا تتوفر منازل عملات المؤسسة ونمط التقريب وعملة الأساس وقيم حقول المبالغ المالية إلا في الحقول المحسوبة للكيانات التي يقيّمها الخادم عند إنشاء السجل أو حفظه.
>
> **ملاحظة:** يمكن أيضاً كتابتها كتحويل عندما تكون القيمة الأولى هي المدخل: `value | roundMoney(...)`.

> **sumBase**
>
> ### `sumBase`
>
> تجمع معادلات عملة الأساس الملتقطة للقيم المالية في القائمة، مهما اختلفت عملاتها، وتعيد رقماً عادياً. تتجاوز القيم المالية التي لا معادل لها والأرقام العادية؛ والقائمة الفارغة أو القيمة التي ليست قائمة تعطي 0.
>
> **التوقيع:** `sumBase(list)`
>
> **مثال:**
>
> ```txt theme={null}
> sumBase([$.goods_total, $.freight_cost]) // total of both captured base equivalents
> ```
>
> **التوافر:** متاحة في لغة تعبيرات المنشئ المشتركة وفي قوالب المستندات بصيغتي الدالة والتحويل. لا تتوفر منازل عملات المؤسسة ونمط التقريب وعملة الأساس وقيم حقول المبالغ المالية إلا في الحقول المحسوبة للكيانات التي يقيّمها الخادم عند إنشاء السجل أو حفظه.
>
> **ملاحظة:** يمكن أيضاً كتابتها كتحويل عندما تكون القيمة الأولى هي المدخل: `value | sumBase(...)`.

> **sumMoney**
>
> ### `sumMoney`
>
> تجمع عناصر القائمة بدقة تامة. يجب أن تكون القيم المالية بعملة واحدة (وإلا ظهر الخطأ `MONEY_CURRENCY_MISMATCH`) والنتيجة قيمة مالية، وتُضاف الأرقام العادية في القائمة إلى مبلغها. قائمة الأرقام العادية تعطي رقماً، والقائمة الخالية من القيم الرقمية تعطي 0، والقيمة التي ليست قائمة تعطي `null`. لا يحتفظ المجموع بمعادل عملة الأساس إلا إذا كان لكل قيمة مالية معادل ولم تتضمن القائمة أرقاماً عادية.
>
> **التوقيع:** `sumMoney(list)`
>
> **مثال:**
>
> ```txt theme={null}
> sumMoney([money(100, "USD"), money(25.5, "USD")]) // 125.5 USD
> ```
>
> **التوافر:** متاحة في لغة تعبيرات المنشئ المشتركة وفي قوالب المستندات بصيغتي الدالة والتحويل. لا تتوفر منازل عملات المؤسسة ونمط التقريب وعملة الأساس وقيم حقول المبالغ المالية إلا في الحقول المحسوبة للكيانات التي يقيّمها الخادم عند إنشاء السجل أو حفظه.
>
> **ملاحظة:** يمكن أيضاً كتابتها كتحويل عندما تكون القيمة الأولى هي المدخل: `value | sumMoney(...)`.

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

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

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

| الخاصية | المعنى |
| - | - |
| `.amount` | المبلغ كرقم. |
| `.currency` | رمز العملة وفق ISO، مثل `USD`. |
| `.base` | المعادل بعملة الأساس للمؤسسة كما التُقط عند حفظ السجل، أو `null`. |
| `.rate` | سعر الصرف الذي التُقطت به القيمة، أو `null`. |

تعطي `.rateDate` و`.rateType` تاريخ ذلك السعر ونوعه. عندما تكون نتيجة الحقل المحسوب قيمة مالية، يخزن الحقل مبلغها.

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

| التعبير | النتيجة |
| - | - |
| مبلغ `+` أو `-` مبلغ | مبلغ، بشرط أن تكون العملة واحدة |
| مبلغ `+` أو `-` رقم | مبلغ بالعملة نفسها |
| مبلغ `*` رقم | مبلغ بالعملة نفسها |
| مبلغ `*` مبلغ | رقم عادي |
| مبلغ `/` مبلغ | نسبة كرقم عادي، بشرط أن تكون العملة واحدة |
| مبلغ `/` رقم | مبلغ بالعملة نفسها |
| `==` `!=` `<` `<=` `>` `>=` | تقارن مبلغاً بمبلغ من العملة نفسها، أو مبلغاً برقم |

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

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

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

```txt theme={null}
$.goods_total + convert($.freight_cost, currencyOf($.goods_total), { on: $.invoice_date })
```

عندما يتوقف تعبير حقل محسوب بخطأ، يحتفظ الحقل بقيمته المخزنة سابقاً.

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

تعمل حسابات المبالغ على أعداد عشرية دقيقة لا على أعداد الفاصلة العائمة، فلا تنحرف المبالغ:

```txt theme={null}
money(0.1, "USD") + money(0.2, "USD") // 0.3 USD تماماً
0.1 + 0.2 // 0.30000000000000004 مع الأرقام العادية كما كان سابقاً
```

لا تُقرَّب النتائج تلقائياً: تحتفظ `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 والقوائم الفارغة.
* لا تضع أسراراً أو رموز وصول أو بيانات شخصية حساسة داخل تعبير.
* راجع [سياقات وتوافر التعبيرات](https://docs.kayanos.com/ar/reference/expressions/contexts.md) قبل نسخ تعبير بين ميزتين.

![دوال المبالغ المالية في KayanOS](https://kayanos.app/docs-images/ar/reference/expressions-helpers-math.png)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.