Core Module

Core Module هو حجر الأساس للنظام. يوفر البنية التحتية المشتركة بين جميع الـ Modules الأخرى.

الميزات الرئيسية:

• Status Management: نظام موحد لإدارة الحالات (Draft, Pending, Approved, etc.)
• Taxonomy System: تصنيف هرمي للبيانات (Categories, Tags, Types)
• Tax Management: إدارة الضرائب والرسوم (VAT 15%)
• Code Sequences: توليد أرقام تلقائية (INV-2025-0001)
• Outbox Events: Event-Driven Architecture للتكامل بين Modules
• Settings System: إعدادات النظام المركزية

Authentication Required: جميع الـ endpoints تتطلب Bearer Token

1. Status Management APIs

per_page: integer     // عدد النتائج (default: 15)
page: integer         // رقم الصفحة
model_type: string    // فلترة حسب نوع Model (invoice, appointment)
is_default: boolean   // الحالات الافتراضية فقط
is_final: boolean     // الحالات النهائية فقط

{
  "status": true,
  "data": [
    {
      "id": 1,
      "name": "Draft",
      "slug": "draft",
      "model_type": "invoice",
      "color": "gray",
      "icon": "fa-file",
      "is_default": true,
      "is_final": false
    }
  ],
  "meta": {
    "current_page": 1,
    "total": 25
  }
}

{
  "status": true,
  "data": {
    "invoice": [
      {"id": 1, "name": "Draft", "slug": "draft"},
      {"id": 2, "name": "Pending", "slug": "pending"},
      {"id": 3, "name": "Paid", "slug": "paid"}
    ],
    "appointment": [
      {"id": 10, "name": "Scheduled", "slug": "scheduled"},
      {"id": 11, "name": "Confirmed", "slug": "confirmed"}
    ]
  }
}

{
  "status": true,
  "data": [
    "invoice",
    "appointment",
    "admission",
    "prescription",
    "lab_test"
  ]
}

context: string (required)    // نوع الـ Model (invoice, appointment)

GET /api/core/statuses/by-context?context=invoice

{
  "name": "Approved",
  "slug": "approved",
  "model_type": "invoice",
  "color": "green",
  "icon": "fa-check-circle",
  "order": 3,
  "is_default": false,
  "is_final": false,
  "is_active": true
}

2. Taxonomy APIs

type: string          // نوع التصنيف (category, tag, type)
parent_id: integer    // التصنيفات الأبناء لـ parent معين
search: string        // بحث في الاسم

{
  "name": "Cardiology",
  "slug": "cardiology",
  "type": "category",
  "parent_id": 1,
  "description": "Heart and cardiovascular services"
}

3. Tax Management APIs

{
  "name": "VAT",
  "rate": 15.00,
  "type": "percentage",
  "is_active": true
}

4. Code Sequence APIs

{
  "key": "invoice",
  "prefix": "INV-",
  "padding": 4,
  "current_value": 0
}

{
  "status": true,
  "data": {
    "number": "INV-0001",
    "current_value": 1
  }
}

5. Outbox Event APIs

1. استخدام Status في الفواتير (Invoices)

use Modules\Core\Services\StatusService;

$statusService = app(StatusService::class);

// الحصول على حالة معينة
$draftStatus = $statusService->getBySlug('draft', 'invoice');

// تعيين حالة للفاتورة
$invoice->status_id = $draftStatus->id;
$invoice->save();

2. استخدام CodeSequence

use Modules\Core\Services\CodeSequenceService;

$sequenceService = app(CodeSequenceService::class);

// توليد رقم فاتورة جديد
$invoiceNumber = $sequenceService->getNext('invoice');
// Result: "INV-2025-0001"

// توليد رقم موعد
$appointmentNumber = $sequenceService->getNext('appointment');
// Result: "APT-20251206-0042"

3. استخدام Taxonomy

// الحصول على تصنيف محدد
$category = Taxonomy::where('slug', 'cardiology')->first();

// الحصول على التصنيفات الأبناء
$subCategories = $category->children;

✅ التوصيات

• استخدم Status بدلاً من enum: لمرونة أكبر في إدارة الحالات
• استخدم CodeSequence للأرقام: لا تقم بتوليد الأرقام يدوياً
• استخدم Taxonomy للتصنيفات: بدلاً من إنشاء جداول منفصلة
• Cache Status و Taxonomy: لتحسين الأداء

❌ تجنب

• إنشاء status يدوياً دون استخدام النظام
• حذف status مستخدمة في النظام
• تعديل slug للـ status بعد الاستخدام

Key Features

• ✅ Unified Status Management System
• ✅ Hierarchical Taxonomy System
• ✅ Tax Calculation Support
• ✅ Auto Number Generation
• ✅ Event-Driven Architecture
• ✅ Centralized Settings