ملخص المطور — OneTwo v3

كل ما تحتاج معرفته لبناء الخلفية (.NET) لمنصة OneTwo لحجز الملاعب الرياضية.

ما هو OneTwo؟

OneTwo هو مشغّل مباشر للملاعب الرياضية في القصيم، المملكة العربية السعودية. نمتلك ونشغّل أكثر من 50 ملعب كرة قدم وكرة طائرة وبادل عبر أكثر من 15 موقعًا. نحن لسنا سوقًا إلكترونيًا — نحن نجمع جميع إيرادات الحجوزات مباشرة.

~60
حجز / يوم
الهدف: 325/يوم
507
عميل نشط
الهدف: 2,500
212K
ريال / شهر
الهدف: 1,060K
50+
ملعب
الهدف: 250

لماذا إعادة البناء؟

النظام الحالي (PocketBase + SQLite + Go + Vue 2) يعاني من مشاكل حرجة تمنع النمو:

المشكلة الأثر
58.3% من الحجوزات بدون سعر لا يمكن تتبع الإيرادات الفعلية — أكثر من نصف الحجوزات بدون سعر مسجل
34.8% عالقة في حالة قديمة الجلسات المؤكدة تظل "قادمة" لأسابيع بعد انتهائها، بدون تقدم تلقائي
حجوزات تختفي بدون أثر الشكوى الأولى للعملاء. لا يوجد سجل تدقيق للتحقيق فيما حدث
إمكانية الحجز المزدوج الفحوصات على مستوى التطبيق فقط، يتم تجاوزها من مولّد العقود — 4 حوادث تلف بيانات
عنق زجاجة الكاتب الواحد في SQLite لا يمكن التوسع بعد 60 حجز/يوم الحالية؛ يمنع هدف النمو 5 أضعاف
تحميل صفحة المشرف أكثر من 3 ثوانٍ يسبب أكثر من 54 نقرة غاضبة/يوم من مديري الملاعب والمشرفين

ما الذي ستبنيه

REST API موحّد (monolith-first) يخدم ثلاثة تطبيقات عميلة:

لوحة تحكم المشرف (ويب)

يستخدمها المشرفون والتنفيذيون. صفحات ويب مُقدّمة من الخادم. مصادقة بالجلسات/الكوكيز.

تطبيق مدير الملعب

تطبيق Flutter للموظفين الميدانيين. جدول مُخزّن مؤقتًا، إنشاء حجز سريع. مصادقة JWT.

تطبيق العميل

تطبيق Flutter للعملاء. تصفح الملاعب، حجز ذاتي. مصادقة JWT.

مبدأ أساسي: جميع العملاء الثلاثة يتشاركون طبقة خدمات واحدة لضمان اتساق منطق الأعمال. كلٌّ من وحدات تحكم الويب للمشرف ووحدات تحكم API للموبايل تستدعي نفس الخدمات الأساسية. لا تكرر أبدًا منطق الحجز عبر وحدات التحكم.

المكدس التقني

الخلفية مبنية على .NET 10 مع EF Core وSQL Server. المشروع (OneTwoApi) يحتوي بالفعل على 16 وحدة تحكم، و47 نموذجًا، وترحيلات EF Core جاهزة.

الجانب المتطلب ملاحظات
إطار العمل .NET 10 (ASP.NET Core) REST API مبني على وحدات تحكم مع خاصية [ApiController]
قاعدة البيانات SQL Server 2022 EF Core 10.0.3 مع Microsoft.EntityFrameworkCore.SqlServer
ORM Entity Framework Core ترحيلات code-first، التعدادات كنصوص عبر HasConversion<string>()
قائمة المهام Hangfire أو hosted services 5 مهام مجدولة: تنظيف الحجز المؤقت، إكمال تلقائي، إلغاء تلقائي، تذكيرات، توليد العقود
المصادقة (ويب) Session / Cookie للوحة تحكم المشرف
المصادقة (موبايل) JWT مهلة عدم نشاط 24 ساعة، آلية تحديث
صيغة الـ API JSON:API معيار لنقاط النهاية الموبايلية؛ ترقيم صفحات، تصفية، ترتيب، تضمينات
WhatsApp WAHA + Twilio WAHA مستضاف ذاتيًا كأساسي، Twilio كاحتياطي تلقائي
التخزين المؤقت / الطوابير Redis طوابير المهام والتخزين المؤقت
تخزين الملفات S3-compatible MinIO في بيئة التطوير، AWS S3 في الإنتاج
التحليلات PostHog SDK من جهة الخادم لإرسال الأحداث المخصصة (أكثر من 80 حدثًا)

المتطلبات غير الوظيفية

المتطلب الهدف السياق
زمن استجابة الـ API < 200ms للقراءة، < 500ms للكتابة الإصدار الحالي يعاني من تأخير تفاعل 285ms (ضعيف)
تحميل صفحة المشرف < ثانية واحدة الإصدار الحالي يأخذ أكثر من 3 ثوانٍ مع 100+ حجز
سعة الحجوزات اليومية 325/يوم 5 أضعاف الحمل الحالي (60/يوم)
وقت التشغيل 99.5% ~3.6 ساعة/شهر توقف مسموح
الاحتفاظ بسجلات التدقيق غير محدود لا تحذف أبدًا audit_logs
تسجيل الأسعار 100% الإصدار الحالي يفتقد 58.3% — قيد قاعدة البيانات يفرض ذلك
الحجوزات الراكدة 0% الإصدار الحالي 34.8% — التقدم التلقائي يعالج ذلك

التوطين والملاحظات الإقليمية

اللغة

العربية أولًا، RTL هو اتجاه التخطيط الأساسي. جميع النصوص الموجهة للمستخدم يجب أن تدعم العربية.

أرقام الهاتف

الصيغة السعودية: 05XXXXXXXX (10 أرقام). هذا هو المعرّف الأساسي للمستخدم.

العملة

ريال سعودي (SAR). بدون منازل عشرية للمستخدمين. جميع الأسعار شاملة ضريبة القيمة المضافة (15%).

المنطقة الزمنية

Asia/Riyadh (UTC+3). بدون توقيت صيفي. جميع الطوابع الزمنية تُخزّن بصيغة DATETIMEOFFSET. التقويم الميلادي (وليس الهجري).

ما يجعل هذا المشروع فريدًا

1. قيود مفروضة على مستوى قاعدة البيانات. القواعد التجارية الأكثر أهمية (منع الحجز المزدوج، إلزامية التسعير) تُفرض على مستوى SQL Server عبر UNIQUE INDEX + Trigger وقيود CHECK — وليس فقط في كود التطبيق. هذا مبدأ معماري جوهري.
2. طبقة خدمات مشتركة. يجب أن يستخدم كلٌّ من ويب المشرف وAPI الموبايل نفس فئات الخدمات. لا تكرار لمنطق الحجز في وحدتي تحكم مختلفتين. كل مسار يمر عبر BookingService.
3. تدقيق كل شيء. كل تعديل على الحجوزات والمدفوعات وبيانات المستخدمين يجب أن ينتج سجل تدقيق غير قابل للتغيير (من، ماذا، متى، القيمة القديمة، القيمة الجديدة). هذا الدرس الأول من مشكلة "الحجوزات المختفية" في الإصدار السابق.
4. WhatsApp هو القناة الأساسية. ليس البريد الإلكتروني، وليس الإشعارات الدافعة. WhatsApp هو الوسيلة التي يتفاعل من خلالها 98% من العملاء. أتمتته هي الأولوية التجارية الأولى.
5. تحديد نطاق مدير الملعب. مديرو الملاعب يمكنهم فقط رؤية/التفاعل مع الملاعب المسندة إليهم. هذا يُفرض عبر البرمجيات الوسيطة (middleware)، وليس مخفيًا في الواجهة. كل استعلام يجب أن يُفلتر حسب الملاعب المسندة.
6. العربية أولًا RTL. هذا هو الاتجاه الأساسي، وليس فكرة لاحقة. جميع الواجهات مصممة من اليمين إلى اليسار أولًا.

ملفات المطور

أضف هذه الملفات إلى جذر مشروع OneTwoApi لتهيئة Claude Code وتوفير القواعد التجارية الشاملة.

CLAUDE.md

تهيئة Claude Code — اتفاقيات الكود، قواعد البنية، القيود التجارية، وما لا يجب بناؤه. (~120 سطر)

spec.md

القواعد التجارية الشاملة — آلة حالة الحجز، المصادقة، RBAC، المدفوعات، العقود، الجدولة، جميع الـ 29 كيان + 18 تعداد. (~480 سطر)

fm-app-spec.md

مواصفات تطبيق مدير الملعب Flutter — الشاشات، تدفقات المصادقة، النطاق، قواعد الحجز، المدفوعات، الدعم بدون اتصال، نقاط API، معايير الواجهة. (~480 سطر)

أهداف النمو (12 شهرًا)

المقياس خط أساس v2 إطلاق v3 نهاية سنة v3
الملاعب النشطة 46 50 250
المواقع 15 15 40+
العملاء 507 550 2,500
الحجوزات/يوم 60.6 65 325
الإيرادات الشهرية (ريال) ~212K ~230K ~1,060K