# ReValue — خطة تنفيذ المشروع الكاملة

> **المشروع:** ReValue — منصة وسيط ضامن (Escrow) لبيع وشراء الخردة والسكراب
> **الـ Backend المعتمد:** **Laravel** (PHP)
> **الوثائق المرافقة:** `01-revalue-features-list.md` (الخصائص) · `03-revalue-build-checklist.md` (قائمة التنفيذ)
> **تاريخ الخطة:** 10 أغسطس 2026

---

# 0. ملخص الخطة في صفحة واحدة

| المحور | القرار |
|---|---|
| **Backend** | Laravel 11 + PHP 8.3 + MySQL 8 + Redis |
| **Realtime** | Laravel Reverb (أو Soketi) + Laravel Echo — للمزايدة الحيّة والمحادثات |
| **الطوابير** | Laravel Horizon + Redis Queues — لإغلاق المزادات والإشعارات والاستردادات |
| **الجدولة** | Laravel Scheduler — لإغلاق المزادات، مهل الدفع، احتساب نبض السوق |
| **تطبيقا الجوال** | **Flutter** (كود واحد لـ iOS و Android) — التوصية الافتراضية |
| **لوحة الإدارة** | Laravel + Inertia.js + Vue 3 + Tailwind (RTL) |
| **التخزين** | S3-compatible (صور المواد، السجلات التجارية، مرفقات الشكاوى) |
| **عدد المراحل** | **8 مراحل** موزّعة على **20 Sprint** (أسبوعان لكل Sprint) |
| **المدة التقديرية** | **28 – 34 أسبوعاً** (≈ 7 – 8.5 أشهر) للنطاق الكامل |
| **حجم الفريق المقترح** | 8 – 10 أشخاص |

> ⚠️ **تحذير جوهري:** هناك **10 قرارات عمل حاسمة** يجب حسمها مع العميل **قبل بدء المرحلة 3** (المحرك المالي) — تفاصيلها في **القسم 9**. البدء في البناء المالي قبل حسمها يعني إعادة كتابة مؤكدة.

---

# 1. المعمارية التقنية

## 1.1 المخطط العام

```
┌─────────────────┐  ┌─────────────────┐  ┌──────────────────┐
│  تطبيق المشتري  │  │  تطبيق البائع   │  │  لوحة الإدارة    │
│    Flutter      │  │    Flutter      │  │  Inertia + Vue   │
└────────┬────────┘  └────────┬────────┘  └────────┬─────────┘
         │  REST + WebSocket  │                    │
         └──────────┬─────────┴────────────────────┘
                    │
         ┌──────────▼──────────────────────────────┐
         │        Laravel API (Sanctum Auth)        │
         │  Controllers → Form Requests → Services  │
         │        → Actions → Repositories          │
         └──┬────────┬────────┬────────┬────────┬───┘
            │        │        │        │        │
      ┌─────▼──┐ ┌──▼───┐ ┌──▼────┐ ┌─▼─────┐ ┌▼────────┐
      │ MySQL  │ │Redis │ │Reverb │ │Horizon│ │   S3    │
      │   8    │ │Cache │ │  WS   │ │ Queue │ │ Storage │
      └────────┘ └──────┘ └───────┘ └───────┘ └─────────┘
                    │
      ┌─────────────▼──────────────────────────────┐
      │            التكاملات الخارجية               │
      │  نفاذ · بوابة الدفع · SMS · Google Maps ·  │
      │              FCM / APNs                     │
      └────────────────────────────────────────────┘
```

## 1.2 مبادئ معمارية إلزامية

| المبدأ | التطبيق |
|---|---|
| **Service / Action Layer** | كل منطق عمل في Action Class مستقل — لا منطق في Controllers |
| **State Machine صريحة** | حالات المزاد والطلب والعرض والشكوى تُدار بـ State Pattern لا بـ if/else |
| **Ledger لا أرصدة مباشرة** | كل حركة مالية = **قيد في جدول `transactions`** — الرصيد يُشتق منه لا يُعدَّل مباشرة |
| **Idempotency** | كل عملية دفع/استرداد تحمل `idempotency_key` لمنع التكرار |
| **DB Transactions** | كل عملية مالية داخل `DB::transaction()` مع `lockForUpdate()` |
| **Audit Log** | كل تغيير حالة أو حركة مالية يُسجَّل بالمستخدم والوقت والقيمة القديمة/الجديدة |
| **API Versioning** | `/api/v1/...` منذ اليوم الأول |
| **Multi-language** | كل نص في ملفات ترجمة — لا نص مكتوب مباشرة في الكود |

## 1.3 حزم Laravel المقترحة

| الحزمة | الغرض |
|---|---|
| `laravel/sanctum` | مصادقة التطبيقات (Token) |
| `laravel/reverb` | WebSocket server (المزايدة الحيّة + المحادثات) |
| `laravel/horizon` | إدارة الطوابير والمراقبة |
| `spatie/laravel-permission` | الأدوار والصلاحيات في لوحة الإدارة |
| `spatie/laravel-medialibrary` | إدارة الصور + توليد Thumbnails + العلامة المائية |
| `spatie/laravel-activitylog` | Audit Log |
| `spatie/laravel-translatable` | المحتوى متعدد اللغات (التصنيفات، الصفحات الثابتة) |
| `spatie/laravel-model-states` | State Machines للمزاد والطلب |
| `intervention/image` | معالجة الصور والعلامة المائية |
| `barryvdh/laravel-dompdf` | توليد الفواتير وتقارير PDF |
| `maatwebsite/excel` | تصدير التقارير Excel |
| `pusher/pusher-php-server` | (بديل Reverb إن اختير Pusher المُدار) |

---

# 2. تصميم قاعدة البيانات (الجداول الأساسية)

## 2.1 المستخدمون والحسابات

| الجدول | الحقول الجوهرية |
|---|---|
| `users` | id, phone, name, type (buyer\|seller\|admin), status, city_id, lat, lng, national_id, avatar, language, is_verified_nafath, fcm_token, created_at |
| `seller_profiles` | user_id, seller_type (individual\|company), company_name, commercial_register_file, nafath_verified_at, nafath_payload (json), review_status (pending\|approved\|rejected), rejection_reason, reviewed_by, reviewed_at |
| `addresses` | id, addressable_type (Client\|Provider), addressable_id, label (home\|work\|other), lat, lng, address, is_default |
| `admin_users` | id, name, username, email, phone, password, role_id, status |
| `roles` / `permissions` / `role_has_permissions` | Spatie standard |
| `otp_codes` | id, phone, code, purpose (register\|login\|change_phone_old\|change_phone_new), expires_at, attempts, consumed_at |

## 2.2 الكتالوج والتصنيفات

| الجدول | الحقول |
|---|---|
| `categories` | id, parent_id, name_ar, name_en, slug, status, sort_order |
| `cities` | id, name_ar, name_en, status |
| `material_conditions` | id, name_ar, name_en (جديد / مستعمل-جيد / مستعمل-مقبول) |
| `units` | id, name_ar, name_en, symbol (طن / كجم) |

## 2.3 القوائم (المزادات والعروض)

| الجدول | الحقول الجوهرية |
|---|---|
| `listings` | id, seller_id, **type (auction\|direct_offer)**, category_id, subcategory_id, condition_id, title, description, quantity, unit_id, city_id, lat, lng, pickup_address_text, **status**, review_status, rejection_reason, published_at, created_at |
| `listing_images` | id, listing_id, path, sort_order, has_watermark |
| `auction_details` | listing_id, start_price, min_bid_increment, deposit_amount, starts_at, ends_at, current_highest_bid, bidders_count, winner_user_id, second_place_user_id, closed_at |
| `offer_details` | listing_id, asking_price_per_unit, total_price, offers_count |
| `favorites` | id, user_id, listing_id |

**حالات `listings.status`:** `draft` · `pending_review` · `rejected` · `scheduled` · `active` · `paused` · `ended_sold` · `ended_unsold` · `cancelled` · `expired`

## 2.4 المزايدات

| الجدول | الحقول |
|---|---|
| `auction_deposits` | id, listing_id, user_id, amount, transaction_id, status (held\|refunded\|forfeited), refunded_at |
| `bids` | id, listing_id, user_id, amount, is_highest, created_at (**فهرس مركّب على listing_id + amount DESC**) |
| `auction_winners` | id, listing_id, user_id, rank (1\|2), bid_amount, payment_deadline_at, status (pending_payment\|paid\|forfeited\|transferred) |

## 2.5 الطلبات ودورة الحياة

| الجدول | الحقول الجوهرية |
|---|---|
| `orders` | id, order_number (`ORD-YYYY-NNNN`), listing_id, **source (auction\|direct_offer)**, buyer_id, seller_id, agreed_price, quantity, commission_amount, deposit_applied, total_paid, **status**, inspection_at, inspection_location, handshake_code, handshake_verified_at, buyer_confirmed_at, escrow_released_at, cancelled_reason |
| `order_status_history` | id, order_id, from_status, to_status, actor_id, note, created_at |
| `price_adjustment_requests` | id, order_id, buyer_id, actual_weight, proposed_price, reason, new_total, new_commission, status (pending\|accepted\|rejected), responded_at |
| `order_ratings` | id, order_id, rater_id, ratee_id, stars, tags (json), comment |
| `rating_tags` | id, name_ar, name_en, applies_to (buyer\|seller), status |
| `invoices` | id, order_id, invoice_number, pdf_path, generated_at |

**حالات `orders.status` — مسار العرض المباشر:**
`pending_inspection` → `price_review` (اختياري) → `pending_payment` → `in_progress` (كود الاستلام) → `completed` / `cancelled` / `on_hold_complaint`

**حالات `orders.status` — مسار المزاد:**
`paid_pending_schedule` → `pending_inspection` → `pending_delivery` → `completed` / `cancelled` / `on_hold_complaint`

## 2.6 المحرك المالي

| الجدول | الحقول |
|---|---|
| `wallets` | id, user_id, available_balance, escrow_balance, total_commissions, currency |
| `transactions` | id, wallet_id, user_id, **type**, amount (signed), balance_after, reference_type, reference_id, gateway_ref, idempotency_key, status, created_at |
| `escrow_holds` | id, order_id, buyer_id, seller_id, amount, commission, net_to_seller, status (held\|released\|refunded), released_at |
| `payment_attempts` | id, user_id, purpose (deposit\|final_payment), amount, gateway, gateway_ref, status (initiated\|success\|failed), failure_reason, payload (json) |
| `withdrawal_requests` | id, user_id, amount, bank_name, account_holder, account_number, iban, status (pending\|approved\|transferred\|rejected), reviewed_by, admin_note |

**أنواع `transactions.type`:** `deposit_hold` · `deposit_refund` · `deposit_forfeit` · `final_payment` · `commission` · `escrow_release` · `withdrawal` · `complaint_compensation` · `adjustment`

> 🔒 **قاعدة صارمة:** `wallets.available_balance` يُحدَّث **فقط** عبر Observer على `transactions` — ولا يُعدَّل يدوياً في أي مكان.

## 2.7 المحادثات والإشعارات

| الجدول | الحقول |
|---|---|
| `conversations` | id, listing_id, buyer_id, seller_id, order_id, status (open\|agreed\|read_only), last_message_at |
| `messages` | id, conversation_id, sender_id, body, attachment_path, type (text\|image\|system\|price_offer), read_at |
| `price_offers` | id, conversation_id, seller_id, price, quantity, inspection_location, inspection_at, status (pending\|accepted\|rejected) |
| `notifications` | id, user_id, type, title, body, data (json), read_at, deleted_at |
| `admin_broadcasts` | id, title, body, target (all\|buyers\|sellers), scheduled_at, sent_at, created_by |

## 2.8 الشكاوى ومؤشر السوق

| الجدول | الحقول |
|---|---|
| `complaint_reasons` | id, name_ar, name_en, applies_to, status |
| `complaints` | id, complaint_number, user_id, order_id, reason_id, custom_reason, details, status (new\|under_review\|resolved), resolution_action, admin_note, resolved_by, resolved_at |
| `complaint_attachments` | id, complaint_id, path |
| `market_indices` | id, material_name, category_id, unit_id, current_price, status |
| `market_index_prices` | id, market_index_id, price, recorded_at, entered_by (**سجل تاريخي — لا تحديث في المكان**) |
| `auction_closings_daily` | id, category_id, date, avg_closing_price, auctions_count, total_quantity (**جدول مُجمَّع يُبنى بـ Job يومي**) |

## 2.9 الإعدادات والمحتوى

| الجدول | الحقول |
|---|---|
| `settings` | key, value, type, group (**commission_rate, payment_deadline_hours, nearby_radius_km, min_withdrawal, winners_count, watermark_enabled...**) |
| `static_pages` | id, slug, title_ar, title_en, content_ar, content_en |
| `faqs` | id, question_ar, question_en, answer_ar, answer_en, audience, sort_order |
| `onboarding_slides` | id, title, description, image, features (json), sort_order, audience |
| `guidance_steps` | id, name, description, sort_order, context (after_deposit) |
| `motivational_messages` | id, message, context (outbid\|leading), status |

---

# 3. آلات الحالات (State Machines) — العمود الفقري

## 3.1 آلة حالة المزاد

```
draft ──(نشر)──► pending_review ──(رفض)──► rejected ──(تعديل)──► pending_review
                       │
                  (موافقة)
                       ▼
                  scheduled ──(بلوغ starts_at)──► active
                                                    │
                                            (بلوغ ends_at)
                                                    │
                            ┌───────────────────────┴──────────────┐
                            │                                      │
                     يوجد مزايدات                            لا مزايدات
                            │                                      │
                            ▼                                      ▼
                     ended_sold                            ended_unsold
                            │
                   [مهلة دفع الفائز #1]
                            │
              ┌─────────────┴──────────────┐
         دفع خلال المهلة              لم يدفع
              │                            │
              ▼                            ▼
        إنشاء Order            forfeit(#1) + transfer(#2)
        + استرداد الباقي                   │
                              ┌────────────┴───────────┐
                         دفع #2                    لم يدفع #2
                              │                        │
                              ▼                        ▼
                        إنشاء Order            forfeit(#2) + cancelled
                        + استرداد الباقي        + استرداد الباقي
```

## 3.2 آلة حالة الطلب — مسار العرض المباشر

```
pending_inspection
   ├──(المشتري: تأكيد المعاينة)──────────────► pending_payment
   ├──(المشتري: طلب تعديل سعر — مرة واحدة)───► price_review
   │        ├──(البائع: قبول)──► pending_payment (بسعر جديد)
   │        └──(البائع: رفض)───► [قرار مطلوب — انظر §9.6]
   └──(المشتري: رفع شكوى)────────────────────► on_hold_complaint

pending_payment ──(دفع ناجح → Escrow Hold)──► in_progress

in_progress
   ├──(البائع يُدخل كود الاستلام ✓)
   └──(المشتري يؤكد الاستلام ✓)──────────────► completed
                                                  │
                                        (تحرير Escrow − العمولة
                                         → محفظة البائع)

on_hold_complaint ──(قرار الإدارة)──► completed | cancelled | pending_payment
```

## 3.3 آلة حالة الطلب — مسار المزاد

```
paid_pending_schedule ──(البائع يحدد موعد المعاينة)──► pending_inspection
pending_inspection ──(المشتري يؤكد المعاينة)────────► pending_delivery
                   └──(المشتري يرفع شكوى)───────────► on_hold_complaint
pending_delivery ──(كود الاستلام + تأكيد)──────────► completed
```

## 3.4 آلة حالة الشكوى

```
new ──► under_review ──► resolved
                            ├─ compensate_and_cancel
                            ├─ close_and_continue
                            └─ cancel_without_payment
```

---

# 4. واجهات الـ API (المجموعات الرئيسية)

> جميع المسارات تحت `/api/v1` · المصادقة عبر **Sanctum Bearer Token** · جميع الردود بصيغة موحّدة `{ success, data, message, errors }`

## 4.1 المصادقة والحساب
```
POST   /auth/request-otp                    إرسال OTP
POST   /auth/verify-otp                     التحقق من OTP
POST   /auth/register/buyer                 إكمال بيانات المشتري
POST   /auth/register/seller                إكمال بيانات البائع
POST   /auth/nafath/initiate                بدء توثيق نفاذ
GET    /auth/nafath/status                  استعلام حالة التوثيق
POST   /auth/logout
GET    /me                                  الملف الشخصي
PUT    /me                                  تحديث الملف
DELETE /me                                  حذف الحساب
POST   /me/change-phone/{step}              مسار تغيير الجوال
GET    /me/addresses  ·  POST  ·  PUT  ·  DELETE
```

## 4.2 الاستكشاف والقوائم
```
GET  /home/buyer                            الرئيسية (Hero + الأقسام)
GET  /home/seller                           رئيسية البائع
GET  /listings?type=&category=&city=&near=  البحث والفلترة
GET  /listings/{id}                         تفاصيل مزاد/عرض
POST /listings/{id}/favorite
GET  /categories  ·  GET /cities
```

## 4.3 المزادات والمزايدة
```
POST /auctions/{id}/deposit/initiate        بدء دفع الضمان
POST /auctions/{id}/deposit/confirm         تأكيد (Webhook/Callback)
GET  /auctions/{id}/live                    حالة المزاد اللحظية
POST /auctions/{id}/bids                    وضع مزايدة  ← [العملية الأحرج]
GET  /auctions/{id}/bidders                 قائمة المزايدين (أسماء مختصرة)
GET  /auctions/{id}/result                  نتيجة الفوز/الخسارة
POST /auctions/{id}/final-payment           إتمام دفع مبلغ الفوز
GET  /me/auctions                           مزاداتي المشترك بها
```

**قنوات WebSocket:**
```
private-auction.{id}     ← BidPlaced · AuctionEnded · CompetitionLevelChanged
private-user.{id}        ← OutbidNotification · OrderStatusChanged
private-conversation.{id}← MessageSent · PriceOfferMade · AgreementConfirmed
```

## 4.4 العروض والمحادثات
```
POST /listings/{id}/make-offer              فتح محادثة عرض
GET  /conversations  ·  GET /conversations/{id}/messages
POST /conversations/{id}/messages
POST /conversations/{id}/price-offer        (البائع) تأكيد عرض السعر النهائي
POST /conversations/{id}/price-offer/accept (المشتري) تأكيد الاتفاق
POST /conversations/{id}/price-offer/reject
```

## 4.5 الطلبات
```
GET  /orders?tab=offers|auctions&status=
GET  /orders/{id}
POST /orders/{id}/confirm-inspection
POST /orders/{id}/price-adjustment          (المشتري — مرة واحدة)
POST /orders/{id}/price-adjustment/respond  (البائع)
POST /orders/{id}/pay                       الدفع النهائي (مسار العروض)
GET  /orders/{id}/handshake-code            (المشتري) عرض الكود
POST /orders/{id}/handshake-code/verify     (البائع) إدخال الكود
POST /orders/{id}/confirm-receipt           (المشتري) تأكيد الاستلام
POST /orders/{id}/schedule-inspection       (البائع — مسار المزاد)
POST /orders/{id}/rate
GET  /orders/{id}/invoice                   تحميل الفاتورة PDF
```

## 4.6 البائع — الإنشاء والإدارة
```
POST /seller/listings                       إنشاء عرض/مزاد
PUT  /seller/listings/{id}                  تعديل (بشروط الحالة)
POST /seller/listings/{id}/pause · /resume · /republish
DELETE /seller/listings/{id}
GET  /seller/listings?type=&status=
GET  /seller/stats?period=today|week|month|year
GET  /seller/stats/export                   تصدير PDF
GET  /market-pulse                          مؤشر نبض السوق
```

## 4.7 المحفظة والشكاوى
```
GET  /wallet                                الرصيد + المحجوز + العمولات
GET  /wallet/transactions
GET  /wallet/withdrawals
POST /wallet/withdrawals                    طلب سحب
GET  /complaints  ·  POST /complaints  ·  GET /complaints/{id}
GET  /notifications  ·  POST /notifications/read-all  ·  DELETE /notifications/{id}
GET  /static/{slug}  ·  GET /faqs  ·  GET /settings/public
```

## 4.8 لوحة الإدارة (مسارات Web داخلية عبر Inertia)
مجموعات: `buyers` · `sellers` · `seller-verifications` · `listings` · `auctions` · `offers` · `orders` · `complaints` · `wallets` · `withdrawals` · `market-indices` · `notifications` · `settings` · `admin-users` · `roles` · `reports` · `categories` · `cities` · `contact` · `heatmaps` · `gmv`

---

# 5. المراحل والـ Sprints

> **افتراض:** Sprint = أسبوعان · فريق كامل يعمل بالتوازي (Backend + Mobile + Web + QA)

## المرحلة 0 — التحضير وحسم القرارات (Sprint 0) · أسبوعان

**الهدف:** ألّا يبدأ أي كود مالي قبل حسم الغموض.

| المهمة | المخرج |
|---|---|
| ورشة عمل مع العميل لحسم **القرارات العشرة** (§9) | وثيقة قرارات موقّعة |
| تجهيز البيئات (Dev / Staging / Prod) | 3 بيئات جاهزة |
| إعداد المستودعات و CI/CD | GitHub Actions / GitLab CI |
| اختيار وتأكيد بوابة الدفع + الحصول على بيانات Sandbox | حساب تجريبي فعّال |
| التقديم على تكامل **نفاذ** والحصول على وثائق التكامل | ⚠️ قد يستغرق أسابيع — يبدأ **اليوم الأول** |
| إعداد حساب SMS Gateway + Google Maps API | مفاتيح جاهزة |
| مراجعة تصاميم Figma وسدّ فجواتها (§9.11) | تصاميم مكتملة للمرحلة 1-3 |
| **تصميم لوحة الإدارة (22 شاشة غير مصممة)** | يبدأ بالتوازي |

**🚩 بوابة الخروج:** لا ننتقل للمرحلة 3 قبل توقيع وثيقة القرارات.

---

## المرحلة 1 — الأساس التقني (Sprints 1–2) · 4 أسابيع

| Sprint | المخرجات |
|---|---|
| **S1** | هيكل مشروع Laravel · Migrations كاملة لكل الجداول (§2) · Models + العلاقات · Seeders (مدن، تصنيفات، إعدادات) · Sanctum · هيكل Response موحّد · معالجة الأخطاء · Localization (ar/en) |
| **S2** | هيكل مشروعي Flutter (مشترك عبر Package مشترك) · Design System (ألوان، خطوط، مكوّنات) · التنقل والراوتنغ · طبقة API Client · إدارة الحالة · دعم RTL والثنائية اللغوية · هيكل لوحة الإدارة (Inertia + Vue + Tailwind RTL) |

**المخرج:** بنية تحتية جاهزة + "Hello World" يمر من التطبيق إلى الـ API إلى قاعدة البيانات.

---

## المرحلة 2 — الهوية والحسابات (Sprints 3–5) · 6 أسابيع

| Sprint | المخرجات |
|---|---|
| **S3** | OTP + SMS Gateway · تسجيل المشتري (3 خطوات) · شاشة الخريطة الكاملة (صلاحيات، GPS، Reverse Geocoding، حفظ العنوان) · تسجيل الدخول · حالة الزائر |
| **S4** | **تكامل نفاذ** · تسجيل البائع (6 خطوات) · رفع السجل التجاري · شاشة "قيد المراجعة" · مسار الرفض بـ SMS |
| **S5** | الملف الشخصي · عناويني · الإعدادات · تغيير رقم الجوال (5 خطوات) · حذف الحساب · الصفحات الثابتة · **لوحة الإدارة: إدارة المشترين + البائعين + مراجعة التوثيق + الصلاحيات + مستخدمي اللوحة** |

**المخرج:** مستخدم يستطيع التسجيل والتوثيق وإدارة حسابه بالكامل، والإدارة تراجعه.

---

## المرحلة 3 — المحرك المالي و Escrow (Sprints 6–8) · 6 أسابيع 🔴

> **أخطر مرحلة في المشروع** — تُبنى بمنهج **Ledger** ولا تبدأ قبل حسم القرارات المالية.

| Sprint | المخرجات |
|---|---|
| **S6** | جدول `transactions` كـ **Ledger غير قابل للتعديل** · `wallets` مشتقة عبر Observer · محرك حساب العمولة (مصدر واحد للحقيقة) · Idempotency Layer · اختبارات وحدة مالية شاملة |
| **S7** | تكامل بوابة الدفع (Initiate / Callback / Webhook) · معالجة **فشل الدفع** وإعادة المحاولة · `escrow_holds` · منطق الحجز والتحرير · Reconciliation Job يومي |
| **S8** | المحفظة (المشتري + البائع) · سجل المعاملات · طلبات السحب + التحقق من الآيبان · **لوحة الإدارة: المحافظ + العمليات المالية + مراجعة السحوبات** |

**🚩 بوابة الخروج:** اختبار مالي شامل — 20 سيناريو (حجز، تحرير، استرداد، خصم، تعويض، فشل، تكرار) بنتائج مطابقة 100%.

---

## المرحلة 4 — المزادات والمزايدة الحيّة (Sprints 9–12) · 8 أسابيع 🔴

| Sprint | المخرجات |
|---|---|
| **S9** | إنشاء المزاد (3 خطوات) · مراجعة الإدارة والنشر المجدول · صفحة مزاداتي (3 تبويبات) · تفاصيل المزاد للبائع |
| **S10** | **محرك المزايدة:** دفع الضمان → التأهيل → وضع مزايدة (Row Lock + التحقق من الحد الأدنى) · Reverb + قنوات البث · شاشة المزايدة الحيّة · قائمة المزايدين (أسماء مختصرة) · Toast التجاوز · مؤشر التنافس |
| **S11** | **إغلاق المزاد:** Scheduled Job + Queue · تحديد الفائز والمركز الثاني · شاشة الفوز · شاشة الخسارة · تبويبا معاينة الفوز/الخسارة · الدفع النهائي وإنشاء الطلب |
| **S12** | **السيناريوهات الثلاثة كاملة:** دفع الفائز / انتقال للمركز الثاني / إلغاء المزاد · مهل الدفع بـ Jobs مجدولة · خصم واسترداد الضمانات · سجل الفائزين · إعادة النشر · **لوحة الإدارة: إدارة المزادات + مراجعة النشر** |

**🚩 بوابة الخروج:** اختبار حمل — 500 مزايدة متزامنة على مزاد واحد بدون فقدان أو ترتيب خاطئ.

---

## المرحلة 5 — العروض المباشرة والمحادثات (Sprints 13–15) · 6 أسابيع

| Sprint | المخرجات |
|---|---|
| **S13** | إنشاء العرض المباشر (3 خطوات) · صفحة عروضي (3 تبويبات) · تفاصيل العرض · مراجعة الإدارة · **لوحة الإدارة: إدارة العروض المباشرة** |
| **S14** | نظام المحادثات (Realtime) · المرفقات · حالة الاتصال · Badge غير المقروء · تقديم عرض سعر · التفاوض |
| **S15** | زر "تأكيد عرض السعر" للبائع (سعر + كمية + موقع + موعد) · تأكيد/رفض المشتري · إنشاء الطلب · الشريط الأخضر · دورة التكرار حتى الاتفاق |

---

## المرحلة 6 — الطلبات ودورة التسليم (Sprints 16–17) · 4 أسابيع

| Sprint | المخرجات |
|---|---|
| **S16** | صفحة الطلبات (تبويبا العروض والمزادات بكل الحالات) · تفاصيل الطلب + Timeline · أزرار ديناميكية حسب المرحلة · تأكيد المعاينة · تحديد موعد المعاينة |
| **S17** | **كود الاستلام (Handshake OTP):** التوليد + العرض + التحقق + الأخطاء · تأكيد الاستلام · تحرير Escrow · طلب تعديل السعر (مرة واحدة) · التقييمات · توليد الفواتير PDF · **لوحة الإدارة: إدارة الطلبات + Audit Log** |

**🚩 بوابة الخروج:** رحلة كاملة End-to-End من إنشاء المزاد حتى وصول المال لمحفظة البائع.

---

## المرحلة 7 — الشكاوى والتحليلات والمحتوى (Sprints 18–19) · 4 أسابيع

| Sprint | المخرجات |
|---|---|
| **S18** | نظام الشكاوى كاملاً (رفع + حالات + إيقاف الطلب + قرارات الإدارة الثلاثة + التعويض) · نظام الإشعارات (داخلي + Push + سجل + بث إداري) |
| **S19** | صفحة الأداء والإحصائيات للبائع (4 بطاقات + Chart + فلتر + تصدير) · مؤشر نبض السوق (المصدران + الرسم + إغلاقات اليوم) · **لوحة الإدارة: مؤشر السوق + التقارير + التصنيفات + المدن + المحتوى + التواصل** |

---

## المرحلة 8 — التلميع والاختبار والإطلاق (Sprint 20 +) · 4–6 أسابيع

| المهمة | التفاصيل |
|---|---|
| العلامة المائية على الصور | معالجة تلقائية عند الرفع |
| Heat Maps + تقارير GMV | (يمكن تأجيلها لما بعد الإطلاق) |
| الترجمة الإنجليزية الكاملة | مراجعة كل النصوص |
| **اختبار QA شامل** | كل السيناريوهات + حالات الحافة |
| **اختبار الأمان** | Penetration Test — تركيز على المسارات المالية |
| **اختبار الأداء والحمل** | المزايدة المتزامنة + المحادثات |
| **UAT مع العميل** | جولتان مع دورة إصلاح |
| تحسين الأداء | فهارس، Cache، تحسين الاستعلامات |
| إعداد المراقبة | Sentry + Horizon Dashboard + Logs |
| النشر على المتاجر | App Store + Google Play (مراجعة قد تستغرق 1–3 أسابيع) |
| التوثيق والتسليم | وثائق API + دليل الإدارة + دليل النشر |

---

# 6. الجدول الزمني الإجمالي

| المرحلة | Sprints | الأسابيع | التراكمي |
|---|---|---|---|
| 0 — التحضير وحسم القرارات | S0 | 2 | 2 |
| 1 — الأساس التقني | S1–S2 | 4 | 6 |
| 2 — الهوية والحسابات | S3–S5 | 6 | 12 |
| 3 — المحرك المالي و Escrow | S6–S8 | 6 | 18 |
| 4 — المزادات والمزايدة الحيّة | S9–S12 | 8 | 26 |
| 5 — العروض والمحادثات | S13–S15 | 6 | 32 |
| 6 — الطلبات ودورة التسليم | S16–S17 | 4 | 36 |
| 7 — الشكاوى والتحليلات | S18–S19 | 4 | 40 |
| 8 — التلميع والإطلاق | S20+ | 4–6 | **44–46** |

> **ملاحظة:** المراحل 4 و5 و6 **قابلة للتوازي جزئياً** بين فريقين (فريق المزادات وفريق العروض) — ما يختصر المدة الفعلية إلى **28–34 أسبوعاً** بفريق كامل.

## 6.1 المسار الحرج (Critical Path)

```
تكامل نفاذ ──► تسجيل البائع ──► إنشاء المزاد ──► محرك المزايدة ──►
إغلاق المزاد ──► الدفع النهائي ──► الطلب ──► كود الاستلام ──► تحرير Escrow
```

**أطول اعتماد خارجي:** تكامل **نفاذ** — يجب أن يبدأ في **اليوم الأول** لأن الموافقة قد تستغرق 4–8 أسابيع.

---

# 7. الفريق المقترح

| الدور | العدد | التوظيف |
|---|---|---|
| **Tech Lead / Solution Architect** | 1 | كامل — مسؤول عن المعمارية والمراجعات |
| **Laravel Backend Developer** | 2–3 | كامل — أحدهم مخصص للمحرك المالي |
| **Flutter Developer** | 2–3 | كامل — واحد للمشتري وواحد للبائع |
| **Frontend Developer (Vue/Inertia)** | 1 | كامل — لوحة الإدارة |
| **UI/UX Designer** | 1 | كامل في المرحلة 0–2، جزئي بعدها |
| **QA Engineer** | 1 | كامل من المرحلة 2 |
| **DevOps** | 0.5 | جزئي — البيئات و CI/CD والمراقبة |
| **Project Manager / BA** | 1 | كامل — إدارة القرارات مع العميل |
| **الإجمالي** | **9–11** | |

---

# 8. المخاطر وخطط التخفيف

| # | المخاطرة | الاحتمال | الأثر | التخفيف |
|---|---|---|---|---|
| 1 | **تأخر الموافقة على تكامل نفاذ** | عالٍ | 🔴 يوقف مسار البائع بالكامل | التقديم في اليوم الأول + بناء **Mock Adapter** يسمح بمواصلة التطوير |
| 2 | **عدم حسم القرارات المالية** | عالٍ | 🔴 إعادة كتابة المحرك المالي | بوابة خروج إلزامية بعد المرحلة 0 |
| 3 | **Race Conditions في المزايدة المتزامنة** | متوسط | 🔴 مزايدات ضائعة أو ترتيب خاطئ | `lockForUpdate()` + DB Transaction + اختبار حمل إلزامي |
| 4 | **خطأ في احتساب العمولة أو Escrow** | متوسط | 🔴 خسارة مالية وفقدان ثقة | Ledger + مصدر واحد لحساب العمولة + Reconciliation يومي + تغطية اختبار 100% للمسار المالي |
| 5 | **لوحة الإدارة غير مصممة (22 شاشة)** | مؤكد | 🟠 ثلث النطاق بلا تصميم | بدء التصميم في المرحلة 0 بالتوازي + استخدام Design System جاهز |
| 6 | **رفض متجر Apple** | متوسط | 🟠 تأخير الإطلاق 2–4 أسابيع | مراجعة مبكرة للـ Guidelines خاصة بالمزادات والمدفوعات |
| 7 | **فجوات مسارات الفشل في التصميم** | مؤكد | 🟠 تأخير في كل Sprint | جلسة تصميم أسبوعية لسدّ الفجوات قبل Sprint بأسبوعين |
| 8 | **تكلفة WebSocket عند التوسع** | منخفض | 🟡 تكلفة تشغيلية | Reverb ذاتي الاستضافة + مراقبة الاتصالات المتزامنة |
| 9 | **زحف النطاق (Scope Creep)** | عالٍ | 🟠 تجاوز الجدول | تجميد النطاق بعد المرحلة 0 + كل إضافة تمر بـ Change Request |
| 10 | **تعارض المهل الزمنية مع مراجعة الدفع اليدوي** | متوسط | 🔴 إلغاء فوز أثناء مراجعة الإيصال | حسم قرار §9.3 — أو تجميد المهلة أثناء المراجعة |

---

# 9. القرارات العشرة المطلوبة من العميل ⚠️

> مستخرجة من تحليل الفجوات بين التصميم والوثيقة الفنية — **كل قرار هنا يمنع كتابة كود صحيح قبل حسمه**.

| # | القرار | لماذا يمنع التطوير | الموعد الأقصى |
|---|---|---|---|
| **9.1** | **نسبة العمولة النهائية ووعاء احتسابها** — التصميم يعرضها بثلاث قيم مختلفة (2.5% / 1% / 2%)، وعلى ثلاثة أوعية مختلفة | كل شاشة دفع في التطبيقين ومحرك المحفظة يتوقفان عليها | نهاية المرحلة 0 |
| **9.2** | **من يُفرج عن Escrow ومتى** — التصميم يعطي الزر للمشتري مرة وللبائع مرة، ويتجاوز كود الاستلام في مسار المزاد | **جوهر المنتج** — أربع شاشات متناقضة | نهاية المرحلة 0 |
| **9.3** | **هل التحويل البنكي معتمد؟** وما حكم المهل أثناء مراجعة الإيصال (24 ساعة)؟ | مسار كامل مصمَّم بلا مواصفات ويكسر مهل المزاد | نهاية المرحلة 0 |
| **9.4** | **هل توجد قاعدة انسحاب من المزاد باسترداد الضمان؟** التصميم يقولها والوثيقة تنفيها | ثغرة استغلال: دفع ← مزايدة ← انسحاب بلا عواقب | نهاية المرحلة 0 |
| **9.5** | **عدد محطات Timeline الطلب** (4 أم 6) وهل يختلف بين المزاد والعرض | يحدد آلة الحالات كاملة | بداية المرحلة 3 |
| **9.6** | **أثر رفض البائع لتعديل السعر** — إلغاء الصفقة أم بقاء الخيار للمشتري؟ | مساران متعارضان تماماً بين التصميم والوثيقة | بداية المرحلة 6 |
| **9.7** | **جدولة المعاينة** — أي مكوّن يُعتمد (تقويم شهري أم شريط أسبوعي)؟ ومن يحدد "الأيام المتاحة"؟ | مكوّنان متعارضان ومفهوم غير معرّف | بداية المرحلة 6 |
| **9.8** | **متى تبدأ لوحة تحكم الإدارة؟** 22 شاشة بلا تصميم | ثلث نطاق المشروع | فوراً |
| **9.9** | **التصنيفات المعتمدة** — 4 مواد أم القائمة الموسّعة (سيارات/بلاستيك/إلكترونيات)؟ | يؤثر على نبض السوق والتقارير والفلاتر | بداية المرحلة 1 |
| **9.10** | **كيان "الصفقة" (#DEAL)** — هل هو مستقل عن "الطلب" (#ORD)؟ | يغيّر نموذج البيانات جذرياً | بداية المرحلة 1 |

## 9.11 فجوات تصميمية إضافية يجب سدّها قبل كل مرحلة

| الفجوة | المرحلة المتأثرة |
|---|---|
| شاشة فشل الدفع + إعادة المحاولة | 3 |
| حالة "كود استلام غير صحيح" | 6 |
| شاشة سبب رفض الإدارة + زر "تعديل وإعادة التقديم" | 4، 5 |
| السيناريوهات الثلاثة للمزاد المنتهي | 4 |
| مسار رفض حساب البائع | 2 |
| نسخة "فرد" من بيانات البائع | 2 |
| حالات تعطيل الأزرار في التسجيل | 2 |
| شاشة الخريطة الكاملة للمشتري (موجودة كحالة تحميل فقط) | 2 |
| شاشة "عناويني" (البند موجود بلا شاشة) | 2 |
| محتوى تبويبَي معاينة الفوز/الخسارة (مرسومان فارغين) | 4 |
| الحالات الفارغة (Empty States) عبر كل الشاشات | كل المراحل |
| الشاشات بالإنجليزية (لا توجد أي شاشة إنجليزية في التصميم) | 8 |

---

# 10. معايير الجودة وبوابات الخروج

## 10.1 معايير القبول لكل Sprint
- [ ] كل الخصائص المستهدفة مطابقة لمعرّفاتها في `01-revalue-features-list.md`
- [ ] تغطية اختبارات ≥ 70% (**100% للمسارات المالية**)
- [ ] لا أخطاء `critical` أو `high` مفتوحة
- [ ] مراجعة كود (Code Review) لكل PR
- [ ] توثيق الـ APIs الجديدة
- [ ] اختبار على جهاز iOS حقيقي وجهاز Android حقيقي

## 10.2 بوابات الخروج الإلزامية

| البوابة | المعيار |
|---|---|
| **بعد المرحلة 0** | وثيقة القرارات العشرة موقّعة من العميل |
| **بعد المرحلة 3** | 20 سيناريو مالي ناجح 100% + Reconciliation يعمل |
| **بعد المرحلة 4** | اختبار حمل: 500 مزايدة متزامنة بلا فقدان |
| **بعد المرحلة 6** | رحلة End-to-End كاملة (مزاد ← مال في محفظة البائع) |
| **قبل الإطلاق** | UAT مقبول + Penetration Test نظيف + المتاجر موافقة |

## 10.3 قواعد اختبار خاصة بالمسار المالي
- كل عملية مالية لها **Unit Test** + **Feature Test** + **سيناريو تكامل**
- اختبار **Idempotency**: استدعاء نفس عملية الدفع مرتين لا يضاعف المبلغ
- اختبار **التزامن**: مزايدتان بنفس المبلغ في نفس الملّي ثانية
- اختبار **الاسترداد التسلسلي**: فائز 1 لا يدفع ← فائز 2 لا يدفع ← استرداد الجميع
- **Reconciliation Job** يومي يقارن مجموع القيود بأرصدة المحافظ ويُنذر عند أي فرق

---

# 11. خطة النشر والتشغيل

## 11.1 البيئات
| البيئة | الغرض |
|---|---|
| **Local** | تطوير — Docker Compose |
| **Dev** | تكامل مستمر — نشر تلقائي من فرع `develop` |
| **Staging** | نسخة مطابقة للإنتاج — UAT وبيانات تجريبية |
| **Production** | الإنتاج — نشر يدوي معتمد فقط |

## 11.2 البنية التشغيلية المقترحة
- **App Servers:** 2+ خلف Load Balancer
- **Database:** MySQL 8 مع Read Replica + نسخ احتياطي يومي (احتفاظ 30 يوماً)
- **Redis:** Cache + Sessions + Queues (مع Persistence)
- **Queue Workers:** عمليات منفصلة عبر Supervisor + Horizon
- **WebSocket:** Reverb على خادم منفصل
- **Storage:** S3-compatible + CDN للصور
- **Monitoring:** Sentry (الأخطاء) + Horizon (الطوابير) + Uptime Monitor

## 11.3 الوظائف المجدولة (Cron)
| المهمة | التكرار |
|---|---|
| نشر المزادات المجدولة | كل دقيقة |
| إغلاق المزادات المنتهية | كل دقيقة |
| فحص مهل دفع الفائزين | كل 5 دقائق |
| احتساب إغلاقات اليوم لنبض السوق | يومياً 00:05 |
| Reconciliation المالي | يومياً 02:00 |
| تنظيف OTP المنتهي | كل ساعة |
| النسخ الاحتياطي | يومياً 03:00 |

---

# 12. ما بعد الإطلاق (Roadmap مقترح)

| الأولوية | البند |
|---|---|
| P1 | Heat Maps + تقارير GMV المتقدمة |
| P1 | لوحة تحليلات موسّعة للبائع |
| P2 | نظام ولاء / تصنيف بائعين مميزين |
| P2 | مزادات مجدولة متكررة |
| P2 | تكامل شركات الشحن والنقل |
| P3 | واجهة ويب للمشترين (Web Marketplace) |
| P3 | API للشركات الكبرى (B2B Integration) |
| P3 | ذكاء اصطناعي لتقدير سعر السكراب من الصورة |

---

# 13. المخرجات النهائية للمشروع

- [ ] تطبيق المشتري منشور على App Store و Google Play
- [ ] تطبيق البائع منشور على App Store و Google Play
- [ ] لوحة تحكم الإدارة منشورة ومؤمّنة
- [ ] كود المصدر الكامل في مستودع العميل
- [ ] وثائق API (Postman Collection + OpenAPI)
- [ ] دليل استخدام لوحة الإدارة (عربي)
- [ ] دليل النشر والتشغيل
- [ ] سكربتات النسخ الاحتياطي والاستعادة
- [ ] تقرير اختبار الأمان
- [ ] تقرير اختبار الأداء
- [ ] فترة دعم وضمان متفق عليها (يُقترح 3 أشهر)