واجهة السائق

حركة السائق تذهب إلى واجهة الإدارة (http://localhost:5001).

دخول الموظف

نفس الملتقط: POST /v1/auth/login بالبريد وكلمة المرور. احفظ accessToken وrefreshToken. أرسل Authorization: Bearer <accessToken> مع كل استدعاء. التحديث عبر POST /v1/auth/refresh مع { "refreshToken" }.

وجّه الواجهة عندما results.user.roleKey === "driver".

بذور التطوير: driver1@test.com، driver2@test.com، كلمة المرور 123. الصلاحيات: orders:read، orders:update. مقيّد بالفرع إن وُجدت branchIds.

سير العمل

ready --pickup--> out_for_delivery --deliver--> delivered
                         |
                         +--fail--> delivery_failed --retry--> out_for_delivery
                                              |
                                              +--return--> ready

استطلع GET /v1/fulfillment/driver/orders. حالات الطابور: ready، out_for_delivery، delivery_failed.

النقاط

GET يتطلب orders:read. POST يتطلب orders:update.

الطريقة	المسار	الجسم	الغرض
GET	/v1/fulfillment/driver/orders	—	بطاقات الطابور
GET	/v1/fulfillment/driver/orders/:orderId	—	الطلب الكامل + محاولات التوصيل
POST	/v1/fulfillment/driver/orders/:orderId/pickup	—	بدء الرحلة؛ الحالة → out_for_delivery
POST	/v1/fulfillment/driver/orders/:orderId/deliver	—	نجاح؛ الحالة → delivered
POST	/v1/fulfillment/driver/orders/:orderId/fail	{ reason, note? }	زيارة فاشلة
POST	/v1/fulfillment/driver/orders/:orderId/retry	—	الخروج من المتجر مجدداً
POST	/v1/fulfillment/driver/orders/:orderId/return	—	الكيس يعود للمتجر؛ الحالة → ready

أسباب الفشل

reason	استخدمه عندما
customer_absent	لا أحد عند الباب
refused	رفض العميل الطلب
wrong_address	العنوان غير صالح للاستخدام
unreachable	فشل الهاتف / الوصول
other	أي شيء آخر (note موصى به)

note اختياري، حد أقصى 256 حرفاً.

مثال الاستلام ثم التسليم

POST /v1/fulfillment/driver/orders/665f0c0c0c0c0c0c0c0c0c10/pickup
Authorization: Bearer <accessToken>

POST /v1/fulfillment/driver/orders/665f0c0c0c0c0c0c0c0c0c10/deliver
Authorization: Bearer <accessToken>

مثال الفشل

POST /v1/fulfillment/driver/orders/665f0c0c0c0c0c0c0c0c0c10/fail
Content-Type: application/json

{ "reason": "customer_absent", "note": "لا رد بعد 3 دقائق" }

retry لا يعيد إشعار العميل. return يعيد الطلب إلى رف الجاهزية لرحلة جديدة.

يشمل delivery على الطلب الحقول driver وpickedUpAt وdeliveredAt الاختياري وattempts[] وlastFailureReason.

الموقع الجغرافي

يسمح مخطط التوصيل بالموقع لاحقاً. الواجهة الحالية لا تقبل نبضات GPS حية.