# 📑 وثيقة الخطة التنفيذية والجدول الزمني الشامل لمشروع منصة ZATCA Tools SaaS

هذه الوثيقة تمثل المرجع الشامل (Master Roadmap) لتنفيذ منصة وسيط الفوترة الإلكترونية للمرحلة الثانية من هيئة الزكاة والضريبة والجمارك (ZATCA Phase 2).

---

## 🧭 1. النظرة العامة والهدف التجاري (Business & Technical Goal)

المنصة تعمل كـ **بوابة وسيطة ذكية (API Gateway & SaaS Middleware)** بين أنظمة الفواتير والمتاجر الإلكترونية (سلة، زد، ووكومرس، أودو، أنظمة الكاشير) وبين خوادم هيئة الزكاة (FATOORA Portal).

- **القيمة المقدمة للعميل:** التخلص من تعقيدات التشفير، توقيع الـ XML، الربط مع خوادم الهيئة، وسلسلة الفواتير بضغطة زر واحدة أو عبر استدعاء API بسيط.
- **نموذج الربح:** اشتراكات شهرية/سنوية مبنية على استهلاك عدد الفواتير (مثلاً: 500 فاتورة، 2,000 فاتورة، 10,000 فاتورة).

---

## ⏱️ 2. ملخص الجدول الزمني الإجمالي

| المرحلة | اسم المرحلة | المدة الزمنية | الحالة |
|:---:|---|:---:|:---:|
| **0** | **محرك التشفير والزكاة الأساسي (Core Engine)** | أسبوعان | **مكتمل 100% ✅** |
| **1** | **الموقع التعريفي + صفحات الأدوات المجانية (SEO)** | 7 - 10 أيام | قيد البدء ⏳ |
| **2** | **لوحة تحكم العميل (Client Dashboard) ومعالج الربط** | أسبوعان (14 يوم) | تالية |
| **3** | **لوحة تحكم الإدارة العليا (Super Admin Panel)** | أسبوع (7 أيام) | تالية |
| **4** | **بوابات الدفع وتطبيقات المتاجر (Plugins & Payments)** | أسبوعان (14 يوم) | تالية |
| **5** | **الاختبارات الشاملة والإطلاق السحابي (Go-Live)** | أسبوع (7 أيام) | تالية |
| **الإجمالي** | **من البداية حتى الإطلاق التجاري الكامل** | **حوالي 7 إلى 8 أسابيع** | |

---

## 🏗️ 3. تفصيل المراحل المتتالية خطوة بخطوة

```mermaid
graph TD
    M0[المرحلة 0: محرك التشفير والنواة ✅] --> M1[المرحلة 1: الموقع التعريفي والأدوات المجانية]
    M1 --> M2[المرحلة 2: لوحة تحكم العميل ومعالج الربط السريع]
    M2 --> M3[المرحلة 3: لوحة الإدارة لمتابعة العملاء]
    M3 --> M4[المرحلة 4: بوابات الدفع وإضافات المتاجر]
    M4 --> M5[المرحلة 5: التدشين السحابي داخل السعودية والإطلاق]
```

---

### 🟢 المرحلة 0: محرك التشفير والنواة (مكتملة بالكامل ✅)
- [x] توليد المفاتيح المشفرة `ECDSA secp256k1` وإنشاء ملف طلب الشهادة `CSR`.
- [x] بناء ملفات فواتير الزكاة المعيارية `UBL 2.1 XML` (Standard B2B + Simplified B2C + إشعارات الدائن والمدين).
- [x] التوقيع الرقمي `XAdES-BES` وتضمين الشهادات.
- [x] حساب الهاش `SHA-256` وسلسلة الفواتير ومنع التلاعب `Invoice Chaining (PIH)`.
- [x] توليد وقراءة كود الاستجابة السريعة `TLV Base64 QR Code`.
- [x] خدمات الاتصال بخوادم الهيئة (`Onboarding`, `Clearance`, `Reporting`).
- [x] بناء محرك طباعة فواتير الـ PDF المتوافقة مع الهيئة بترميز ثنائي للـ QR.
- [x] إعداد قاعدة البيانات و 33 اختباراً آلياً بنسبة نجاح 100%.

---

### 🟡 المرحلة 1: الموقع التعريفي والأدوات المجانية (المدة: 7 - 10 أيام)
**الهدف:** بناء واجهة احترافية للعلامة التجارية، وشرح مميزات المنصة، وجلب زيارات مجانية من محركات البحث (SEO).

#### المخرجات التقنية:
1. **الصفحة الرئيسية (Landing Page):**
   - تصميم متجاوب (Mobile First) باللغتين العربية والإنجليزية.
   - قسم توضيحي: "كيف تعمل المنصة في 3 خطوات؟".
   - جدول الباقات والأسعار مع إمكانية التبديل بين الدفع الشهري والسنوي.
   - قسم للمطورين يعرض مقتطفات برمجية (Code Snippets) بطرق إرسال الفواتير.
2. **مركز الأدوات المجانية لجلب العملاء (Free Growth Tools):**
   - **أداة فحص وفك تشفير كود QR للزكاة:** تتيح لأي شخص رفع صورة الفاتورة أو لصق كود الـ QR وعرض محتوياته بدقة.
   - **أداة التحقق من الرقم الضريبي (VAT Validator):** تدقيق صلاحية الرقم الضريبي للشركات السعودية.
   - **حاسبة ضريبة القيمة المضافة (15%):** حساب الضريبة الشاملة وغير الشاملة.
3. **صفحة التوثيق للمطورين (API Documentation):**
   - واجهة مدمجة عبر Swagger / Scramble توضح كيفية استخدام الـ REST API ونماذج الطلب والاستجابة.

---

### 🔵 المرحلة 2: لوحة تحكم العميل (Client Dashboard) (المدة: 14 يوم)
**الهدف:** توفير تجربة استخدام سهلة جداً لأصحاب المتاجر والمحاسبين دون الحاجة لخبرة تقنية.

#### الشاشات والمميزات:
1. **نظام التسجيل والدخول والتحقق (Auth & Onboarding):**
   - تسجيل حساب جديد للشركة وتحديد النشاط والرقم الضريبي.
2. **معالج الربط السريع مع الزكاة (ZATCA Onboarding Wizard):**
   - خطوة 1: اختيار الفرع أو نقطة البيع.
   - خطوة 2: طلب إدخال رمز الـ OTP الذي يجلبه العميل من بوابة "فاتورة".
   - خطوة 3: بضغطة زر واحدة، يتولى النظام توليد الشهادة واجتياز الفحص وجلب شهادة الإنتاج (Production CSID) وإظهار شارة "تم الربط والاعتماد بنجاح".
3. **مستكشف الفواتير (Invoices Hub):**
   - جدول يستعرض كافة الفواتير المصدرة مع الفلترة حسب (التاريخ، الفرع، نوع الفاتورة، الحالة).
   - توضيح حالة الفاتورة لدى الزكاة: (معتمدة، تم الإبلاغ، مرفوضة مع سبب الرفض بالتفصيل).
   - أزرار تحميل مباشرة:
     - تحميل ملف `XML` المعتمد والموقع.
     - تحميل ملف `PDF` الرسمي جاهز للطباعة متضمناً الـ QR والباركود.
4. **شاشة إصدار فاتورة يدوية (Manual Invoice Creator):**
   - لمن لا يمتلك متجراً أو نظام كاشير، يمكنه كتابة بنود الفاتورة وإصدارها مباشرة عبر المنصة.
5. **إدارة الأجهزة والفروع (Devices & Pos Management):**
   - إضافة وإلغاء تفعيل نقاط البيع ومتابعة عداد وسلسلة الفواتير لكل فرع.
6. **بوابة المطورين والمفاتيح (API Keys Management):**
   - إنشاء مفاتيح بيئة التجارب (`sk_test_...`) ومفاتيح الإنتاج (`sk_live_...`).
   - سجل التنبيهات والـ Webhooks عند نجاح أو فشل الفاتورة.

---

### 🟣 المرحلة 3: لوحة تحكم الإدارة العليا (Super Admin Panel) (المدة: 7 أيام)
**الهدف:** تمكينك كمالك للمنصة من التحكم الكامل ومتابعة نمو المشروع والمشتركين وصحة النظام.

#### الشاشات والمميزات:
1. **لوحة الإحصائيات العامة (Dashboard Analytics):**
   - إجمالي الفواتير المعالجة (اليوم، هذا الشهر، إجمالي).
   - إجمالي الإيرادات وعدد الشركات المشتركة.
   - معدل نجاح الاتصال مع خوادم هيئة الزكاة وسرعة الاستجابة.
2. **إدارة الشركات والعملاء (Tenants Management):**
   - عرض قائمة المشتركين، أرقامهم الضريبية، وحالة اشتراكاتهم.
   - تعديل رصيد الفواتير أو ترقية باقة عميل يدوياً.
   - حظر أو إيقاف مؤقت لأي حساب مخالف.
3. **مراقبة الطوابير والعمليات (Jobs & Queues Monitoring):**
   - تتبع الفواتير المعلقة في Redis طوابير المعالجة وإعادة المحاولة التلقائية.
   - سجل الأخطاء التقنية القادمة من بوابة الزكاة لتقديم الدعم الفني للعملاء بسرعة.
4. **إدارة الباقات والأسعار (Plans & Pricing):**
   - إنشاء وتعديل خطط الاشتراك (الحد الأقصى للفواتير، السعر، المميزات).

---

### 🟠 المرحلة 4: بوابات الدفع والتكامل مع المتاجر (المدة: 14 يوم)
**الهدف:** أتمتة تحصيل الأموال والوصول لأصحاب المتاجر الإلكترونية الجاهزة.

#### المخرجات:
1. **ربط بوابة دفع محلية معتمدة:**
   - التكامل مع بوابات مثل (ميسر Moyasar أو Tap Payments) لدعم الدفع عبر: **مدى (Mada)، البطاقات الائتمانية، و Apple Pay**.
   - تجديد الاشتراكات التلقائي وإصدار فواتير الاشتراك الشهرية للمشتركين.
2. **إضافات وتطبيقات المتاجر الإلكترونية:**
   - **إضافة WooCommerce (WordPress Plugin):** إضافة جاهزة يركبها العميل في موقعه بضغطة زر وتصدر الفواتير تلقائياً عند الدفع.
   - **تطبيق سلة (Salla Webhook App):** استقبال إشعار الطلب المكتمل وإصدار الفاتورة وتخزينها في حساب العميل.

---

### 🔴 المرحلة 5: الاختبارات الشاملة والتدشين السحابي (المدة: 7 أيام)
**الهدف:** تشغيل المنصة على خوادم سعودية معتمدة والامتثال التام للأنظمة الرسمية.

#### المخرجات:
1. **الاستضافة والامتثال لنظام حماية البيانات (PDPL):**
   - حجز خادم سحابي محلي (مثل Oracle Cloud في الرياض/جدة أو خوادم STC Cloud / Mobily).
   - نشر بيئة الإنتاج باستخدام Docker Compose التي قمنا بإعدادها مع تفعيل تشفير SSL / TLS.
2. **اختبارات الامتثال الحية (Live Sandbox Testing):**
   - اختبار ربط أجهزة حقيقية عبر منصة فاتورة واجتياز الـ Compliance Checks بنجاح.
3. **إطلاق المنصة رسمياً للعملاء (Go-Live).**

---

## 💡 4. ملخص تقنيات العمل المعتمدة (Tech Stack)

| المجال | التقنية المعتمدة | الفائدة والسبب |
|---|---|---|
| **الباك إند (Backend)** | PHP 8.3 + Laravel 13 | أداء استثنائي، أمان عالي، وسرعة فائقة في بناء أنظمة الـ SaaS. |
| **قواعد البيانات (Database)** | PostgreSQL 16 | أفضل قاعدة بيانات للعمليات المالية والحسابية والـ JSONB. |
| **إدارة الطوابير (Queues)** | Redis 7 + Laravel Queues | لمعالجة الفواتير في الخلفية دون جعل العميل ينتظر رد الزكاة. |
| **الواجهات والداشبورد** | Blade + Tailwind CSS + Livewire | كود موحد، أداء عالي، ودعم ممتاز للمحركات العربية والـ SEO. |
| **التشفير وحفظ المفاتيح** | AES-256-GCM + Master Key | عزل تام للمفاتيح الخاصة بكل عميل لمنع أي تسريب للبيانات. |
| **بيئة التشغيل السحابية** | Docker & Docker Compose | تشغيل ونقل المنصة على أي سيرفر سعودي في دقائق معدودة. |

---

## 🎯 5. من أين نبدأ الآن؟

التنفيذ يسير وفق الترتيب المنطقي للبرمجة:
- بما أن **المرحلة 0 (المحرك)** انتهت بنجاح كامل، الخطوة المنطقية التالية مباشرة هي **المرحلة 1: بناء واجهة الموقع العام (Landing Page) والأدوات المجانية**، تليها لوحة التحكم وتسجيل الدخول.