مقدمة
حقل Monetary في أودو يظهر بسيطًا — رقم على الشاشة — لكنه يخبئ قواعد دقيقة تتعلق بالعملة والتقريب والدقة. فهم هذه القواعد يغيّر طريقة تصميمك للحقول المالية: بعد ذلك لن تعتمد على Float عادي لكل رقم له قيمة نقدية.
كلما فتحت فاتورة، أمر بيع، أو صفحة منتج في أودو، تكون قد تعاملت مع حقل Monetary. هذه الحقول موزعة في موديلات النظام وتتكفل بعرض الرموز النقدية، تنسيق الأرقام، وقواعد التقريب التي يحتاجها المحاسبون والمستخدمون النهائيون.
هذه المقالة موجهة للمطوّرين، الاستشاريين، ومديري النظام في بيئات أودو الذين يريدون فهم التفاصيل التقنية لحقول Monetary. إن كنت تبني موديول مخصّص، تجهّز لتقارير مالية، أو تبحث عن سبب فروق التقريب، ستجد هنا مرجعًا عمليًا ومباشرًا.
ما هي حقل المبالغ في أودو
نوع الحقل fields.Monetary هو نوع أساسي في إطار عمل أودو مُصمم خصيصًا للقيم المقومة بعملة: أسعار، مبالغ، إجماليات، أو أي رقم يُمثّل مالًا.
الفرق الأساسي عن Float العادي هو ارتباطه الإلزامي بمرجع عملة. حقل Monetary دائمًا يعرف العملة التي يعمل بها، ويستخدم إعدادات تلك العملة لتحديد عدد المنازل العشرية وقاعدة التقريب عند العرض والتخزين.
كيف يظهر في الواجهة
في واجهة أودو يعرض حقل Monetary الرقم بصيغة العملة المرتبطة به: إذا كانت العملة يورو سترى شيئًا مثل € 1,234.50، وللدولار ستظهر $ 1,234.50. عدد المنازل العشرية والتنسيق يعتمدان على إعدادات سجل العملة.
يمكن تحرير الحقل بسهولة في شاشات النموذج، ويعرض بشكل مرتب في القوائم، ويتكامل مع الجداول المحورية والتقارير المالية. المستخدم لا يهتم بتنسيق الرقم — أودو يتولى ذلك تلقائيًا.
النوع المُخزن في قاعدة البيانات
في مستوى قاعدة البيانات يخزن الحقل كـ double precision float في PostgreSQL، بينما معلومات العملة محفوظة في سجل منفصل res.currency مرتبط عبر حقل Many2one على نفس الموديل.
الفصل بين قيمة المبلغ وسجل العملة مقصود: يحافظ على بنية الجدول بسيطة ويسمح بتغيير العملة دون لمس العمود الرقمي نفسه.
كيف يعمل الحقل
معرفة هذه الآلية تساعدك على تفادي فروق التقريب ومشكلات العرض التي تظهر كثيرًا في تخصيصات أودو عندما لا تُستخدم القواعد الصحيحة.
معامل currency_field
كل حقل Monetary يجب أن يكون مربوطًا بحقل Many2one يُشير إلى res.currency. افتراضيًا يبحث أودو عن حقل اسمه currency_id على نفس الموديل، لكن يمكنك تحديد اسم آخر عبر currency_field كما في المثال التالي:
amount = fields.Monetary(string='Amount', currency_field='currency_id')إذا غاب حقل العملة أو لم يُعبَّأ، يلجأ أودو افتراضيًا إلى عملة الشركة. هذا يمنع الأخطاء الحادة، لكنه قد يخفي أخطاء تنسيق في بيئات عملة متعددة. لذلك من الأفضل دائمًا إعلان حقل العملة صراحةً.
التقريب والدقة
ميزة رئيسية تميّز Monetary عن Float هي قواعد التقريب. نموذج res.currency يحدد عدد المنازل العشرية وعامل التقريب لكل عملة. عند قراءة أو عرض قيمة Monetary يطبّق أودو هذه القواعد تلقائيًا.
بالتالي قيمة مخزنة مثل 1.2349999 لحقل يورو ستعرض كـ 1.23 وفقًا لقواعد العملة، وليس بصيغ متضاربة. هذا مهم جدًا لحساب الضرائب، إجماليات الفواتير، ومطابقة القيود. استخدام Float في سياقات مالية يؤدي غالبًا إلى فروق تقريب يصعب تتبعها.
التعامل مع ORM في أودو
عند القراءة عبر ORM يرجع حقل Monetary دائمًا float في بايثون، بينما سياق العملة يأتي من حقل العملة المرفق في نفس السجل. عند إجراء حسابات استخدم دالة round() الخاصة بسجل العملة للحفاظ على الدقة، مثل:
rounded_value = self.currency_id.round(self.amount)هذا يقي من تراكم أخطاء الأعداد العشرية التي تظهر عند جمع خطوط متعددة أو حسابات تكرارية.
حقول Monetary في تقارير QWeb
في قوالب تقارير QWeb يستفيد الحقل من ويدجت مخصص لعرضه بشكل صحيح في PDF وصفحات الويب، مثال:
<span t-esc="record.amount"
t-options='{"widget": "monetary", "display_currency": record.currency_id}'/>بهذه الطريقة يظهر رمز العملة وعدد المنازل العشرية الصحيح في كل مستند مولَّد بغض النظر عن العملة المرتبطة بالسجل.
حالات استخدام عملية
تطبيقات عملية للحقل في أودو
1. المبيعات: أسعار المنتجات وإجماليات الطلبات
حقول مثل price_unit، price_subtotal، وamount_total في أوامر البيع هي حقول Monetary. هي تتبع عملة الطلب — التي قد تختلف عن عملة تشغيل الشركة — وتعرض القيم وتقربها تبعًا لذلك.
لو أن مندوبًا أنشأ طلبًا بالدولار لشركة تعمل باليورو، فإن الحقل Monetary يتولى عرض القيم وتقريبها وتحويلها عند الحاجة بحسب سياق كل سجل.
2. المحاسبة: مبالغ الفواتير وخطوط الضريبة
في المحاسبة كل عمود مبلغ في الفاتورة عبارة عن حقل Monetary: amount_untaxed، amount_tax، amount_total. العملة المحددة في الفاتورة تقرر قواعد التقريب لكل هذه القيم.
هذا أمر بالغ الأهمية: اختلاف التقريب في خطوط الضرائب يؤدي إلى قيود متوازنة بشكل خاطئ وصعوبات في التسوية. اعتماد Monetary يقي من هذه المشاكل على مستوى البيانات.
3. إدارة العلاقات: الإيرادات المتوقعة في الفرص
حقل expected_revenue في وحدة CRM هو Monetary. فرق المبيعات تسجل قيم الفرص بعملة العميل، بينما لوحات التحكم والتحليلات تجمع وتقارن الأرقام بعد تحويلها لعملة الشركة عند الحاجة.
عمل هذه الآلية بسلاسة يعود إلى أن حقول Monetary تربط القيمة بسجل العملة مباشرة.
4. المشتريات: أسعار الموردين وأوامر الشراء
أوامر الشراء تستخدم Monetary للوحدات والإجماليات وفق عملة المورد المتفق عليها. فاتورة مورد بالين الياباني تُعامل مثل فاتورة باليورو — الحقل يهتم بالدقة والتنسيق دون تدخل يدوي من فريق المشتريات.
5. حقول مخصّصة: تتبع الميزانية والأهداف
الطلبات الشائعة مثل إضافة حقل ميزانية، هدف إيراد، أو سقف تكلفة إلى مشروع أو قسم تُحل بحقل Monetary. يندمج طبيعيًا مع عملة الشركة، ويعرض بشكل صحيح في الشاشات والتقارير والتصدير.
يمكنك استخدام Float تقنيًا لذلك، لكن سرعان ما ستواجه تناقضات في العرض وفروق تقريب حين تدخل سيناريوهات متعددة العملات.
إنشاء الحقل أو تخصيصه
طرق إنشاء حقل Monetary
هناك طريقتان رئيسيتان لإضافة حقل Monetary إلى موديل في أودو: باستخدام Odoo Studio بدون كود، أو عبر وحدة بايثون مخصّصة إذا احتجت تحكم كامل.
باستخدام Odoo Studio
تتضمن أودو ستوديو نوع Monetary في واجهة إضافة الحقول. عند إضافته ينشئ ستوديو تلقائيًا حقل currency_id إن لم يكن موجودًا مسبقًا. لكن لاحظ أن ستوديو يستعمل بادئة x_ للأسماء (مثال: x_studio_budget) ويجب مراجعة مشاركة حقل العملة إن أُنشئت عدة حقول Monetary على نفس الموديل.
بالنسبة للحالات البسيطة، ستوديو هو أسرع حل لفرق الأعمال التي لا تملك صلاحية تطوير، ويغطي معظم احتياجات الحقول دون كتابة كود.
النهج التقني: حقول بايثون
في موديول مخصّص تحتاج لتعريف الحقل وحقله المرتبط بالعملة معًا. هذا هو النمط القياسي في تطوير أودو بالبايثون:
from odoo import fields, models
class ProjectTask(models.Model):
_inherit = 'project.task'
x_budget = fields.Monetary(
string='Budget',
currency_field='x_budget_currency_id',
)
x_budget_currency_id = fields.Many2one(
comodel_name='res.currency',
string='Budget Currency',
default=lambda self: self.env.company.currency_id,
)تعيين عملة الشركة كقيمة افتراضية خيار عملي لمعظم الحقول الداخلية لأنه يمنع ظهور حقل العملة فارغًا عند فتح سجل جديد، مما يحافظ على تنسيق Monetary سليمًا من البداية.
حقول Monetary المحسوبة
يمكن استخدام Monetary كحقول محسوبة. عند جمع مبالغ خطوط أو تطبيق صيغة لإنتاج نتيجة مالية، اتبع النمط التالي:
x_total_budget = fields.Monetary(
string='Total Budget',
currency_field='currency_id',
compute='_compute_total_budget',
store=True,
)
@api.depends('x_line_ids.x_amount')
def _compute_total_budget(self):
for record in self:
record.x_total_budget = sum(record.x_line_ids.mapped('x_amount'))خاصية store=True مهمة إذا رغبت بالبحث، الفرز، أو التجميع على هذا الحقل في القوائم أو التقارير. الحقول المحسوبة غير المخزنة لا تُستخدم في نطاقات ORM أو عروض SQL.
إضافة الحقل عبر API
إذا كنت تُنشئ الحقول برمجيًا عبر XML-RPC (مثل نص تهيئة عن بُعد)، يمكنك إنشاء حقل Monetary عبر نموذج ir.model.fields كما في المثال:
models.execute_kw(ODOO_DB, uid, ODOO_API_KEY,
'ir.model.fields', 'create',
[{
'name': 'x_budget',
'field_description': 'Budget',
'model_id': model_id,
'ttype': 'monetary',
'currency_field': 'currency_id',
'state': 'manual',
}]
)هذا جزء من أدوات التخصيص المتاحة عبر API والتي تُستخدم عادة في نصوص التهيئة الآلية أو نقل الإعدادات بين بيئات.
أفضل الممارسات
أهم ممارسات استخدام Monetary
اتِّبع قواعد واضحة عند التعامل مع الحقول المالية للحفاظ على اتساق النظام وتجنّب أخطاء يصعب تصحيحها لاحقًا.
1. لا تستخدم Float للقيم المالية
هذه القاعدة الأساسية: إن كان الحقل يمثل مالًا، استعمل fields.Monetary. Float لا يملك وعيًا بالعملة ولا يطبق قواعد التقريب، ما يؤدي لمشكلات عند التعامل مع عدة عملات.
2. أعلن حقل العملة صراحةً
لا تعتمد على الرجوع الافتراضي إلى currency_id ما لم يكن موجودًا فعليًا على الموديل. حدد currency_field وأعلن الـ Many2one إلى res.currency لوضوح العلاقة ومنع السلوك الصامت الخاطئ في بيئات متعددة العملات.
3. عيّن عملة افتراضية
لحالات داخلية تستخدم عادة عملة الشركة عيّن القيمة الافتراضية: default=lambda self: self.env.company.currency_id. يمنع ذلك ظهور الحقل بلا عملة على السجلات الجديدة ويضمن تنسيقًا ثابتًا.
4. استخدم store=True للحقول المحسوبة التي ستبحث عنها
إذا كان الحقل المحسوب سيُستخدم في مرشحات أو تقارير، فعليك تعيين store=True لأن الحقول غير المخزنة لا تظهر في نطاقات ORM ولا يمكن فرزها في SQL-based views.
5. طبّق round() للعملة في الحسابات الوسيطة
عند إجراء عمليات حسابية متعددة على قيم مالية طبّق self.currency_id.round(value) بعد خطوات مهمة بدل الانتظار للنهاية. هذا يحدّ من أخطاء تراكم الفواصل العشرية ويجعل النتائج متوقعة.
6. كن واضحًا عند تجميع بيانات متعددة العملات
المشكلات الشائعة
عند تجميع قيم Monetary عبر سجلات بعملات مختلفة لا تجمع الأرقام الخام. حوّل القيم إلى عملة مشتركة أولًا باستخدام res.currency.compute() أو اجعل التقرير مقيّدًا بعملة معينة؛ جمع العملات المختلفة يعطي نتائج غير قابلة للتفسير ماليًا.
أخطاء شائعة ونصائح لتجنّبها
الخطأ 1: غياب حقل العملة
أكثر أخطاء المصممين هو نسيان تعريف حقل Many2one للّعملة. إذا لم يكن currency_id موجودًا قد يلجأ النظام لصيغة الشركة بصمت في بعض الحالات ويطلّق خطأ في حالات أخرى. لذلك أنشئ حقل العملة مع أي Monetary دائمًا.
الخطأ 2: مشاركة حقل عملة واحد لحقلين بنوايا مختلفة
إن كان لديك حقلان Monetary على نفس الموديل مقصود لهما العمل بعملتين مختلفتين (سعر عميل باليورو وتكلفة مورد بالدولار مثلاً)، فلا تشاركا نفس currency_id. كل حقل يحتاج مرجع عملة خاص به وإلا ستُفرض عملة واحدة على الحقلين مما يغيّر البيانات ويشوّش الواجهة.
الخطأ 3: فروق التقريب عند التجميع عبر عملات
جمع قيم Monetary عبر سجلات بعملات مختلفة يظهر مُجموعًا خاطئًا لأنك تجمع وحدات غير متوافقة. الحل أن تطبّع القيم إلى عملة واحدة قبل الجمع.
الخطأ 4: مقارنات Float في بحث ORM
البحث عن قيمة مالية بمساواة تامة (مثال: amount = 10.0) قد يفشل بسبب تخزين float في قاعدة البيانات. استخدم نطاقات ≤ و ≥ مع هامش صغير، أو طبّق تقريب العملة قبل المقارنة في منطق بايثون.
الخطأ 5: تجاهل تقريب العملة عند الاستيراد
الخاتمة
عند استيراد بيانات عبر CSV أو XML-RPC، القيم تُخزن كما هي دون تقريب تلقائي. إذا كانت الأرقام تحتوي منازل عشرية أكثر مما تسمح به العملة فسوف تُخزن وتظهر بشكل مختلف عند العرض. ضمّن تقريب العملة في سكربتات الاستيراد أو جهّز البيانات مسبقًا لتجنّب الفروقات.
الخلاصة: لماذا يهم الأمر
حقل Monetary يبدو بسيطًا لكنه يحمل سلوكًا مهمًا مرتبطًا بسجل العملة: تقريب صحيح، عرض ثابت، وسلوك متوقع عبر الواجهة والتقارير. اتباع قواعد استخدامه يوفر عليك أخطاء دقيقة ومضنية عند التشغيل الفعلي.
هل تحتاج مساعدة في تنفيذ أودو؟
استخدامه الصحيح — عبر الربط الصريح بحقل العملة ورفض استبداله بـ Float للقيم المالية — سيقيك من فئات من العيوب التي يصعب إصلاحها لاحقًا. هذا النوع مبني في نموذج بيانات أودو لسبب واضح.
سواء كنت تتبع دليل مطور أودو، تعدّل موديل قياسي، أو تبني حلًا من الصفر، اختيارك لحقول Monetary بشكل سليم يُعد قرارًا أساسيًا في كيفية تعامل نظامك مع المال بثقة وموثوقية. في Dasolo نساعد الشركات على تنفيذ وتخصيص وتحسين أودو على مستوياته المختلفة. إذا أردت بنية بيانات نظيفة، استراتيجية حقول مخصّصة، دعم متعدد العملات، أو تنفيذ أودو متكامل، فريقنا يملك الخبرة الفنية والوظيفية لإنجاز ذلك بشكل صحيح. إذا كانت لديك أسئلة حول حقول Monetary أو أي جانب آخر من تنفيذ أودو، يسعدنا أن نساعدك.