تطبيق سند - الفوترة الإلكترونية

1) ما هو سند؟ ولماذا ستحتاجه؟

سند (Sanad) هو نظام امتثال (Compliance System) يعمل Self‑Hosted لمساعدة المنشآت في المملكة العربية السعودية على الالتزام الكامل بمتطلبات المرحلة الثانية للفوترة الإلكترونية (ZATCA Phase 2).

على عكس الحلول البسيطة، يقدم سند منظومة متكاملة تغطي:

• إصدار الفواتير الإلكترونية بمعيار UBL 2.1 وفق متطلبات ZATCA.
• توقيع XAdES‑EPES وربط الشهادة والـ SignedProperties بشكل صحيح.
• إنشاء QR (TLV) متوافق ومشفّر في الوقت الفعلي.
• Hash Chaining / ICV لضمان تتابع الفواتير وعدم العبث (ضمان السلامة).
• لوحة تحكم احترافية باللغة العربية لإدارة الفواتير، الشهادات، الأجهزة، وسجل التدقيق.
• API تكامل موحد لاستقبال الفواتير من أي مصدر (WooCommerce / Shopify / POS / ERP).

2) ماذا يضم المنتج (Package Contents)

عند استلامك النسخة التجارية من سند، ستجد الأجزاء التالية:

• تطبيق الويب (Laravel/PHP): لوحة التحكم + API التكامل + قواعد البيانات + إدارة الشهادات.
• خدمة التوقيع (FastAPI/Python): محرك تشفير متخصص للعمليات الحساسة والتوقيع الرقمي.
• قوالب PDF: إخراج PDF/A-3 مع إرفاق XML مدمج بشكل قانوني.
• ملفات الإعداد: قوالب جاهزة، ملفات Docker، وسكريبتات التثبيت التلقائي.

ملاحظة: سند ليس نظام SaaS سحابي، بل يتم تشغيله على خوادمك الخاصة (Dedicated/VPS/Shared) لضمان خصوصية البيانات الكاملة.

3) المميزات الرئيسية ونقاط القوة

نقاط قوة المنظومة:

• الامتثال: دعم كامل للفواتير الضريبية، المبسطة، إشعارات الدائن والمدين.
• التشغيل: معالج تثبيت Web-Wizard يقوم بتهيئة البيئة وقاعدة البيانات تلقائياً.
• المراقبة: أدوات Health/Metrics لتشخيص أعطال التكامل اللحظي.
• الصلاحيات: نظام RBAC متطور لإدارة وصول الموظفين والأنظمة.

4) الحماية والأمان

5) التكنولوجيا المستخدمة

يعتمد سند على معمارية هجينة (Hybrid Architecture) تضمن التوازن بين سهولة الإدارة وقوة الأداء التشفيري:

6) متطلبات التنصيب ومواصفات السيرفر

إضافات PHP المطلوبة:

openssl, pdo, mbstring, xml, bcmath, curl, fileinfo, gd, gmp, zip

7) معالج التثبيت (Installer Wizard)

بعد رفع ملفات التطبيق وربط اسم المجال (Domain) بالمجلد العام (public)، قم بزيارة الرابط التالي لبدء التثبيت:

سيرشدك المعالج خلال الخطوات التالية بالترتيب:

1. 1. الترحيب (Welcome): شاشة ترحيبية لبدء عملية تنصيب النظام.
2. 2. المتطلبات (Requirements): يقوم النظام بفحص إصدار PHP والإضافات (Extensions) المطلوبة مثل bcmath, ctype, json, mbstring, openssl, pdo, tokenizer, xml للتأكد من توافق السيرفر.
3. 3. الصلاحيات (Permissions): فحص إمكانية الكتابة على المجلدات الحساسة مثل storage/ و bootstrap/cache/ وملف .env لضمان استقرار التطبيق.
4. 4. بيئة العمل (Environment): إعداد اسم التطبيق ورابطه:
   • APP_NAME: اسم المنشأة أو التطبيق.
   • APP_URL: الرابط الكامل للموقع.
   • الوضع (Mode): اختيار Production (للاستخدام الفعلي) أو Local (للتطوير وتتبع الأخطاء).
5. 5. قاعدة البيانات (Database): إدخال بيانات الاتصال (Host, Port, Database, Username, Password) مع إمكانية اختبار الاتصال (Test Connection) قبل المتابعة.
6. 6. خدمة التوقيع (Python Service):
   • على VPS: تحديد المنفذ (مثل 8000) ومسار الخدمة. يمكن تفعيل خيار Generate Setup Script لإنشاء سكريبت يجهز البيئة الافتراضية (venv) وخدمة النظام (systemd) تلقائياً.
   • على استضافة مشتركة: إدخال الرابط المباشر لخدمة التوقيع إذا كانت مستضافة خارجياً.
7. 7. التأكيد (Confirm): مراجعة شاملة لكافة الإعدادات المدخلة قبل البدء الفعلي في التثبيت.
8. 8. تنفيذ التثبيت (Perform Install): يقوم النظام آلياً بـ:
   • توليد مفتاح التطبيق (APP_KEY).
   • بناء جداول قاعدة البيانات (Migrations).
   • تهيئة نظام الصلاحيات والأدوار (RBAC).
   • إنشاء حساب المدير الافتراضي (Admin User).
9. 9. النهاية (Finish): إتمام العملية وتوجيهك إلى صفحة تسجيل الدخول.

8) التثبيت عبر ZIP على VPS

للمحترفين أو مديري الخوادم (Ubuntu/Debian)، يمنحك هذا الخيار أقصى درجات التحكم والأداء.

المتطلبات المسبقة:

• OS: Ubuntu 22.04 LTS أو أحدث.
• Web Server: Nginx أو Apache.
• PHP: الإصدار 8.2 أو 8.3 مع الإضافات المطلوبة.
• Database: MySQL 8.0+ أو MariaDB 10.6+.
• Services: Redis (لإدارة الصفوف)، Python 3.10+ (لخدمة التوقيع).

خطوات التثبيت السريع:

1. رفع الملفات: قم برفع ملف release.zip إلى مسار /var/www/sanad وفك الضغط.
2. ضبط الصلاحيات:

   chown -R www-data:www-data /var/www/sanad
   chmod -R 775 /var/www/sanad/storage /var/www/sanad/bootstrap/cache

3. إعداد خدمة Python:

   cd /var/www/sanad/sanad_service
   pip3 install -r requirements.txt
   # ينصح باستخدام Supervisor أو Systemd لتشغيل الخدمة في الخلفية

4. ضبط Nginx: وجه الـ Document Root إلى مجلد /public.
5. المعالج: افتح المتصفح على رابط موقعك لاستكمال التثبيت عبر الـ Wizard.

9) التثبيت عبر Docker

الطريقة الأسهل والأكثر ضماناً لتشغيل النظام في بيئة معزولة ومطابقة للمعايير.

الخطوات:

1. تأكد من تثبيت Docker و Docker Compose Plugin على الخادم.
2. قم بفك ضغط ملف المشروع وانتقل للمجلد الرئيسي.
3. أنشئ ملف البيئة المخصص للإنتاج:

   cp .env.example .env.production
   # قم بتعديل القيم داخل الملف (DB_PASSWORD, APP_URL, ...)

4. شغل الحاويات (Containers):

   docker compose -f docker-compose.prod.yml up -d --build

5. النظام الآن يعمل! قم بالدخول إلى الرابط لتشغيل معالج التثبيت وإتمام تهيئة قاعدة البيانات.

10) التثبيت على استضافة مشتركة (cPanel)

للمحترفين: إعداد بيئة هجينة (Hybrid) بتشغيل Laravel كتطبيق PHP وتشغيل خدمة التوقيع كتطبيق Python مستقل (Passenger).

10.1 رفع ملفات النظام (Laravel)

1. ارفع ملف release.zip داخل مجلد public_html/sanad (أو أي مسار فرعي مناسب).
2. اضبط Document Root للدومين ليشير إلى: public_html/sanad/public.
3. أنشئ قاعدة بيانات MySQL ومستخدم جديد من لوحة cPanel.

10.2 تشغيل معالج التثبيت (مبدئي)

• افتح رابط موقعك: https://YOUR-DOMAIN/install
• أدخل بيانات قاعدة البيانات التي أنشأتها.
• في خطوة Python Service، أدخل الرابط المستقبلي للخدمة (مثلاً): https://api.YOUR-DOMAIN.com (سنقوم بإنشائه في الخطوة التالية).

10.3 إعداد خدمة Python (FastAPI App)

1. أنشئ Subdomain جديد للخدمة (مثلاً api.YOUR-DOMAIN.com).
2. اذهب إلى أداة Setup Python App في cPanel.
3. أنشئ تطبيقاً جديداً:
   • Python Version: اختر 3.10 أو أحدث.
   • Application Root: اختر المجلد الذي يحتوي على كود الخدمة (داخل مجلد مشروعك): sanad/sanad_service.
   • Application URL: اختر الدومين الفرعي الذي أنشأته (api...).
   • Startup File: اكتب passenger_wsgi.py.
   • Entry Point: اكتب application.
4. إنشاء ملف التشغيل: داخل مجلد sanad_service، أنشئ ملفاً جديداً باسم passenger_wsgi.py وضع فيه الكود التالي:

   import os
   import sys
   
   # Ensure app path uses current working directory
   sys.path.append(os.getcwd())
   
   from a2wsgi import ASGIMiddleware
   from main import app as fastapi_app
   
   # Passenger entry point
   application = ASGIMiddleware(fastapi_app)

5. اضغط Update أو Restart للتطبيق في cPanel.
6. تثبيت المكتبات: انسخ كود التفعيل (Virtual Environment) ونفذه في Terminal، ثم شغل: pip install -r requirements.txt

10.4 ربط الإعدادات (Environment Sync)

لضمان التخاطب الآمن بين النظامين، يجب تطابق المفاتيح:

أولاً: في ملف Laravel (.env)

SANAD_PYTHON_MODE=fastapi
SANAD_PYTHON_SERVICE_URL=https://api.YOUR-DOMAIN.com
SANAD_INTERNAL_TOKEN=ضع_كود_سري_طويل_هنا

ثانياً: في إعدادات Python App (Environment Variables)

أضف المتغيرات التالية في واجهة cPanel Python App:

• SANAD_INTERNAL_TOKEN: (نفس القيمة الموجودة في ملف .env)
• SANAD_ENVIRONMENT: production
• SANAD_DISABLE_FASTAPI_DOCS: true
• SANAD_ALLOWED_CALLER_IPS: عنوان IP السيرفر (Localhost أو Public IP).

10.5 إعداد المهام المجدولة (Cron Jobs)

أضف السطر التالي في Cron Jobs (مع تعديل المسار واسم المستخدم):

* * * * * /usr/local/bin/php /home/USER/public_html/sanad/artisan schedule:run >> /dev/null 2>&1

11) لوحة التحكم - شرح مفصل

تحتوي لوحة التحكم على أدوات متكاملة لإدارة منظومة الفوترة. تم تقسيم الصفحات حسب الوظيفة:

12) إعداد ZATCA (Onboarding)

تتم عملية ربط النظام مع هيئة الزكاة والضريبة والجمارك من خلال صفحة Admin → Sanad → Onboarding. هذه العملية ضرورية للحصول على شهادات التشفير (CSID) التي تسمح بتوقيع وإرسال الفواتير.

حالات التنبيه:

• Simulation Mode: استخدم هذا الوضع للتجربة دون إرسال بيانات مالية حقيقية للهيئة.
• Production Mode: الوضع الفعلي. يتطلب OTP من حسابك الرسمي على بوابة الهيئة.
• Renewal: يقوم النظام بتنبيهك قبل انتهاء صلاحية الشهادة لتجديدها بضغطة زر.

13) واجهة API البرمجية

يوفر سند واجهة RESTful API كاملة مصممة للتكامل السلس:

14) أسئلة شائعة

16) أخطاء شائعة وحلول

• خطأ: "Python Service Unreachable"
  الحل: تأكد من تشغيل سكريبت Python أو الـ Container الخاص بـ FastAPI وتحقق من الرابط في ملف .env.
• خطأ: "Hash Chain Broken"
  الحل: استخدم ميزة Recovery Mode في سجل الجهاز لإعادة بناء السلسلة من آخر فاتورة ناجحة.
• خطأ: "403 Forbidden" (cPanel)
  الحل: تأكد من إضافة IP السيرفر إلى قائمة SANAD_ALLOWED_CALLER_IPS في إعدادات البيئة لخدمة Python.

16) الدعم الفني

للحصول على المساعدة التقنية أو التدريب، نحن متاحون عبر: