tripz-llc/docs/17-backend-backlog.md

17 — Backlog الباك إند (مراجعة المالك + مقارنة سيرو)

مصدره: مراجعة المالك (2026-07-17) + قراءة مباشرة لجداول سيرو (schema_primary.sql, schema_ride.sql). الترتيب حسب الأثر. نمشي مجموعة مجموعة.

---

المجموعة A — الزمن الحقيقي والإشعارات (الأعلى أولوية) — ✅ منفَّذة

شكوى المالك الأساسية: «تسأل القاعدة كثيراً، أقرب للـ polling»، والإشعارات ناقصة.

#	البند	التفصيل	الحالة
A1	FCM على كل حالات الرحلة	حالياً push عند assigned فقط. المطلوب: FCM + WebSocket على كل انتقال. ضروري للخلفية (background).	✅ notifyParties تُنادى من كل انتقال + priority: high + حذف التوكنات الميتة
A2	ترجمة الإشعارات	الإشعارات تُرسل إنجليزي والهاتف عربي → نصوص الإشعارات في ملفات ترجمة وتُرسل حسب لغة المستخدم.	✅ common/i18n (ar/en) + عمود users.language
A3	تقليل استعلامات القاعدة	حالة الرحلة الجارية + المواقع في Redis؛ القاعدة للحقيقة الدائمة فقط. (الآن كل انتقال يقرأ/يكتب عدة مرات + يقرأ السائق ثانيةً).	✅ TripStateService (hash لكل رحلة نشطة، TTL 6س) — الانتقال صار UPDATE شرطي + قراءة واحدة
A4	Race condition عند القبول	سائقان يقبلان بنفس اللحظة → قبول ذرّي (Redis SETNX / UPDATE شرطي WHERE status='searching'). أول قبول يفوز، والثاني يُرفض بوضوح.	✅ CAS بـLua في Redis + UPDATE … WHERE status='searching' كحَكَم نهائي
A5	إلغاء العرض عند القبول	فور القبول: بث WebSocket + FCM لبقية السائقين المعروض عليهم → «الرحلة لم تعد متاحة» فتختفي من شاشتهم/الـ overlay.	✅ مجموعة عروض في Redis + trip:offer_taken + FCM
A6	الرحلات المتاحة (available rides)	قائمة طلبات متاحة يسحبها السائق (بديل/مكمّل للعرض المباشر).	✅ GET /trips/available
A7	overlay أندرويد	معلومات الرحلة للقبول/الرفض فوق التطبيقات — يحتاج FCM data-message + payload كامل.	✅ dataOnly + payload كامل (نقاط، مسافة، أجرة، فئة، دفع)

مؤجَّل من A: سجل الأحداث (trip_events) ما زال يُكتب متزامناً داخل الطلب — نقله إلى BullMQ يبقى تحسيناً مفتوحاً (worker.ts لا يزال هيكلاً فارغاً).

---

المجموعة B — اكتمال نموذج الرحلة

مقارنة بجدول ride في سيرو + قواعد التشغيل.

#	البند	التفصيل
B1	حالة started وفصل الوصول عن البدء	السائق وصل ≠ الرحلة بدأت. الراكب قد لا يرد/يلغي. نحتاج تمييزاً صريحاً.
B2	عدّاد انتظار 5 دقائق (قانون)	يبدأ عند وصول السائق (بعد تأكيد المسافة من فلاتر). عند انتهائه: خيار للراكب — يبقى السائق منتظراً، أو تعويض فترة الانتظار.
B3	احتساب مشوار الوصول للراكب	المسافة/الزمن من موقع السائق حتى الراكب تُحتسب بالتعرفة (دقائق + مسافة).
B4	نقاط توقف (stops)	نقطتا توقف ضمن الرحلة (كما في سيرو/شير).
B5	حجز مسبق/جدولة	جداول الرحلة (date/time/endtime في سيرو).
B6	فصل السعر	price_for_driver مقابل price_for_passenger (العمولة) — ناقص عندنا.
B7	طوابع زمنية دقيقة	DriverIsGoingToPassenger · rideTimeStart · rideTimeFinish (سيرو) — عندنا assigned_at/completed_at فقط.
B8	مطابقة الوجهة	is_destination_match + خصم الراكب.
B9	تعديل التعرفة من لوحة الأدمن	جداول تعرفة قابلة للتحرير (موجودة كـ jsonb — نحتاج واجهة/نقاط CRUD).
B10	كتالوج أنواع الرحلات العالمي	ride_types فكرته سليمة (الأدمن/المستأجر يضيف أنواعه). المطلوب: كتالوج جاهز بما هو شائع عالمياً كخيارات جاهزة للاختيار (عندنا 6 فقط الآن).
B11	تعرفة بالوزن	بُعد تسعير إضافي بالوزن (للشحن/التوصيل) بجانب المسافة والزمن. الاستعلام عن التعرفة من Redis خط أول (G5).

---

المجموعة C — بيانات السائق والمركبة (من سيرو)

#	البند	التفصيل
C1	CarRegistration كامل	vin · car_plate · make · model · year · expiration_date · color + color_hex (لتلوين السيارة في فلاتر) · owner · fuel · isDefault · vehicle_category_id · fuel_type_id · status.
C2	حقول السائق	gender · national_number (فريد) · name_arabic · first/last_name · birthdate · license_type/categories/issue/expiry · address · accountBank/bankCode · employmentType · maritalStatus · rejected_reason (سبب رفض خدمة العملاء).
C3	ai_data + user_input	تخزين مخرجات Gemini الخام و ما أدخله السائق — للمقارنة والتدقيق (نمط سيرو).
C4	صور السيارة ×2	صورتان للمركبة (لا واحدة).
C5	فيديو/liveness للوجه	تأكيد حيّ للوجه (غير السيلفي الثابت).

---

المجموعة D — الأمان والمصادقة

#	البند	التفصيل
D1	تطبيع أرقام الهاتف (JO/EG/SY)	خصوصاً مصر: الناس تكتب 01… بدل 1… وتظن المفتاح 2 لا 20. نحتاج normalize احترافي لكل دولة.
D2	بصمة الجهاز (device fingerprint)	تُرسل من فلاتر مع كل request وتُربط بالجلسة (نمط سيرو: التوكن المسروق لا يعمل على جهاز آخر).
D3	HMAC للعمليات الحساسة	خصوصاً المدفوعات — توقيع الطلب.

---

المجموعة E — كشف الاحتيال (من driver_ride_scam)

#	البند	التفصيل
E1	تسجيل زر الاتصال	isDriverCallPassenger لكل رحلة (سيرو).
E2	ربط الاتصال بالإلغاء	اتصال ثم إلغاء = مؤشر اتفاق خارج التطبيق. 3 إلغاءات/يوم → إنذار؛ التكرار → إجراء.

---

المجموعة F — الدردشة

| F1 | إشعار الرسالة يُرسل فقط إذا لم تكن صفحة الدردشة مفتوحة (المعالجة الأساسية في فلاتر؛ الباك إند يرسل دائماً ويترك القرار للعميل أو عبر presence). |

---

المجموعة G — Redis خط أول والقاعدة خط احتياط

مراجعة المالك (2026-07-17، الجولة الثانية): «كل ما بدي أبعث notification أستعلم من القاعدة — هذا ثقيل. الريدز خط أول، القاعدة نقطة الاحتياط». القاعدة: البيانات الساخنة والمتكررة تُقرأ من Redis؛ القاعدة تُقرأ مرة واحدة عند البرود (cache miss) ثم تُكتب في Redis.

#	البند	التفصيل
G1	لغة المستخدم في Redis	users.getLanguage() الآن استعلام قاعدة قبل كل إشعار. المطلوب: فلاتر يفحص لغة الجهاز عند الفتح ويرفعها → تُخزَّن في Redis (user:lang:{tenant}:{user}) → الإشعار يقرأ من هناك. القاعدة احتياط عند غياب المفتاح.
G2	توكنات الأجهزة (FCM) في Redis	sendLocalized يقرأ device_tokens من القاعدة لكل إرسال. تُخزَّن set لكل مستخدم في Redis.
G3	sendLocalizedToMany عبر غرف Redis	البث الجماعي يعتمد الغرف بدل استعلام لكل مستخدم — خصوصاً في dispatch.
G4	tenant في Redis	TenantsService.resolve(slug→uuid) يعمل على كل request (middleware). كاش دائم في Redis (يتغيّر نادراً جداً). أعلى نسبة قراءات في النظام.
G5	التعرفة و ride-types في Redis	جداول شبه ثابتة تُقرأ في كل تسعير/طلب — كاش مع إبطال عند تعديل الأدمن.
G6	التقييم (ratings) بتراكم يومي	التقييم يُجمَّع في Redis ويُكتب/يُحدَّث على القاعدة مرة واحدة يومياً لكل طرف (إن لم يكن حُدِّث بنفس اليوم). فائدتان: استجابة أسرع، وتأخير ظهور التقييم ~يوم كامل يبعد الاحتكاك بين الطرفين. للطرفين معاً (راكب وسائق).
G7	سعة Redis	رصد مساحة أكبر أو Redis منفصل عند الحاجة (خصوصاً dispatch + المواقع). حالياً DB 3 مشترك — راجع docs/14.

---

المجموعة H — المواقع والتتبع (من loction_server في سيرو)

ملاحظة المالك: «لحد الآن مش شايف السائق أو الراكب يرفع موقعه، ولا جداول location». عندنا الآن: driver:location عبر WebSocket → Redis GEO + حفظ صف السائق في Postgres على كل نبضة (drivers.updateLocation يعمل repo.save) — هذا أثقل حتى من سيرو.

ما يفعله سيرو (مقروء من الكود):

• driver_socket.php — سوكيت مخصص للمواقع، لا يلمس القاعدة إطلاقاً؛ Redis فقط عبر pipeline كل 500ms (REDIS_BATCH_INTERVAL).
• عتبات لتقليل الكتابة: MIN_MOVE_METERS=10 (GEOADD فقط عند تحرّك >10م)، HMSET_SPEED_DELTA=1.0، HMSET_HEADING_DELTA=5، FORWARD_MIN_METERS=15 / FORWARD_MAX_SECONDS=3 للبث للراكب.
• فهرسان منفصلان: geo:drivers:available وgeo:drivers:busy (عندنا فهرس واحد لكل فئة خدمة، بلا تمييز مشغول/متاح).
• driver:profile:{id} hash في Redis (heading/speed/status) — المطابقة تقرأ منه بلا قاعدة.
• عروض الرحلة: setex للعرض + sadd لمجموعة المعروض عليهم + expire — نفس نمطنا في A5 ✅.

#	البند	التفصيل
H1	إيقاف كتابة الموقع على القاعدة لكل نبضة	drivers.updateLocation يكتب Postgres كل ثانية/ثلاث — يُنقل إلى Redis فقط.
H2	عتبات + batching	تبنّي عتبات سيرو (10م/1.0 سرعة/5 اتجاه) + pipeline كل 500ms.
H3	جدول car_locations مكافئ	صف واحد لكل سائق (آخر موقع) — يُكتب دورياً من worker لا من الطلب. عند سيرو: ON DUPLICATE KEY UPDATE + عمود point SRID 4326 عبر trigger (عندنا PostGIS متاح).
H4	جدول car_tracks (المسار)	سجل نقاط تاريخي للتتبع/النزاعات — إدراج مجمّع (batch insert) من worker.
H5	فهرس available/busy	تمييز السائق المشغول عن المتاح في فهرس GEO.
H6	driver_behavior	max_speed · avg_speed · hard_brakes · total_distance · behavior_score لكل رحلة.
H7	driver_daily_work / driver_daily_summary	ساعات عمل السائق (total_seconds باليوم + last_point_at + last_status).
H8	ربط المواقع بالمطابقة والـdispatch	المطابقة تقرأ driver:profile من Redis؛ لوحة dispatch ترى الأسطول حياً.
—	Geofence	مؤجَّل بقرار المالك («خليها لوقتها») — موجود في سيرو (get_location_area_links, LocationIntelligenceEngine).

---

المجموعة I — المدفوعات والمحفظة (من payment_server في سيرو) 🔴 أمني

طلب المالك: تدقيق أمني على المدفوعات، خصوصاً الـpayout: OTP عبر نبيه + بصمة (وجه/إصبع) في فلاتر + HMAC.

بنية سيرو (مقروءة من WalletDB.sql + sms_webhook/):

• جدول لكل طريقة دفع (كما قال المالك): cliq_invoices · ecash_transactions (+_driver) · invoices_shamcash (+_passenger) · mtn_invoices · invoices_sms (+_passenger) · kazan.
• محافظ منفصلة: driverWallet · passengerWallet · siroWallet (محفظة الشركة) — نمط دفتر قيود append-only، الرصيد = SUM(amount).
• نمط ذكي جداً: raw_sms_log + process_with_gemini.php — رسالة SMS من مزوّد الدفع تُرفع خاماً، Gemini يقرأها ويستخرج المبلغ/المرجع، ثم finalize_wallet_payment. يحلّ غياب الـAPI الرسمي في سوريا.
• payment_tokens (+_passenger) للتتبع/عدم التكرار · admin_audit_log · paymentsLogSyria(Driver).

🔴 ثغرات وجدتها في كود سيرو — لا تُنقل كما هي:

الثغرة	التفصيل
IDOR في request_payout.php	driverId وphone يُؤخذان من الطلب لا من الـJWT → سائق يطلب سحب رصيد سائق آخر إلى هاتفه. يجب اشتقاق الهوية من التوكن حصراً.
لا خصم عند الطلب	الطلب يفحص الرصيد ثم يُدرج سجلاً فقط بلا حجز → طلبات متعددة متزامنة تمرّ كلها (double-spend).
عمولة متناقضة	request_payout يفحص balance >= amount + 3500 (العمولة فوق المبلغ)، وfinalize_payout يحسب netAmount = amount - 3500 ويخصم الصافي فقط (العمولة داخله) → تسريب مال. والرقم 3500 مكرر حرفياً في الملفين.
finalizePayout بلا معاملة	5 عمليات كتابة بلا beginTransaction/rollBack → فشل في المنتصف = خصم بلا تسجيل عمولة (حالة نصفية).
UPDATE payments SET isGiven=TRUE WHERE driverID=… AND isGiven=FALSE	يعلّم كل الدفعات المعلّقة كمدفوعة بغضّ النظر عن مبلغ السحب.
driverWallet.amount = varchar(10)	المال مخزَّن كنص (وحساب SUM على varchar).
لا OTP على الـpayout	phone_verification موجود لكنه مستخدم في التسجيل/الدخول فقط — لا شيء يحمي السحب. (ملاحظة المالك صحيحة.)
جدولان متداخلان	payout_requests وdriver_withdrawal_requests لنفس المفهوم.

🔴 ثغرة في كودنا نحن (wallet.service.ts): credit/debit تعمل read-modify-write على عمود balance بلا قفل ولا معاملة → سباق حقيقي: خصمان متزامنان يقرآن نفس الرصيد ويكتبان فوق بعض = مال مفقود/مخلوق. سيرو هنا أفضل منّا (دفتر قيود + FOR UPDATE).

#	البند	التفصيل
I1	✅ إصلاح سباق المحفظة	منفَّذ: UPDATE … SET balance = balance ± :delta WHERE tenant_id … AND balance >= :amount RETURNING * — عبارة واحدة ذرّية، والقيد+الرصيد في معاملة واحدة. أُضيف wallet_txns.balance_after وقيد CHECK (balance >= 0) كشبكة أمان. إنشاء المحفظة عبر ON CONFLICT DO NOTHING. اختبارات jest على pg-mem + scripts/wallet-race-test.mjs للتزامن الحقيقي على السيرفر.
I2	محفظة لكل طرف + محفظة المنصة	راكب · سائق · المستأجر/المنصة (مكافئ siroWallet) — أساس العمولة (B6).
I3	جدول لكل طريقة دفع	شام كاش · كليك · إي كاش · بيموب · MTN · فوري … لكل واحدة جدولها + محوّل (adapter) موحّد. حالياً عندنا tripz_pay_payments عام.
I4	OTP على الـpayout عبر نبيه	إرسال كود + تحقّق قبل تنفيذ السحب (لا يوجد في سيرو).
I5	بصمة (وجه/إصبع) في فلاتر	تأكيد حيوي قبل السحب — يُربط بالطلب (device fingerprint من D2).
I6	HMAC على العمليات المالية	توقيع الطلب (D3) — إلزامي على topup/payout.
I7	سجل تدقيق مالي	مكافئ admin_audit_log — من فعل ماذا ومتى على كل عملية.
I8	webhook SMS + Gemini	تبنّي نمط سيرو للأسواق بلا API رسمي (سوريا): raw_sms_log + استخراج بالـAI + تسوية.

---

قرار: هل يخاطب فلاتر خرائط انطلق مباشرة؟

القرار المتّخذ (2026-07-17): تقسيم حسب نوع النداء — لا «كله مباشر» ولا «كله عبر السيرفر».

النوع	المسار	السبب
البلاطات (tiles)	فلاتر → انطلق مباشرة	حجم كبير ومتكرر، لا يحمل أسراراً، ويُخزَّن مؤقتاً على الجهاز. تمريره عبر سيرفرنا = تضخيم عرض النطاق بلا فائدة.
geocode / reverse / route / places	فلاتر → سيرفرنا → انطلق	يحمي مفتاح API (مفتاح داخل التطبيق = مسروق)، يتيح كاش Redis، حصص لكل مستأجر، وتبديل المزوّد بلا تحديث التطبيق.

السرعة ليست مقايضة هنا — بالعكس: اختبار التحميل عندنا أظهر أن p50 قفز إلى 2.9 ثانية والسبب المهيمن هو نداء HTTP الخارجي إلى انطلق. كاش النتائج في Redis (نفس العنوان يُطلب آلاف المرات) يجعل المسار عبر سيرفرنا أسرع من النداء المباشر، لا أبطأ. الإضافة الصافية للسيرفر ~10–30ms مقابل توفير ~2.9s على كل إصابة كاش. → البند المطلوب: كاش Redis لنتائج geocode/route/places (يُضاف للمجموعة G).

---

مؤجَّل عمداً (قرار المالك)

المفاوض الذكي · تدرّج السائق · خصم العمولة — آخر شيء (جديدة حتى على سيرو). Geofence — مؤجَّل («لوقتها»)، موجود في سيرو للاستئناس.

---

ترتيب التنفيذ المقترح

1. A (الزمن الحقيقي + FCM + Redis + race) ✅ منفَّذة.
2. I1 (سباق المحفظة) — عاجل: ثغرة مالية حيّة في كودنا، تُنفَّذ وحدها فوراً.
3. G (Redis خط أول: لغة/توكنات/tenant/تعرفة/تقييم/كاش الخرائط) — امتداد طبيعي لـA.
4. H (المواقع: إيقاف الكتابة لكل نبضة + batching + tracks).
5. B (نموذج الرحلة: started/انتظار/فصل السعر/الطوابع/stops).
6. I الباقي (المدفوعات: جداول لكل طريقة + OTP/بصمة/HMAC للسحب).
7. C (بيانات المركبة والسائق + ai_data).
8. D (تطبيع الهاتف + بصمة الجهاز + HMAC).
9. E (الاحتيال) ثم F.