الانتقال إلى المحتوى
كل الأعمال

دراسة حالة ٠١تطبيق لإدارة الأعمال

نظام إدارة العمولات.

تطبيق ويب متعدد المتاجر يسجّل طلبات الزبائن، ويحسب عمولات الموظفين ومكافآتهم تلقائيًا، ويمنح المالك صرف المستحقات ومتابعة الديون وتقارير مالية متطابقة.

الدور
المطوّر الوحيد — full stack
المدة
تشرين الأول ٢٠٢٦ – الآن
الحالة
منشورالإصدار الأول يعمل على خادم خاص، وما زالت فحوصات القبول والإطلاق جارية.
المنصة
تطبيق ويب قابل للتثبيت (PWA) للهاتف والحاسوب
اللغات
العربية والكردية السورانية والإنجليزية (RTL وLTR)
الشيفرة المصدرية
مستودع خاص
لوحة تحكم المالك مع بطاقات ملخّص للطلبات والمبيعات ومستحقات الموظفين والمصروفات والإيرادات
لوحة تحكم المالك على الهاتف، مع شريط تنقّل سفلي وزر «طلب جديد» في المنتصف
شكل ٠١لوحة تحكم المالك: الطلبات والمبيعات ومستحقات الموظفين والمصروفات والإيرادات للأسبوع أو الشهر المحدد، مع العناصر التي تنتظر المراجعة.

٠١

نظرة عامة

نظام إدارة العمولات تطبيق ويب full‑stack صمّمته وبنيته لنشاط تجاري في قطاع التجزئة يمتلك عدة متاجر. يسجّل الموظفون الطلبات من هواتفهم، ويحوّل النظام الطلبات المؤكَّدة إلى عمولات ومكافآت أسبوعية وشهرية ودفعات مستحقات وتقارير — ويمكن تتبّع كل رقم إلى السجلات التي يستند إليها.

يعمل كتطبيق ويب قابل للتثبيت على الهاتف والحاسوب، بالعربية والكردية السورانية والإنجليزية، مع واجهات من اليمين إلى اليسار للعربية والكردية.

المشكلة

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

الحل

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

٠٢

أبرز الميزات

  • إدخال سريع للطلبات

    يسجّل الموظفون الطلب من هواتفهم — المصدر والزبون والمبلغ وعدد القطع — وينقلونه عبر مراحل التجهيز والجاهزية والشحن والتسليم والإنجاز. ويشمل البحث أرقام الهواتف وأرقام الطلبات وأسماء الزبائن.

  • عمولة تلقائية

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

  • فترات أسبوعية وشهرية

    تُغلق الأسابيع (من السبت إلى الجمعة) والأشهر كلٌّ على حدة بعد مهلة ثلاثة أيام. وعند إغلاق الفترة تُثبَّت مكافآتها ولا تتغيّر أبدًا.

  • قوائم مراجعة المالك

    تتجمّع طلبات الإلغاء، والطلبات التي تتجاوز حدّ المكافأة، والحالات الاستثنائية الأخرى في قوائم مراجعة، حتى لا يؤخّر شيءٌ إغلاقَ الفترة دون أن ينتبه إليه أحد.

  • صرف المستحقات ومتابعة الديون

    يُعدّ النظام دفعات المستحقات، ويعتمدها المالك ويسجّل المبلغ النقدي المدفوع فعلًا. ويُحتفظ بما يدين به العمل للموظف وبما يدين به الموظف كرصيدين منفصلين.

  • المتاجر والموظفون والصلاحيات

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

  • تقارير متطابقة

    عرض شهري للأرباح والنقد يفتح فيه كل رقم السجلات التي يستند إليها، مع تصدير CSV وتنسيق جاهز للطباعة.

  • سجلّ تدقيق كامل

    يُسجَّل كل تغيير مع اسم من أجراه والقيم قبل التغيير وبعده.

  • ثلاث لغات واتجاهان

    العربية والكردية السورانية والإنجليزية بواجهات من اليمين إلى اليسار. ويُثبَّت على أندرويد كتطبيق ويب، مع تنبيهات push عندما تنتظر المراجعاتُ المالك.

٠٣

الواجهة

شاشة الطلبات مع حقل بحث وفلاتر للحالة والفترة وبطاقة طلب
شكل ٠٢الطلبات: البحث برقم الهاتف أو رقم الطلب أو اسم الزبون، والتصفية حسب الحالة والفترة.
قائمة فترات العمولة الأسبوعية مع حالتها والطلبات المؤهَّلة ومكافآتها
شكل ٠٣فترات العمولة: تُغلق الفترات الأسبوعية والشهرية تلقائيًا بعد مهلة ثلاثة أيام.
شاشة الموظفين مع أعضاء المتجر ونموذج صلاحيات لإجراءات الطلبات ومراحل العمل
شكل ٠٤الموظفون: عضوية لكل متجر مع صلاحيات دقيقة لإجراءات الطلبات ومراحل العمل.
تقرير شهري بعمودَي الأرباح والنقد، مع اختيار الفترة وزرَّي التصدير إلى CSV والطباعة
شكل ٠٥التقرير الشهري: عرض الأرباح والنقد جنبًا إلى جنب، مع التصدير إلى CSV وتنسيق للطباعة.
قيود سجلّ التدقيق تعرض إجراءات مثل إغلاق فترة وتحديث ملف شخصي مع أوقاتها
شكل ٠٦سجلّ التدقيق: يُسجَّل كل تغيير مع اسم من أجراه والقيم قبله وبعده.
شاشة الحساب مع بيانات تسجيل الدخول ونموذج تغيير كلمة المرور والتحقق بخطوتين مفعَّلًا
شكل ٠٧أمان الحساب: تغيير كلمة المرور والتحقق بخطوتين عبر تطبيق مصادقة ورموز استرداد.
لوحة تحكم المالك على الهاتف، مع شريط تنقّل سفلي وزر «طلب جديد» في المنتصف
شكل ٠٨الجوّال: لوحة التحكم نفسها مهيّأة للهاتف، مع شريط تنقّل سفلي وإجراء سريع لإضافة «طلب جديد».
قائمة «المزيد» على الهاتف تعرض الأقسام الثانوية وزر تسجيل الخروج
شكل ٠٩التنقّل على الجوّال: الأقسام الثانوية تحت «المزيد» ليبقى الشريط السفلي مركّزًا.

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

٠٤

أبرز الجوانب التقنية

  1. ٠١

    المال لا يُخزَّن أبدًا كعدد عشري

    تُحسب المبالغ بالدينار العراقي الصحيح داخل PostgreSQL بنوع bigint وتُرسَل كنصوص لأعداد صحيحة، فلا تمسّ أرقام JavaScript المبالغَ المعتمدة أبدًا. كما تمنع قواعد lint استخدام parseFloat.

  2. ٠٢

    سجلّ مالي لا يقبل إلا الإضافة

    تحمي مُشغِّلات (triggers) في قاعدة البيانات ٢٧ جدولًا للدفاتر والسجلّات من التعديل والحذف. وتُصحَّح الأخطاء بقيود عكسية صريحة، لذا يمكن إعادة احتساب أي مجموع من سجلّاته.

  3. ٠٣

    عزل المتاجر مفروض مرتين

    كل فحص يجري على الخادم، ثم تفرض ميزة row‑level security في PostgreSQL مع مفاتيح أجنبية مركّبة حدودَ المتجر مرة أخرى داخل قاعدة البيانات. ويتصل الـ API بدور لا يستطيع تجاوز هذه الحدود ولا حذف الصفوف، ويرفض العمل إذا أُعطي دورًا بصلاحيات أوسع.

  4. ٠٤

    عقد واحد للواجهة والخادم

    توجد مخططات الطلبات والاستجابات في حزمة Zod مشتركة يستخدمها الـ API وواجهة الويب معًا، وترفض المخططات الصارمة أي حقل لا يُسمح لدورٍ ما بإرساله.

  5. ٠٥

    مُختبَر على قاعدة بيانات حقيقية

    تعمل ٨٩ ملفّ اختبار للـ API على PostgreSQL 18، كل ملف على نسخة مستقلة من قاعدة بيانات نموذجية مُهيّأة، إلى جانب اختبارات قائمة على الخصائص (property‑based) بـ fast‑check واختبارات متصفّح بـ Playwright بمقاسَي الهاتف والحاسوب.

  6. ٠٦

    نشر قابل للتكرار

    يشغّل GitHub Actions فحوصات lint والأنواع والاختبارات والبناء والاختبارات الشاملة، ثم يبني صور Docker. وتقدّم صورة واحدة الـ API وواجهة الويب خلف Caddy، مع نسخ احتياطية مشفّرة وعمليات استعادة مُجرَّبة.

  7. ٠٧

    أمان متعدد الطبقات

    تجزئة كلمات المرور بـ Argon2، والتحقق بخطوتين مع رموز الاسترداد، والحماية من CSRF، وتحديد معدّل الطلبات، وسياسة Content Security Policy صارمة، وإعادة التحقق من الهوية قبل الإجراءات الحساسة.

٠٥

التقنيات

الواجهة الأمامية
  • React
  • TypeScript
  • Vite
  • Tailwind CSS
  • Radix UI
  • i18next
الخادم
  • Node.js
  • Fastify
  • Zod
قاعدة البيانات
  • PostgreSQL
  • Kysely
الأمان
  • Argon2
  • TOTP two‑step verification
الاختبار
  • Vitest
  • fast-check
  • Playwright
  • Testing Library
  • ESLint
النشر
  • Docker
  • GitHub Actions
  • Caddy
  • AWS Lightsail

٠٦

مساهمتي

المطوّر الوحيد — full stack

  • عملتُ مع صاحب العمل على تحويل المتطلبات إلى خطة مكتوبة للنظام: قواعد العمل، وأمثلة مالية محسوبة، وسجلّ للقرارات.
  • صمّمتُ نموذج البيانات في PostgreSQL وكتبتُ ٣٤ ملف ترحيل (migration) بلغة SQL، منها سياسات row‑level security ومُشغِّلات تمنع التعديل والحذف.
  • بنيتُ الـ API باستخدام Fastify: المصادقة والطلبات والمستحقات وصرف الدفعات والديون والتقارير والمهام المجدولة لإغلاق الفترات.
  • صمّمتُ وبنيتُ واجهة React للمالك والموظفين — تبدأ بالجوّال، وتراعي الكتابة من اليمين إلى اليسار، ومتاحة بثلاث لغات.
  • كتبتُ مجموعات الاختبارات الآلية وأعددتُ التكامل المستمر (continuous integration).
  • جهّزتُ النشر المعتمد على Docker والنسخ الاحتياطي وأدلّة التشغيل.

٠٧

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

  • الفترات المغلقة تبقى مغلقة

    تُثبَّت المكافآت عند إغلاق الفترة. وبدلًا من إعادة فتح السجلّ، تُقيَّد التصحيحات اللاحقة كتسويات ظاهرة في الفترة الحالية، فلا تتغيّر النتائج السابقة بصمت أبدًا.

  • القواعد الحساسة تُطلَق وهي معطّلة

    قواعد استرداد الديون من الأجور مُنفَّذة ومُختبَرة، لكنها خلف مفاتيح ميزات (feature flags) معطّلة افتراضيًا، ولا تسمح بيئة الإنتاج بتفعيلها دون مراجعة قانونية مسجَّلة.

  • القرارات مكتوبة

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

هل ترغب في العمل معًا؟

أنا منفتح على فرص جديدة. حدّثني عن مشروعك أو فريقك، وسأردّ عليك.