إدارة تأجير المعارض

نظرة عامة — سوق الطرفيات المؤجَّرة

ما هي. تدير وحدة المعارض سوقًا يملك فيه المنظّم أجنحة العرض وأجهزة الدفع بالبطاقات، ويبيع المستأجرون (العارضون) من تلك الأجنحة عبر تمرير البطاقات على أجهزة المنظّم، بينما يورّد البنك جميع متحصلات البطاقات إلى حساب المنظّم. تنسب الوحدة كل حركة بطاقة إلى المستأجر الصحيح، وتقتطع عمولة المنظّم وأي إيجار للجناح من الأصل، ثم تسوّي الباقي. والرقم التسلسلي للطرفية هو مفتاح الربط الشامل الذي يصل سطر كشف البنك بالجهاز وبتخصيصه وبالمستأجر.

كيف تستخدمها. تجمع لوحة معلومات المنظّم (/exhibition/dashboard) بين النظرة العامة لمؤشرات الأداء وتقرير التسوية في مركز قيادة واحد للقراءة فقط: مؤشرات رئيسية (إيراد العمولة، والمستحقات الدائنة للمستأجرين، والإيجار المتأخر، ومبيعات الأجهزة المطابَقة، وصافي المركز، وأعداد المستأجرين والعقود والأجهزة)، وشريط يتطلب إجراءً (إيجار متأخر، جلسات مطابقة مفتوحة، أسطر مطابقة غير مطابَقة)، وقائمة بالمستأجرين الذين يحتاجون انتباهًا، وملخص تسوية قابل للتنزيل بصيغتَي PDF وCSV وللإرسال بالبريد.

استخدمها بذكاء. تقع جميع الصفحات تحت المعارض في الشريط الجانبي على المسار /exhibition/*؛ والوحدة وحدة ويب موحّدة تُخدَّم واجهتها البرمجية على /api/v1/exhibition. تعامل مع الرقم التسلسلي على أنه مقدَّس — فهو معرّف الطرفية المطبوع على كشف البنك وعلى تقرير المستأجر؛ وإن لم يتطابقا لن تتم أي مطابقة تلقائية. ولأن الأرقام المالية في النظرة العامة ولوحة المعلومات محسوبة من نفس عرض الفروقات لكل مستأجر المستخدَم في بقية الصفحات، اعتمد لوحة المعلومات مصدرًا واحدًا للحقيقة بدل مطابقة الأرقام يدويًا.

المستأجرون والأجهزة والتخصيصات (الإعداد)

ما هي. ثلاثة كيانات إعداد. المستأجر جهة اتصال معلَّمة بالخاصية IsRenter. وجهاز الدفع طرفية بطاقات فعلية يجب أن يساوي رقمها التسلسلي معرّف الطرفية لدى البنك. والتخصيص يربط جهازًا بمستأجر خلال فترة زمنية محددة ويلتقط صورة ثابتة لنسبة العمولة السارية، بحيث لا يعيد أي تعديل لاحق على العمولة كتابة التاريخ المسجَّل.

كيف تستخدمها. تعرض صفحة المستأجرين قائمة المستأجرين مع العقد الساري وعدد الأجهزة وإجمالي الإيجار المستحق/المدفوع والرصيد؛ وتدعم البحث ونموذج إضافة سريعة (الاسم + بريد/هاتف اختياري) ينشئ جهة اتصال بالخاصية isRenter=true — كما يمكن لأي جهة اتصال قائمة أن تكون مستأجرًا. وفي صفحة الأجهزة تنشئ أو تعدّل طرفية بالرقم التسلسلي (= معرّف الطرفية، مثل POS-001) واسم مختصر ورمز بنك اختياري وموقع وملاحظات؛ وتفعّلها أو توقفها؛ أو تحذفها (حذف منطقي)، مع إمكانية البحث في القائمة بالرقم التسلسلي أو الاسم أو الموقع. وفي صفحة التخصيصات، ولكل جهاز محدد، تنشئ تخصيصًا لمستأجر بتاريخ «مخصَّص من» (وتاريخ «مخصَّص إلى» وعقد وأصل الجناح وملاحظات اختياريًا). ويُرفض تداخل التخصيصات السارية لنفس الجهاز والفترة؛ ويجب أن تكون نسبة العمولة بين 0 و100، ويجري التحقق منها والتقاطها في التخصيص ونسخها إلى كل كشف يُنشأ منه. ويمكن إنهاء تخصيص مفتوح (بلا تاريخ «مخصَّص إلى») بتحديد تاريخ انتهاء — ونافذة تواريخ التخصيص هي ما تعتمد عليه المطابقة التلقائية ومستورد ملف مبيعات المستأجرين لتحديد مالك الجهاز في تاريخ كل حركة.

عقود الأجنحة (/exhibition/contracts) تنشئ عقد إيجار مرقّمًا ببادئة EXH- لمستأجر مقابل أصل جناح بإيجار شهري ومبلغ تأمين؛ ويولّد النظام جدول الدفعات تلقائيًا (دفعة تأمين إن وُجدت، ثم دفعة لكل شهر). كما تنشئ الإضافة السريعة أصل الجناح نفسه، وتتيح لوحة الجسور ربط سيناريوهات إيجار الجناح واستخدام أجهزة الدفع بعقود رسمية.

السيناريوهات المرتبطة تخبرك عندما تنحرف. يسجّل الجسر حالة المستند الذي رُبط به، فإذا أُعيد تأريخ عقد الجناح أو تسعيره لاحقًا، تعرض البطاقة غير متزامن (Out of sync) بدل الاستمرار في الإبلاغ عن ارتباط سليم — وتعرض المصدر محذوف (Source deleted) إذا اختفى المستند تمامًا. ويعيد زر إعادة مزامنة الارتباط تأكيد الجسر مقابل المستند بوضعه الحالي. وهو يسجّل أنك راجعت التغيير، ولا يعيد عمدًا كتابة العقد المرتبط، لأنه مستند رسمي وقد يكون موقَّعًا بالفعل — عدّله من خلال العقد نفسه.

استخدمها بذكاء. اضبط الرقم التسلسلي للجهاز على نفس معرّف الطرفية الذي يطبعه البنك حرفيًا — فهذا الحقل وحده هو ما يجعل كل مطابقة تلقائية لاحقة تنجح. وأنشئ دائمًا تخصيصًا بتاريخ «مخصَّص من» قبل وصول الحركات، لأن نافذة التخصيص هي التي تحدد مالك الجهاز في كل تاريخ؛ وإعادة تخصيص جهاز في منتصف الفترة تحتاج فقط إلى تخصيص جديد بتاريخ البداية التالي. ولا تعدّل عمولة ملتقطة متوقعًا تغيّر الكشوف القديمة — فالالتقاط مقصود كي يبقى التاريخ صحيحًا.

جلسة المطابقة (الأموال المؤكَّدة من البنك)

ما هي. جلسة المطابقة دفعة من حركات البطاقات المؤكَّدة من البنك لحساب بنكي وفترة محددة. تُنشأ بحالة مسودة، وتُملأ عبر أحد ثلاثة مسارات استيراد (كل سطر هو سطر مطابقة يحمل الطرفية والتاريخ والمبلغ الإجمالي/الصافي وحالة غير مطابَق (Unmatched))، ثم تُطابَق تلقائيًا أو يدويًا وتُكتمل. والاستيراد ينقل الجلسة إلى قيد التنفيذ.

كيف تستخدمها. أنشئ جلسة بمعرّف حساب بنكي وفترة من/إلى؛ فتبدأ بحالة مسودة. وتملأ المسودة ثلاثة مسارات استيراد (كما يقبل مسارا PDF وCSV حالة «قيد التنفيذ»): استيراد التغذية البنكية (يسحب الحركات البنكية الموسومة بمعرّف جهاز للحساب والفترة)، واستيراد ملف PDF (كشف جهة الاستحواذ من Network International — يستخرج الطرفية والتاريخ والإجمالي/الصافي والعمولة وضريبة القيمة المضافة ومرجع جهة الاستحواذ ورقم البطاقة، ويضبط تاريخ كشف الجلسة)، واستيراد كشف الحساب البنكي بصيغة CSV. وعند الاستيراد يُعاد احتساب إجماليات الجلسة (عدد الحركات وإجمالي المبلغ) ويُرحَّل قيد يومية للاعتراف بالنقد تلقائيًا فقط عند الإعداد المسبق: مدين حساب البنك في دليل الحسابات (الصافي) + مدين مصروف رسوم البنك (رسوم خدمة التاجر + ضريبة القيمة المضافة، عندما يحمل الاستيراد حقول الرسوم — ملف PDF أو ملف CSV لجهة الاستحواذ) = دائن الحساب الوسيط لتسويات الأجهزة (الإجمالي)؛ أما أسطر التغذية البنكية فلا تحمل مكوّن رسوم، لذا يُحذف طرف الرسوم فيها. وإذا لم يُعدّ حساب البنك أو حسابا مقاصة التسويات ورسوم البنك في الإعدادات المحاسبية الافتراضية، يُتخطى القيد مع تحذير في السجل ويظل الاستيراد ناجحًا.

تقوم المطابقة التلقائية (تعمل على الجلسات «قيد التنفيذ» فقط) بمطابقة كل سطر غير مطابَق بمستأجر عبر الطرفية ← الرقم التسلسلي للجهاز ← التخصيص الذي تغطي نافذته الزمنية تاريخ الحركة؛ ثم تجري تمريرة ثانية بسماحية يومين (±2 يوم) لتأخر معالجة البنك. وتصبح الأسطر المطابَقة بحالة مطابَق تلقائيًا (AutoMatched) وتحمل الجهاز والمستأجر والجناح المطابق. ويمكن مطابقة الأسطر يدويًا (بإدخال معرّف جهة اتصال المستأجر ← مطابَق يدويًا (ManualMatched)، مع تحديد الجهاز بالرقم التسلسلي) أو استبعادها مع سبب اختياري (الأسطر المستبعَدة Excluded تخرج من كل الإجماليات والكشوف). ويضع زر إكمال الجلسة حالة «مكتملة» مع الطابع الزمني واسم المُكمِل؛ ولا تظهر إجراءات المطابقة التلقائية والإكمال إلا في الجلسات قيد التنفيذ، بينما تغذّي الجلسات المفتوحة (غير المكتملة وغير الملغاة) وأسطرها غير المطابَقة عدّادات «يتطلب إجراءً» في لوحة المعلومات.

استخدمها بذكاء. شغّل المطابقة التلقائية أولًا واحتفظ بالمطابقة اليدوية والاستبعاد للبقايا فقط — فالسطر غير المطابَق يعني في الغالب تخصيصًا ناقصًا أو رقمًا تسلسليًا غير مطابق، وإظهار ذلك هو الغاية. وإعادة استيراد الملف نفسه آمنة لأن الأسطر تُنقّى من التكرار، فيمكن ببساطة إعادة تشغيل استيراد انقطع. ولا تُكمل جلسة إلا بعد أن تصبح أسطرها نظيفة؛ فالجلسات المفتوحة وأسطرها غير المطابَقة هي بالضبط ما تنبّهك إليه لوحة المعلومات.

كشوف مبيعات المستأجرين + مطابقة الكشوف (جوهر العمولة)

ما هي. كشف مبيعات المستأجر هو ما يقرّ المستأجر أنه باعه، بإجماليات يومية، مع احتساب العمولة والتقاطها من التخصيص (العمولة = الإجمالي × النسبة، والصافي = الإجمالي − العمولة، وهو المستحق للمستأجر). أما مطابقة الكشف فتقارن الإجمالي المُقرّ بما ورّده البنك فعليًا لذلك الجهاز خلال الفترة، وترحّل قيد يومية التخصيص.

كيف تستخدمها. تُنشأ الكشوف يدويًا (تخصيص + فترة + إجماليات يومية) أو دفعة واحدة عبر استيراد ملف CSV لمبيعات المستأجرين؛ وتُلتقط نسبة العمولة من التخصيص عند الإنشاء بحيث لا يغيّر أي تعديل لاحق للنسبة كشفًا مسجَّلًا. ومطابقة الكشف تقارن الإجمالي المُقرّ بالإجمالي المؤكَّد من البنك لنفس الرقم التسلسلي خلال الفترة (بمطابقة أسطر المطابقة على حقل MachineSerialNumber أو TerminalId، مع تجاهل الأسطر المستبعَدة)؛ وتعيد المبلغ المُقرّ ومبلغ البنك والفرق وعدد الأسطر، وتضع الكشف بحالة مطابَق (Reconciled). وهي غير مرتبطة بالترتيب — تعمل سواء سُجّل الإقرار أو الاستيراد البنكي أولًا. وعند نجاح المطابقة مع إجمالي بنكي أكبر من صفر، يُرحَّل قيد التخصيص مرة واحدة لكل كشف (عند الإعداد المسبق وإلا يُتخطى): مدين الحساب الوسيط لتسويات الأجهزة (الإجمالي البنكي) = دائن إيراد العمولة (الإجمالي × النسبة، فقط عندما تكون النسبة الملتقطة أكبر من صفر) + دائن ذمم المستأجر الدائنة (الصافي). وبذلك يُقفل الحساب الوسيط الذي مُوّل عند الاستيراد البنكي في إيراد العمولة والذمم الدائنة للمستأجر.

أما صفحة تقرير كشف المستأجر (/exhibition/renter-statement) فهي عرض منفصل للقراءة فقط: أدخل معرّف المستأجر ونطاق التواريخ لعرض حركات أسطر المطابقة المؤكَّدة من البنك لذلك المستأجر (التاريخ والرقم التسلسلي والوصف والمبلغ وحالة المطابقة والجناح) مع الإجمالي. وتعرض تبويبة التسوية في ملف المستأجر المبيعات المُقرّة مقابل المؤكَّدة من البنك، والفرق، والعمولة، والمستحقات الدائنة، والمقاصة مقابل الإيجار، والمبالغ المصروفة، والإيجار المتأخر، وصافي الفرق، إضافة إلى زرَّي المقاصة وصرف المستحقات لكل مستأجر.

استخدمها بذكاء. طابق كل كشف مع البنك بدل الصرف اعتمادًا على إقرار المستأجر وحده — فالفرق هو أداتك لكشف الخطأ أو التلاعب. وثق بالعمولة الملتقطة: لأن النسبة تُثبَّت عند إنشاء الكشف، يمكنك تعديل نسبة المستأجر مستقبلًا دون المساس بالتاريخ. وراقب عمود الفرق في تبويبة التسوية؛ فالفجوة المستمرة بين المُقرّ والمؤكَّد من البنك تعني عادة سطر مطابقة غير مطابَق أو معرّف طرفية خاطئًا.

التسوية وصرف المستحقات (العمولة، ومقاصة الإيجار المتأخر، والتحويل)

ما هي. التسوية تصافي مبيعات أجهزة كل مستأجر المطابَقة بنكيًا مقابل عمولة المنظّم وأي إيجار جناح متأخر، ثم تصرف الباقي. والمستحق المتاح هو صافي كل كشف مطابَق ومؤكَّد من البنك مطروحًا منه ما جرت مقاصته أو صرفه فعلًا. ويُقاصّ الإيجار المتأخر بدءًا من الأقدم؛ ويُمنع الصرف ما دام هناك إيجار متأخر.

كيف تستخدمها. يحسب عرض الفروقات لكل مستأجر (وهو المصدر الواحد للحقيقة) المبيعات المُقرّة، والمبيعات المطابَقة، والفرق، والعمولة، وصافي المطابَق، والمقاصة، والمصروف، والمستحق الدائن، والإيجار المتأخر، وإجمالي الإيجار المستحق/المدفوع، وصافي الفرق، والاتجاه (ExhibitionOwesRenter أي المعرض مدين للمستأجر / RenterOwesExhibition أي المستأجر مدين للمعرض / Settled أي مُسوّى). وهو متاح لكل مستأجر على حدة ولجميع المستأجرين معًا (مرتبًا حسب القيمة المطلقة لصافي الفرق). ومقاصة الإيجار المتأخر تطبّق المستحق المطابَق المتاح للمستأجر على دفعات إيجار عقده EXH- المتأخرة، فتسدد الإيجار من الأقدم وتسحب من الكشوف من الأقدم بأقل القيمتين: المستحق المتاح أو الإيجار المتأخر؛ والكشوف المسحوبة بالكامل تصبح «مُسوّاة». وترحّل القيد: مدين ذمم المستأجر الدائنة / دائن إيراد إيجار الأجنحة (على الأساس النقدي، وعند الإعداد المسبق وإلا يُتخطى)، وتعيد المبالغ قبل وبعد، والدفعات المتأثرة، والكشوف المسحوبة، ورقم قيد اليومية.

تحويل المستحقات يصرف للمستأجر صافيه المطابَق المتاح. ويُمنع (يعيد blocked=true ولا يحوّل شيئًا) إذا بقي أي إيجار جناح متأخر؛ أما الإيجار المستقبلي فلا يمنع الصرف. وعند النجاح يسحب من الكشوف بدءًا من الأقدم، ويضع الكشوف المسحوبة بالكامل بحالة «مُسوّاة»، ويرحّل: مدين ذمم المستأجر الدائنة / دائن البنك (عند الإعداد المسبق وإلا يُتخطى). ولا يُفعَّل زر المقاصة إلا عندما يكون الإيجار المتأخر > 0 والمستحق > 0؛ ولا يُفعَّل زر الصرف إلا عندما يكون المستحق > 0 والإيجار المتأخر = 0 — تجسيدًا لقاعدة المالك بأن الإيجار يجب أن يُسوّى قبل أي صرف. ويمكن تسجيل دفعات الإيجار يدويًا مقابل دفعة مجدولة في العقد، كما يحوّل إجراء فحص المتأخرات دفعات EXH- المعلّقة التي فات موعدها إلى «متأخرة».

استخدمها بذكاء. شغّل مسح «فحص المتأخرات» قبل تسوية أي دفعة كي يكون رقم المتأخرات (ومنع الصرف) محدّثًا. ودع منطق «الأقدم أولًا» يقوم بالعمل — فالمقاصة تسدد أقدم إيجار وتسحب من أقدم الكشوف تلقائيًا، ما يبقي مسار التدقيق مرتبًا. ومنع الصرف المتعمّد أثناء وجود إيجار متأخر ميزة لا خلل: سوِّ الإيجار (بمقاصة أو دفعة يدوية) وسيُفعَّل زر الصرف من تلقاء نفسه.

الاستيراد — PDF والتغذية البنكية وملفَّا CSV

ما هو. تدخل الأموال والمطالبات إلى الوحدة عبر أربعة مسارات. إلى الجلسة: التغذية البنكية (الحركات البنكية)، وملف PDF من Network International، وملف CSV لكشف الحساب البنكي — وكلها تتحول إلى أسطر مطابقة. وبشكل منفصل، يتحول ملف CSV لمبيعات المستأجرين إلى كشوف مبيعات المستأجرين. وحد ملفات PDF وCSV هو 10 ميغابايت مع التحقق من امتداد الملف.

كيف تستخدمه. استيراد التغذية البنكية يسحب الحركات البنكية القائمة للحساب البنكي للجلسة ضمن الفترة والتي تحمل معرّف جهاز، مع منع التكرار حسب معرّف الحركة البنكية؛ ويعمل على المسودة فقط. واستيراد PDF يحلّل كشف جهة الاستحواذ من Network International إلى أسطر مطابقة (الطرفية والتاريخ والإجمالي والصافي والعمولة وضريبة القيمة المضافة ومرجع جهة الاستحواذ ورقم البطاقة) ويضبط تاريخ كشف الجلسة؛ ومنع التكرار فيه حسب مرجع جهة الاستحواذ؛ ويعمل على المسودة أو «قيد التنفيذ». واستيراد كشف الحساب البنكي بصيغة CSV يحوّل ملف البنك (انظر صيغ ملفات CSV) إلى أسطر مطابقة؛ مع منع التكرار مقابل الأسطر المستوردة سابقًا بحيث تكون إعادة استيراد الملف نفسه آمنة (وهو ما يمنع أيضًا ترحيل قيد النقد مرتين)؛ ويعمل على المسودة أو «قيد التنفيذ».

استيراد ملف CSV لمبيعات المستأجرين يجمّع الصفوف حسب الطرفية، ويعثر على الجهاز بالرقم التسلسلي، ويضع كل صف تحت التخصيص الذي تغطيه نافذته الزمنية (بحيث ينتج عن جهاز أُعيد تخصيصه في منتصف الملف كشف لكل مستأجر)، ويجمع القيم لكل يوم، وينشئ كشف مبيعات واحدًا لكل (تخصيص، فترة) بالعمولة المأخوذة من التخصيص. ويبلّغ التأكيد بعدد الكشوف المُنشأة، والصفوف المقروءة، والصفوف التالفة المتخطّاة، والكشوف المكررة المتخطّاة، والطرفيات غير المطابَقة (فيظهر فورًا أي جهاز نسيت تخصيصه). ويتشارك مستوردا CSV محلّلًا واحدًا مرنًا يعتمد على صف العناوين (أسماء أعمدة غير حساسة لحالة الأحرف والمسافات، وحقول بين علامات اقتباس، مع تحمّل علامة ترتيب البايت UTF-8 BOM).

راجع قبل أن تستورد (PDF وملف CSV البنكي). اختيار ملف الكشف لم يعد يستورده فورًا — بل يعرض لك ما سيفعله الاستيراد، ولا يُكتب شيء حتى تؤكد. وتذكر لوحة المراجعة الصيغة التي جرى التعرف عليها، وتاريخ الكشف، وعدد الصفوف المقروءة مقابل ما يعلنه الكشف نفسه، وكم صفًا جديد مقابل ما استُورد سابقًا، والمبالغ التي تضيفها الصفوف الجديدة، وتفصيلًا لكل طرفية، وعيّنة من الصفوف. وبالنسبة لملف CSV تعرض أيضًا كل صف تعذّر قراءته، مع رقم السطر والمشكلة والخلية المسببة. وإذا كانت كل الصفوف مستوردة سلفًا، يُعطَّل زر التأكيد ويُبلغك بذلك. وهذا مهم لأن الاستيراد يرحّل قيد النقد فورًا: فكشف لفترة خاطئة، أو كشف استوردته الأسبوع الماضي، يُحلَّل بلا أخطاء ويتطابق مع إجمالياته الخاصة — ولا يكتشفه إلا إنسان يقارن الفترة والطرفيات.

التوافر: وحدة المعارض إضافة من السوق تخضع للتفعيل. وعندما تكون غير مفعّلة، يُحجب عنصر القائمة وتُحوَّل المسارات إلى السوق — وهذا سلوك متوقع. وقد التُقطت لقطات الشاشة أثناء تفعيل الإضافة ويُحتفظ بها كمرجع للميزة.

استخدمه بذكاء. ضمّن دائمًا عمود المرجع (Reference) في ملف CSV البنكي — فهو مفتاح منع التكرار الدقيق، وبه تبقى عمليات إعادة الاستيراد نظيفة ولا يُرحَّل قيد النقد مرتين. واقرأ تأكيد استيراد المستأجرين: فعدد الصفوف التالفة المتخطّاة والطرفيات غير المطابَقة هما الطريقة التي تعلن بها البيانات السيئة والتخصيصات الناقصة عن نفسها. وأبقِ الملفات دون 10 ميغابايت وقسّم فترة الكشف الكبيرة بدل فرض رفع ملف ضخم واحد.

صيغ استيراد ملفات CSV

ما هي. يستخدم الاستيرادان محلّلًا مشتركًا واحدًا (ExhibitionCsvImportParser): صف العناوين إلزامي؛ وأسماء الأعمدة غير حساسة لحالة الأحرف والمسافات (تُطبَّع إلى حروف وأرقام فقط)؛ وتُعالَج الحقول بين علامات اقتباس وعلامة ترتيب البايت UTF-8 BOM؛ ويُفترض أن المدخلات بترميز UTF-8.

ملف CSV لكشف الحساب البنكي (Reconcile → Import Bank CSV، نقطة النهاية POST sessions/{id}/import-csv). الأعمدة المطلوبة: Terminal (المرادفات: Terminal ID, Machine, Machine Serial, Serial, Serial Number) — ويجب أن يساوي الرقم التسلسلي للجهاز؛ وDate (المرادفات: Transaction Date, Txn Date, Value Date, Posting Date)؛ وAmount (المرادفات: Gross, Gross Amount). والاختيارية: Net (المرادف Net Amount) — ويُستخدم عندما تطابق الجلسة على الصافي؛ وReference (المرادفات: Ref, Acq Reference, Transaction ID, Txn ID) — اختياري لكنه موصى به لأنه مفتاح منع التكرار الدقيق. وإذا غاب عمود Terminal أو Date أو Amount/Gross، يتوقف الاستيراد ويخبرك بالضبط بالعمود الذي لم يجده، وبالأعمدة الموجودة فعلًا في ملفك، وبالأسماء التي يقبلها — فملف تصدير يسمّي العمود “Device” أو “Txn Amount” تحلّه إعادة تسمية سريعة بدل التخمين.

ملف CSV لمبيعات المستأجرين (Reconcile → Import Renter Sales CSV من شريط الأدوات، نقطة النهاية POST renter-statements/import-csv). نفس المحلّل والمرادفات؛ وعمليًا: Terminal وDate وAmount. وتُجمَّع الصفوف حسب الطرفية، وتوضع تحت التخصيص الذي تغطي نافذته كل صف، وتُجمع لكل يوم في كشف واحد لكل (تخصيص، فترة).

صيغ التواريخ (تُجرَّب بهذا الترتيب وتُحلَّل بصيغة ثابتة ومطابقة تمامًا): yyyy-MM-dd (ISO، وهي المفضّلة)، yyyy/MM/dd، dd/MM/yyyy، dd-MM-yyyy، yyyy-MM-ddTHH:mm:ss، yyyy-MM-dd HH:mm:ss، dd/MM/yyyy HH:mm:ss. أما الصيغة الأمريكية الملتبسة M/d/yyyy فهي غير مقبولة عمدًا كي لا تُحلَّل تواريخ الشرطة المائلة خطأً بصمت. ويُهمَل وقت اليوم (يُخزَّن التاريخ فقط). والمبالغ أرقام عشرية بثقافة ثابتة، وتُؤخذ بقيمتها المطلقة (وجود إشارة سالبة في البداية مقبول) — فالمردودات وعمليات الاسترداد تُؤخذ بقيمتها المطلقة ولا تُنمذَج كعكوسات.

الصفوف التالفة. أي صف بيانات بطرفية فارغة أو تاريخ غير قابل للتحليل أو مبلغ غير قابل للقراءة يُتخطّى بدل إفشال الملف كله — وصار كل صف منها يُبلَّغ عنه على حدة: رقم السطر (محسوبًا مع صف العناوين ليطابق جدولك)، وما الخطأ (لا توجد طرفية / صيغة التاريخ غير معروفة / المبلغ غير قابل للقراءة)، والخلية المسببة. وتعرضها لوحة مراجعة ملف CSV البنكي قبل الاستيراد، فيُصلَح ملف فيه بضعة صفوف سيئة في دقيقة واحدة بدل رفضه بالكامل أو فقدان صفوف بصمت.

منع التكرار / إعادة استيراد آمنة. في ملف CSV البنكي: السطر الذي يحمل مرجعًا يُنقّى بناءً على ذلك المرجع (دون حساسية لحالة الأحرف، بالبادئة r:)؛ والسطر بلا مرجع يُنقّى بمفتاح طبيعي terminal|yyyyMMdd|gross|net (بالبادئة n:). ويتم المنع مقابل الأسطر المحفوظة سابقًا فقط، لذا تُحفظ عمليتا بيع متطابقتان فعلًا وبلا مرجع داخل ملف واحد؛ وإعادة استيراد الملف نفسه تتخطى المكررات (ومن ثم لا تُرحّل قيد النقد مرتين). وفي ملف CSV المستأجرين: تُتخطى الكشوف القائمة بنفس (تخصيص الجهاز، الفترة من، الفترة إلى) عند إعادة الاستيراد (وكذلك المكررات داخل الملف)، فتكون إعادة استيراد تقرير المستأجر نفسه آمنة.

فترة الكشف = أدنى وأقصى تاريخ حركة موجود في الملف (لكل تخصيص في ملف المستأجرين).

القيود: المبيعات الموجبة فقط (لا نمذجة للقيم السالبة أو العكوسات)؛ وترميز UTF-8 حصرًا؛ ويُسقط استيراد المستأجرين أي صف لا يغطي تاريخه أي تخصيص، ويبلّغ عن الطرفيات التي لا جهاز لها أو لا تخصيص يغطيها بوصفها “غير مطابَقة”.

التقارير والتصدير

ما هي. أربعة أسطح تقارير. تقرير التسوية والعمولة (صف لكل مستأجر + إجماليات عامة، مع نطاق تواريخ اختياري) قابل للتنزيل بصيغتَي CSV وPDF وللإرسال بالبريد. وكشف حساب المستأجر ملف PDF يمكن تنزيله أو إرساله بالبريد. أما تقرير كشف المستأجر والملخص اليومي للأجهزة فجدولان يُعرضان على الشاشة.

كيف تستخدمها. يعرض تقرير التسوية والعمولة صفوف الفروقات لكل مستأجر إضافة إلى إجماليات مجموع الأعمدة مع نطاق تواريخ اختياري (?from&to)؛ وهو متاح بصيغة JSON، وبصيغة CSV وفق معيار RFC-4180 (مع علامة UTF-8 BOM ليقرأ Excel الأسماء غير اللاتينية)، وبملف PDF قابل للطباعة (يُولَّد على الخادم عبر QuestPDF)، ويمكن الوصول إليه من لوحة التسويات في صفحة المستأجرين ومن لوحة المعلومات. ويعرض الملخص اليومي للأجهزة (/exhibition/machine-report)، لكل جهاز في كل يوم، عدد الحركات وإجماليات الإجمالي/الصافي/العمولة خلال نطاق تواريخ، مع تحديد المستأجر المخصَّص عبر التخصيص الذي يغطي كل يوم؛ ويتضمن إجماليات ملخصة (تاريخ آخر حركة، وإجمالي عدد الحركات، والإجمالي، والصافي) وتصديرًا إلى CSV من جانب المتصفح. ويسرد تقرير كشف المستأجر (/exhibition/renter-statement) حركات أسطر المطابقة المؤكَّدة من البنك لمستأجر خلال نطاق تواريخ مع إجمالي (باستثناء الأسطر المستبعَدة).

البريد الإلكتروني. يمكن إرسال ملف PDF لكشف حساب المستأجر إلى بريده المسجَّل (أو إلى بريد بديل؛ ويظهر خطأ إن لم يتوفر أيٌّ منهما)، كما يمكن إرسال ملف PDF لتقرير التسوية إلى مستلم محدد (المنظّم أو المحاسب)؛ وكلاهما يُدرَج في طابور الإرسال عبر خدمة البريد الأساسية ويعيد رقم سجل البريد. ويجمع ملف PDF لكشف حساب المستأجر (المنزَّل من ملف المستأجر) بين عقد الجناح وجدول الإيجار وحركات الأجهزة ومركز التسوية.

استخدمها بذكاء. صدّر تقرير التسوية والعمولة بصيغة CSV للتدقيق في جدول بيانات، وبصيغة PDF للمستأجر أو المحاسب — فكلاهما يأتي من عرض الفروقات نفسه، ولذلك يتطابقان دائمًا. وأرسل ملف PDF لكشف الحساب مباشرة من ملف المستأجر بدل إعادة إدخال الأرقام. واستخدم الملخص اليومي للأجهزة لرصد طرفية خاملة (عبر تاريخ آخر حركة) قبل أن تتحول إلى مفاجأة في المطابقة.

الصلاحيات

ما هي. كل إجراء في وحدة المعارض محكوم بصلاحية دقيقة، بحيث يملك موظف استقبال المستأجرين والمحاسب والمنظّم كلٌّ نطاقه المطلوب بالضبط.

• Exhibition.Read — عرض المستأجرين، والنظرة العامة/لوحة المعلومات، وملفات المستأجرين، وفروقات المستأجرين (مستأجر واحد + الجميع).
• Exhibition.Recon.Read — عرض الأجهزة، وتخصيصات الأجهزة، وجلسات وأسطر المطابقة، والملخص اليومي للأجهزة.
• Exhibition.Recon.Manage — إنشاء/تعديل/حذف الأجهزة، وإنشاء/إنهاء التخصيصات، وإنشاء الجلسات، والاستيراد (تغذية بنكية / PDF / CSV بنكي)، والمطابقة التلقائية، وإكمال الجلسة، ومطابقة الأسطر يدويًا أو استبعادها.
• Exhibition.Statement.Read — تقرير كشف المستأجر، وكشوف مبيعات المستأجرين (قائمة/تفصيل)، وتقرير التسوية (JSON/CSV/PDF)، وملف PDF لكشف المستأجر.
• Exhibition.Statement.Manage — إنشاء كشوف مبيعات المستأجرين، ومطابقة كشف مبيعات مستأجر، واستيراد ملف CSV لمبيعات المستأجرين، وتسجيل دفعة إيجار، وفحص الدفعات المتأخرة.
• Exhibition.Statement.Email — إرسال ملف PDF لكشف الحساب إلى المستأجر بالبريد؛ وإرسال ملف PDF لتقرير التسوية والعمولة.
• Exhibition.Payout.Run — مقاصة مستحق المستأجر مقابل الإيجار المتأخر؛ وتحويل مستحقات المستأجر.
• Exhibition.Contract.Read — عرض عقود الأجنحة (قائمة/تفصيل)، وسيناريوهات العقود، وجسور العقود.
• Exhibition.Contract.Manage — إنشاء عقود الأجنحة؛ وربط سيناريو عقد.

استخدمها بذكاء. أبقِ نطاقات تحريك الأموال (Exhibition.Payout.Run وExhibition.Statement.Email) ضيقة — فموظفو الاستقبال يحتاجون عادة إلى صلاحية القراءة مع نطاقَي إدارة المطابقة والكشوف لإدخال البيانات فقط، بينما تبقى المقاصة والصرف والبريد الصادر لدى المنظّم أو المحاسب.

الصفحات على بيئة التطوير

ما هي. يقع سطح وحدة المعارض بالكامل تحت /exhibition/*؛ وكل مسار محكوم بالصلاحية المناسبة أعلاه.

• /exhibition (الفهرس) — صفحة هبوط/مُشغّل الوحدة (مكوّن جذر المعارض المعروض عند جذر القسم).
• /exhibition/dashboard — لوحة معلومات المنظّم: بطاقات المؤشرات (العمولة، والمستحقات، والإيجار المتأخر، والمبيعات المطابَقة، وصافي المركز، والأعداد)، وشريط «يتطلب إجراءً» (إيجار متأخر / جلسات مفتوحة / أسطر غير مطابَقة)، وقائمة المستأجرين الذين يحتاجون انتباهًا، وملخص تسوية مع تصدير PDF/CSV وإرسال بالبريد.
• /exhibition/renters — قائمة المستأجرين (إضافة سريعة، وبحث، والإيجار المستحق/المدفوع/الرصيد، والعقد وعدد الأجهزة)، ولوحة التسويات (صفوف الفروقات لكل مستأجر + الإجماليات، ومرشّح نطاق التواريخ، وتصدير تقرير التسوية بصيغة PDF/CSV)، وزر فحص المتأخرات.
• /exhibition/renters/:id — ملف المستأجر: مؤشرات رصيد الإيجار والذمم المدينة والدائنة، وتبويبات العقد، والدفعات (تسجيل دفعة إيجار)، والأجهزة، والحركات، وتبويبة التسوية (المُقرّ مقابل المؤكَّد من البنك، والعمولة، والمستحق، والمقاصة، والصرف) إضافة إلى تنزيل/إرسال ملف PDF للكشف.
• /exhibition/contracts — عقود الأجنحة: إضافة سريعة لأصل الجناح، وإنشاء عقد الجناح (جدول إيجار تلقائي)، وقائمة بملخص الدفعات، ولوحة ربط جسور العقود (سيناريوهات إيجار الجناح واستخدام أجهزة الدفع).
• /exhibition/machines — أجهزة الدفع (طرفيات البطاقات): إنشاء/تعديل، وضبط الرقم التسلسلي = معرّف الطرفية مع الاسم/رمز البنك/الموقع، وتفعيل/إيقاف، وحذف، وبحث.
• /exhibition/assignments — تخصيصات الأجهزة: تخصيص كل جهاز لمستأجر (مع عقد/جناح اختياري)، ونافذة «مخصَّص من/إلى»، والتقاط العمولة، وإنهاء التخصيص.
• /exhibition/reconcile — جلسات المطابقة: إنشاء جلسة، واستيراد الأسطر البنكية (تغذية بنكية / PDF / CSV بنكي)، واستيراد ملف CSV لمبيعات المستأجرين، والمطابقة التلقائية، والمطابقة اليدوية أو استبعاد الأسطر، وإكمال الجلسة.
• /exhibition/renter-statement — تقرير كشف المستأجر: حركات الأجهزة المؤكَّدة من البنك لمستأجر خلال نطاق تواريخ، مع الإجماليات.
• /exhibition/machine-report — تقرير الملخص اليومي للأجهزة: عدد الحركات لكل جهاز في كل يوم وإجماليات الإجمالي/الصافي/العمولة خلال نطاق تواريخ، مع تصدير CSV من جانب المتصفح.