منصة موحّدة لتأكيد
استلام الطلبات والشحنات

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

الأهداف المقترحة

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

فرضيات المشكلة التالية تُختبر بمقابلات وتجربة تشغيلية؛ وليست نتائج دراسة سوق مكتملة.

مجالات قابلة للدعم

اتساع نموذج المنتج لا يعني إطلاق جميع القطاعات معًا. يُختار قطاع أول وتجربة محددة قبل تعميم التشغيل.

تفصيل السيناريو الأساسي

1. التهيئة: اعتماد الجهة، المستخدمين، سياسة التحقق وقنوات الإشعار.
2. الإنشاء: إدخال بيانات الشحنة يدويًا أو عبر API والتحقق من صحتها وعدم تكرارها.
3. الملصق: توليد رمز مرتبط بالطرد، مع مرجع مقروء بديل عند تلف الطباعة.
4. التسليم الفعلي: ينقل الناقل الطلب خارج المنصة، ويسجل المحاولة إن كان مرتبطًا بها.
5. فتح الرابط: يعرض «وصول» الحد الأدنى من بيانات الطلب دون كشف معلومات حساسة قبل التحقق.
6. التحقق: إرسال رمز إلى وسيلة اتصال مسجلة مسبقًا، أو استخدام حساب مؤسسي مخول.
7. الإقرار: يراجع المستلم الطرود والنتيجة والنص، ثم يضغط زر التأكيد صراحة.
8. الحفظ: تسجيل الإقرار والطرود المستلمة والوقت ونسخة النص وسياق التحقق.
9. الإشعار: إصدار الإيصال وإضافة حدث إلى قائمة الإرسال للشريك.
10. الإغلاق: إغلاق الشحنة عند اكتمال جميع الطرود المطلوبة؛ أما النقص فيظل استثناءً مفتوحًا.

يُقترح فصل ثلاث مجموعات: حالة التسليم، حالة التحقق والجلسة، وحالة إرسال الإشعار. الفصل يمنع الخلط بين استلام البضاعة ووصول التحديث إلى نظام الشريك.

حالات بديلة يجب تصميمها

قواعد عمل حاكمة

1. مسح الرمز أو زيارة الرابط لا يغير حالة التسليم.
2. مرجع الطلب الخارجي يُفسر داخل نطاق الجهة، وليس معرّفًا عالميًا منفردًا.
3. لكل طرد معرّف مستقل؛ تأكيد طرد لا يغلق بقية الطرود تلقائيًا.
4. وسيلة التحقق تعتمد على بيانات معتمدة، لا على رقم يكتبه ماسح الرمز دون تحقق إداري.
5. تعديل المستلم أو وسيلة الاتصال يُسجل ويُبطل جلسات التحقق المفتوحة ذات الصلة.
6. الإقرار لا يُحذف أو يُستبدل بصمت؛ التصحيح إجراء لاحق مرتبط بالأصل وبصاحب الصلاحية.
7. إعادة الطلب البرمجي بنفس مفتاح منع التكرار لا تنشئ شحنة أو إقرارًا جديدًا.
8. نجاح حفظ الإقرار وحدث الإرسال عملية واحدة؛ الإرسال الخارجي لاحق ومستقل.
9. الرفض والتسليم الجزئي يتطلبان سببًا أو تحديدًا واضحًا للطرود المتأثرة.
10. دورة المرتجع اللاحقة مستقلة؛ لا تعيد كتابة حقيقة استلام سابق.

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

• التوافر: هدف الخدمة ونافذة الصيانة ومستويات الدعم تُعتمد بعد التجربة.
• الأداء: قياس زمن API وصفحة المستلم منفصلًا عن زمن مزود الرسائل.
• القابلية للتوسع: فصل المهام الثقيلة والإشعارات عن الطلبات التفاعلية.
• الوصول: واجهة عربية RTL، استخدام بلوحة المفاتيح، ورسائل خطأ واضحة.
• الاعتمادية: نسخ احتياطي، اختبار استعادة، ومراقبة تأخر الإشعارات.
• قابلية الصيانة: توثيق API وإصدارات وقواعد تحقق واختبارات آلية.

هذه قائمة المدخلات الأساسية المقترحة على مستوى الأعمال. قاموس الحقول التفصيلي وأطوالها وقيمها المرجعية من مخرجات التحليل اللاحق.

الكيانات المقترحة

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

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

مثال طلب إنشاء — عقد أولي للمناقشة

{
  "external_order_ref": "ORD-1048",
  "external_shipment_ref": "SHP-1048-A",
  "recipient": {
    "display_name": "عميل تجريبي",
    "phone": "+12025550123"
  },
  "verification_policy": "sms_otp",
  "parcels": [
    {
      "external_ref": "BOX-01",
      "description": "الطرد الأول"
    },
    {
      "external_ref": "BOX-02",
      "description": "الطرد الثاني"
    }
  ],
  "metadata": {
    "source_system": "partner-demo"
  }
}

لا يرسل العميل البرمجي هوية الجهة باعتبارها مصدر صلاحية؛ تُستنتج من بيانات اعتماد التكامل. المثال تجريبي، وحقل metadata له حدود ولا يُستخدم لتخزين أسرار أو بيانات شخصية عشوائية.

أحداث مقترحة

مثال إشعار

{
  "event_id": "evt_demo_0001",
  "type": "delivery.partially_confirmed",
  "occurred_at": "2026-10-18T10:30:00Z",
  "schema_version": "1",
  "resource_version": 4,
  "data": {
    "shipment_id": "shp_demo_1048",
    "external_shipment_ref": "SHP-1048-A",
    "acknowledgement_id": "ack_demo_0001",
    "status": "partially_confirmed",
    "received_parcel_refs": ["BOX-01"],
    "remaining_parcel_refs": ["BOX-02"]
  }
}

قواعد موثوقية التكامل المقترحة

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

ضوابط يُقترح اعتمادها في التصميم

سياسة الأدلة والاحتفاظ

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

ملصق مقترح — المحتوى لا الرسم النهائي

ما يدخل النسخة الأولى؟

ما يُؤجل؟

إجراءات التشغيل اللازمة

1. تهيئة الجهة وتحديد مسؤوليها وصلاحياتها ومراجعة بياناتها.
2. اعتماد سياسة التحقق ونص الإقرار والاحتفاظ.
3. اختبار الطباعة والرسائل والتكامل قبل الإنتاج.
4. تدريب التجهيز والمندوبين على عدم طلب مشاركة OTP.
5. تحديد مسار دعم للأرقام الخاطئة والروابط التالفة والاعتراضات.
6. مراجعة دورية لمفاتيح API والحسابات والتقارير والأحداث المعلقة.

معايير قبول وظيفية وأمنية أولية

مؤشرات التجربة

الأسئلة التالية تحول الفكرة من تصور عام إلى نطاق يمكن تقديره والتعاقد على تنفيذه.

المخرجات المطلوبة بعد مناقشة هذه المسودة

• وثيقة نطاق معتمدة للنسخة الأولى وحدود مسؤوليات الأطراف.
• قصص مستخدمين ومعايير قبول وترتيب أولويات.
• نماذج شاشات تفصيلية ونصوص الإقرار ورسائل الخطأ.
• ERD وقاموس بيانات وجدول انتقالات حالات.
• مواصفة OpenAPI وعقد Webhooks وخطة اختبار للشريك.
• تصميم أمان وخصوصية وتشغيل واستجابة للحوادث.
• تقدير زمني ومالي مبني على نطاق وفريق وافتراضات واضحة.