# وثيقة تحليل وتصميم نظام إدارة الذهب والمجوهرات

**حالة الوثيقة:** مسودة للاعتماد قبل بدء البرمجة  
**الإصدار:** 1.0  
**النطاق:** تحليل الأعمال والتصميم المنطقي والفني وخطة التنفيذ والتشغيل  
**لغة النظام:** العربية والإنجليزية، مع RTL/LTR  

> هذه الوثيقة هي بوابة اعتماد. لا يبدأ تنفيذ Laravel أو ترحيلات قاعدة البيانات قبل تثبيت القرارات المفتوحة في القسم الأخير واعتماد نطاق الإصدار الأول.

---

## 1. الملخص التنفيذي

النظام منصة تشغيل ومالية مركزية لمحلات وشركات الذهب والفضة والمجوهرات والألماس والأحجار الكريمة. يخدم فرعاً واحداً أو عدة فروع ومستودعات، ويعامل كل قطعة فريدة كوحدة مخزنية ومالية مستقلة لها رقم مسلسل ووزن وعيار وتكلفة وملكية وحالة وسجل حركة كامل.

المبدأ الحاكم هو أن كل عملية تجارية مؤثرة تنشئ، داخل معاملة قاعدة بيانات واحدة، ثلاثة آثار مترابطة عند الحاجة: مستنداً تشغيلياً، حركة مخزون غير قابلة للمحو، وأثراً محاسبياً مزدوج القيد. لا تُحذف الفواتير أو القيود المرحلة؛ بل تُلغى أو تُعكس بمستند مقابل وموافقة وسجل تدقيق.

يبنى النظام كتطبيق Laravel معياري Modular Monolith في البداية، بحدود وحدات واضحة وأحداث داخلية وواجهات تكامل مستقلة. هذا يقلل التعقيد التشغيلي مقارنة بالخدمات المصغرة، مع إبقاء الوحدات قابلة للفصل مستقبلاً. تستخدم PostgreSQL بوصفها الخيار الموصى به بسبب القيود، JSONB، الفهارس الجزئية، ودعم التزامن الجيد؛ ويمكن دعم MySQL 8 بعد مراجعة فروق القيود والفهارس.

### أهداف النجاح

- منع البيع المزدوج للقطعة الفريدة حتى مع الطلبات المتزامنة.
- تطابق رصيد المخزون الكمي والوزني مع دفتر الحركات.
- قابلية تتبع كل مبلغ ووزن من المستند المصدر إلى القيد والتدقيق.
- إغلاق يومي مستقل لكل فرع وصندوق مع تقارير موحدة.
- فصل قيمة المعدن والمصنعية والأحجار والضرائب والخصومات محاسبياً وتقريرياً.
- دعم أسعار تاريخية مثبتة على الفاتورة وعدم تغيير الفواتير القديمة.
- صلاحيات دقيقة مقيدة بالفرع والإجراء وحساسية البيانات.
- واجهة عملية وسريعة لنقطة البيع بالعربية والإنجليزية وعلى الهاتف والكمبيوتر.

### مؤشرات أداء مقترحة

- إنشاء فاتورة بيع عادية خلال أقل من ثانيتين عند الحمل الاسمي، باستثناء خدمات الدفع الخارجية.
- البحث عن قطعة بالباركود أو الرقم المسلسل خلال أقل من 500 مللي ثانية عند مئات آلاف القطع.
- صفر حالات بيع مزدوج ناجح في اختبارات التزامن.
- تطابق 100% بين مجموع دفتر حركة المخزون والرصيد المادي المحتسب.
- نجاح استعادة نسخة احتياطية تجريبية دورية ضمن RTO/RPO المعتمدين.

---

## 2. حدود النطاق والافتراضات

### 2.1 داخل النطاق الكامل

إدارة المؤسسة والفروع، المستخدمين والصلاحيات، المعادن والعيارات والأسعار، المنتجات والقطع والأحجار، المخزون والجرد والتحويل، العملاء والموردين، المبيعات ونقطة البيع والمرتجعات، المشتريات، الصناديق والبنوك، المحاسبة، الذهب المستعمل والاستبدال، الأمانات، التصنيع والورش، الصهر والتكرير، الصيانة، الطلبات الخاصة، الحجوزات، الأقساط والذمم، الولاء، الموارد البشرية والعمولات، المستندات والطباعة، التقارير، الإشعارات، المتجر الإلكتروني، التكاملات والتدقيق.

### 2.2 حدود MVP الموصى بها

يشمل الإصدار التشغيلي الأول:

1. المؤسسة والفروع والمستودعات والمستخدمون وRBAC والتدقيق.
2. العملات والضرائب ووحدات الوزن والمعادن والعيارات والأسعار التاريخية.
3. الأصناف والمتغيرات والقطع الفريدة والأحجار والصور والشهادات.
4. دفتر المخزون، الأرصدة، التحويل، الجرد، الحجز والملكية.
5. العملاء والموردون.
6. نقطة البيع، الدفع المتعدد، البيع الآجل، المرتجعات، وطباعة الفاتورة.
7. المشتريات والاستلام والإرجاع والمدفوعات.
8. الصندوق والورديات والبنوك ودليل الحسابات والقيود الآلية الأساسية.
9. لوحة تشغيل وتقارير أساسية وتنبيهات وموافقات وAPI أساسي.

يؤجل إلى ما بعد استقرار MVP: التصنيع المتقدم، الصهر والتكرير، الصيانة المتقدمة، الرواتب، الولاء، المتجر الإلكتروني الكامل، تكامل RFID والموازين، الفوترة الإلكترونية الخاصة بالدولة، والرسائل المدفوعة. تصمم حدودها وجداولها من البداية، لكن لا تظهر وظائف أو أزرار غير مكتملة.

### 2.3 افتراضات تصميمية

- نظام متعدد المؤسسات مستقبلاً، لكن الإصدار الأول يمكن تشغيله لمؤسسة واحدة؛ لذلك تحمل الجداول التجارية `organization_id` منذ البداية.
- العملة الوظيفية تحدد لكل مؤسسة، مع دعم عملة معاملة وعملة تسوية وفروق صرف.
- الزمن يخزن UTC ويعرض وفق منطقة الفرع.
- الوزن الأساسي يخزن بالغرام، مع وحدة إدخال وعامل تحويل محفوظين لأغراض التدقيق.
- الملكية واحدة من: ملك الشركة، أمانة مورد، أمانة عميل/صيانة، أو طرف ثالث.
- لا تعتمد الأرصدة المخزنية أو المحاسبية على حقول قابلة للتعديل فقط؛ مصدر الحقيقة هو دفتر حركات مرحّل.

### 2.4 خارج النطاق ما لم يعتمد لاحقاً

- تحديد الضرائب أو الفوترة الإلكترونية لدولة بعينها.
- إعطاء نصائح امتثال AML/KYC بديلة عن مراجعة قانونية محلية.
- تشغيل أجهزة محددة قبل معرفة البروتوكول والطراز والتعريفات.
- توحيد رواتب وقوانين عمل دول متعددة في نموذج واحد دون إعدادات محلية.

---

## 3. الوحدات الرئيسية وخريطة الاعتماد

| المجال | الوحدات | يعتمد على |
|---|---|---|
| المنصة | المؤسسات، الفروع، الإعدادات، التسلسلات، اللغات، الملفات | لا شيء |
| الهوية والرقابة | المستخدمون، الموظفون، الأدوار، الصلاحيات، الجلسات، 2FA، التدقيق | المنصة |
| البيانات المرجعية | العملات، الصرف، الضرائب، الوحدات، المعادن، العيارات، الأسعار | المنصة والهوية |
| الكتالوج | التصنيفات، المنتجات، المتغيرات، القطع، الأحجار، الشهادات، الوسائط | البيانات المرجعية |
| المخزون | الأرصدة، دفتر الحركة، الحجز، التحويل، الجرد، الملكية، المواقع | الكتالوج والفروع |
| الأطراف | العملاء، الموردون، الورش، جهات الاتصال، KYC والائتمان | المنصة |
| المبيعات | POS، التسعير، الفواتير، الدفعات، المرتجعات، الاستبدال | المخزون والأطراف والأسعار |
| المشتريات | الطلبات، أوامر الشراء، الاستلام، الفواتير، الإرجاع | المخزون والموردون |
| الخزينة | الصناديق، الورديات، القبض، الصرف، البنوك، التسويات | الفروع والأطراف |
| المحاسبة | دليل الحسابات، القيود، الضرائب، الفترات، مراكز التكلفة | كل الوحدات المالية |
| المتخصصة | مستعمل، أمانات، صيانة، تصنيع، ورش، صهر، طلبات خاصة | المخزون والمحاسبة |
| الائتمان والتسويق | أقساط، ذمم، ولاء، قسائم، بطاقات هدايا، حجوزات | المبيعات والعملاء |
| الموارد البشرية | الموظفون، الرواتب، الحضور، العمولات | الهوية والمحاسبة |
| القنوات والتكامل | المتجر، API، أجهزة، دفع، أسعار، رسائل، فوترة | الوحدات الأساسية |
| القرار | Dashboard، تقارير، تصدير، جدولة، إشعارات | مستودع القراءة/الوحدات |

تدفق الاعتماد العام:

```mermaid
flowchart LR
  A["المنصة والهوية"] --> B["البيانات المرجعية"]
  B --> C["الكتالوج والأطراف"]
  C --> D["المخزون"]
  D --> E["المبيعات والمشتريات"]
  E --> F["الخزينة والمحاسبة"]
  F --> G["الوحدات المتخصصة"]
  G --> H["التقارير والتكاملات"]
```

---

## 4. المستخدمون والأدوار

| الدور | نطاق العمل المعتاد | القيود الأساسية |
|---|---|---|
| مالك النظام | كل المؤسسة | العمليات الحساسة تتطلب 2FA ولا يتجاوز التدقيق |
| المدير العام | كل الفروع والتقارير | لا يغير القيود المرحلة مباشرة |
| مدير الفرع | فرع أو فروع معينة | لا يرى فروعاً غير مسندة إليه |
| المحاسب | المحاسبة والضرائب والتسويات | فصل إنشاء القيد عن اعتماده حسب السياسة |
| أمين الصندوق | صندوق ووردية محددان | لا يعمل خارج وردية مفتوحة |
| مسؤول المبيعات | POS والعملاء والحجوزات | التكلفة والخصم حسب الصلاحية |
| مسؤول المشتريات | الموردون ودورة الشراء | الاعتماد منفصل عند تخطي الحدود |
| مسؤول المستودع | الاستلام والتحويل والجرد | الإرسال والاستلام يمكن فصلهما |
| الصائغ/الفني | التصنيع والصهر | يرى المواد والمهام المسندة فقط |
| مسؤول الصيانة | أوامر الصيانة والتسليم | لا يعدّل الدفعات دون صلاحية خزينة |
| الموارد البشرية | الموظفون والرواتب | لا يرى المبيعات التفصيلية إلا للعمولة |
| المدقق المالي | قراءة وتصدير وتدقيق | وصول للقراءة فقط وسجل تصدير |
| خدمة العملاء | بيانات العملاء والحالة | إخفاء الرصيد والهوية حسب الحاجة |
| مدير المتجر الإلكتروني | النشر والطلبات | لا يحرر تكلفة المخزون |
| مستخدم مخصص | صلاحيات مجمعة | مبدأ أقل صلاحية |

يكون الدور قالباً، بينما القرار الفعلي للصلاحية هو: **إجراء + مورد + نطاق مؤسسة/فرع/مستودع + شروط سياقية** مثل قيمة الخصم أو حالة المستند أو امتلاك الصندوق.

---

## 5. حالات الاستخدام الرئيسية

### 5.1 الإدارة والهوية

- إنشاء مؤسسة وفرع ومستودع وصندوق وتسلسل مستندات.
- دعوة مستخدم، ربطه بموظف، تعيين أدوار وفروع ومستودعات.
- تسجيل الدخول و2FA وإدارة الأجهزة والجلسات.
- مراجعة سجل التدقيق ومحاولات الدخول والتصدير والطباعة.

### 5.2 الأسعار والكتالوج

- تعريف معدن وعيار ووحدة وتحويل وسعر شراء/بيع بحسب الفرع والعملة.
- استيراد سعر خارجي ثم مراجعته أو تفعيله تلقائياً وفق السياسة.
- إنشاء منتج ومتغير وقطع مسلسلة بأوزان وتكاليف مستقلة.
- تسجيل حجر وشهادته وربطه بقطعة أو حفظه منفصلاً.
- حساب المعدن الخالص والتكلفة وسعر البيع والمصنعية والضريبة.

### 5.3 المخزون

- استلام قطعة، نقلها بين مواقع التخزين، حجزها، فك الحجز، وتسويتها.
- طلب تحويل واعتماده وشحنه واستلامه مع توثيق الفروقات.
- بدء جرد، تجميد نطاقه، العد، المقارنة، واعتماد التسويات.
- تتبع سلسلة حيازة قطعة من المصدر إلى البيع/الصهر/الإرجاع.

### 5.4 المبيعات

- فتح وردية، مسح قطعة، تثبيت سعر المعدن، تسعيرها، تطبيق خصم ضمن الحد.
- طلب موافقة على بيع تحت التكلفة أو خصم كبير.
- قبض متعدد الطرق والعملات وإصدار وترحيل الفاتورة.
- تعليق مسودة أو حجز قطعة مع انتهاء صلاحية.
- إرجاع كلي/جزئي مع إعادة المخزون وعكس القيود والعمولة.
- استبدال ذهب مستعمل بمنتج جديد وتسوية الفرق.

### 5.5 المشتريات

- طلب شراء، عرض، أمر، استلام وفحص، فاتورة، مطابقة ودفع.
- تسجيل فروق العدد والوزن والعيار والتكلفة.
- إرجاع للمورد وإشعار دائن/مدين وعكس الأثر.

### 5.6 الخزينة والمحاسبة

- فتح/إغلاق وردية بجرد نقدي وفروق وموافقة عند اللزوم.
- قبض وصرف وتحويل بين صندوق وبنك وتسوية كشف البنك.
- توليد قيود آلية، مراجعتها، ترحيلها، وعكسها.
- إغلاق فترة ومنع الترحيل بأثر رجعي إلا بموافقة.

### 5.7 الوحدات المتخصصة

- شراء وفحص ذهب مستعمل وتحديد وجهته وإثبات هوية البائع.
- إدارة أمانة مورد وبيعها وتسويتها أو إرجاعها.
- استلام صيانة وتسعيرها وتتبعها وتسليمها.
- إصدار أمر تصنيع وتسليم المواد وتتبع الفاقد والتكلفة.
- إنشاء دفعة صهر وتحويل المدخلات إلى ناتج وفاقد ورسوم.
- إنشاء أقساط وتحصيلها ومتابعة المتأخر.

---

## 6. قواعد العمل

### 6.1 سلامة المستندات

1. المستند المالي بعد الترحيل immutable؛ التصحيح بمستند عكسي مرتبط بالأصل.
2. كل إلغاء أو إرجاع أو تسوية أو تغيير تكلفة يحتاج سبباً منظماً وملاحظة، وقد يحتاج موافقة.
3. أرقام المستندات فريدة ضمن المؤسسة والفرع ونوع المستند والسنة المالية، وتولد داخل قفل ذري.
4. تحفظ نسخة Snapshot من السعر والضريبة وسعر الصرف والعيار والتكلفة لحظة الترحيل.
5. لا تُعاد حسبة مستند تاريخي عند تغير إعداد أو سعر لاحق.

### 6.2 القطعة والمخزون

6. الرقم المسلسل والباركود الفعال فريدان داخل المؤسسة.
7. القطعة الفريدة لا توجد في أكثر من موقع أو حالة بيع فعالة في اللحظة نفسها.
8. البيع يقفل سجل القطعة `SELECT ... FOR UPDATE` ويتحقق من `available` والملكية والحجز والفرع.
9. لا يصبح رصيد المخزون سالباً إلا لنوع مخزون يسمح بذلك صراحةً وبموافقة.
10. كل حركة تحمل كمية ووزناً قبل/بعد، مصدر/وجهة، ملكية، مستند مصدر، مستخدم، ووقتاً.
11. مخزون الأمانة منفصل منطقياً ومحاسبياً عن ملك الشركة.
12. تعديل وزن/عيار قطعة مباعة ممنوع؛ يسجل تصحيح مؤرخ دون تغيير Snapshot الفاتورة.
13. فروقات التحويل والجرد والصهر لا ترحل دون سبب، وحسب الحد دون موافقة أو معها.

### 6.3 الأوزان والتسعير

14. تستخدم `DECIMAL(20,6)` افتراضياً للأوزان بالغرام، وقابلية العرض/التقريب إعداد مستقل.
15. المبالغ تستخدم `DECIMAL(20,4)` داخلياً وتعرض وفق منازل العملة؛ لا يستخدم Float.
16. `net_metal_weight = gross_weight - gemstone_weight - other_material_weight` مع رفض الناتج السالب.
17. `fine_weight = net_metal_weight × purity_ratio`.
18. `metal_value = fine_weight × base_pure_metal_price` أو المعادلة المعتمدة للعيار.
19. التكلفة الفعلية للقطعة = معدن + أحجار + تصنيع + شحن + مصروفات موزعة، وكل مكون منفصل.
20. الربح = صافي الإيراد قبل/بعد الضريبة وفق تعريف التقرير ناقص تكلفة البضاعة الفعلية؛ يجب تسمية المقياس بوضوح.
21. قواعد التقريب تنفذ في نقطة واحدة وتختبر؛ لا تقرب الأوزان الوسيطة بلا سياسة.

### 6.4 المبيعات والدفع

22. مجموع الدفعات + الرصيد الآجل + قيمة الاستبدال يجب أن يساوي إجمالي الفاتورة ضمن سماحية التقريب.
23. كل دفعة بعملة أجنبية تحفظ المبلغ والعملة وسعر الصرف والمبلغ الوظيفي.
24. المرتجع لا يتجاوز الكمية/القطع والقيمة القابلة للإرجاع من الأصل.
25. المرتجع يعيد القطعة لحالة فحص أولاً، ولا يجعلها متاحة تلقائياً إن تطلبت فحصاً.
26. إرجاع البيع يعكس COGS والمخزون والضريبة والإيراد والعمولة بنسبته.

### 6.5 المحاسبة والرقابة

27. كل قيد مرحل متوازن: مجموع المدين = مجموع الدائن بالعملة الوظيفية.
28. لا يسمح بالترحيل إلى فترة مغلقة؛ فتحها يحتاج صلاحية وموافقة وتدقيقاً.
29. منشئ عملية حساسة لا يكون موافقها النهائي عندما تفرض سياسة فصل المهام.
30. سجلات التدقيق append-only للمستخدمين، مع حماية إدارية وفحص سلامة دوري.

### 6.6 حالات القطعة الفريدة

```mermaid
stateDiagram-v2
  [*] --> Draft
  Draft --> Available: استلام وترحيل
  Available --> Reserved: حجز
  Reserved --> Available: انتهاء/إلغاء
  Available --> InTransfer: شحن تحويل
  InTransfer --> Available: استلام
  Available --> Sold: ترحيل بيع
  Sold --> Inspection: مرتجع
  Inspection --> Available: قبول إعادة البيع
  Inspection --> InRepair: يحتاج صيانة
  Available --> InRepair: أمر صيانة داخلي
  Available --> InManufacturing: تحويل تصنيع
  Available --> InMelting: اعتماد صهر
  InRepair --> Available: اكتمال
  InManufacturing --> Available: ناتج
  InMelting --> Consumed: صهر
  Available --> WrittenOff: فاقد/تلف معتمد
```

---

## 7. مخطط ERD منطقي

المخطط التالي يركز على النواة التشغيلية. الجداول المتخصصة مذكورة في قاموس البيانات بعده.

```mermaid
erDiagram
  ORGANIZATIONS ||--o{ BRANCHES : owns
  BRANCHES ||--o{ WAREHOUSES : contains
  BRANCHES ||--o{ CASH_REGISTERS : contains
  USERS }o--o{ ROLES : assigned
  USERS }o--o{ BRANCHES : scoped_to
  ROLES }o--o{ PERMISSIONS : grants
  METALS ||--o{ PURITIES : defines
  METALS ||--o{ METAL_PRICES : priced
  PURITIES ||--o{ METAL_PRICES : qualifies
  CURRENCIES ||--o{ METAL_PRICES : denominates
  CATEGORIES ||--o{ PRODUCTS : groups
  PRODUCTS ||--o{ PRODUCT_VARIANTS : has
  PRODUCT_VARIANTS ||--o{ PRODUCT_SERIALS : instances
  PRODUCT_SERIALS ||--o{ INVENTORIES : located_as
  WAREHOUSES ||--o{ INVENTORIES : holds
  PRODUCT_SERIALS ||--o{ INVENTORY_MOVEMENTS : moved
  WAREHOUSES ||--o{ INVENTORY_MOVEMENTS : source_or_target
  CUSTOMERS ||--o{ SALES : buys
  BRANCHES ||--o{ SALES : issues
  SALES ||--|{ SALE_ITEMS : contains
  PRODUCT_SERIALS ||--o| SALE_ITEMS : sold_as
  SALES ||--o{ SALE_PAYMENTS : settled_by
  SALES ||--o{ SALE_RETURNS : may_have
  SUPPLIERS ||--o{ PURCHASES : supplies
  PURCHASES ||--|{ PURCHASE_ITEMS : contains
  PURCHASES ||--o{ PURCHASE_PAYMENTS : settled_by
  STOCK_TRANSFERS ||--|{ STOCK_TRANSFER_ITEMS : contains
  PRODUCT_SERIALS ||--o{ STOCK_TRANSFER_ITEMS : transferred
  CHART_OF_ACCOUNTS ||--o{ JOURNAL_ENTRY_LINES : posted_to
  JOURNAL_ENTRIES ||--|{ JOURNAL_ENTRY_LINES : contains
  FISCAL_PERIODS ||--o{ JOURNAL_ENTRIES : includes
  SALES ||--o{ JOURNAL_ENTRIES : originates
  PURCHASES ||--o{ JOURNAL_ENTRIES : originates
  APPROVAL_REQUESTS ||--o{ APPROVAL_STEPS : requires
  USERS ||--o{ APPROVAL_DECISIONS : decides
  ATTACHMENTS }o--|| ATTACHABLES : polymorphic
  AUDIT_LOGS }o--|| AUDITABLES : records
```

---

## 8. تصميم قاعدة البيانات وقاموس المجالات

### 8.1 معايير عامة

- مفاتيح داخلية `bigint` للأداء، و`uuid` عام غير قابل للتخمين للمستندات المعروضة خارجياً.
- جميع الجداول التابعة تحمل `organization_id` وفهارس مركبة تبدأ به.
- أعمدة معيارية: `created_at`, `updated_at`, `deleted_at` حيث يناسب، و`created_by`, `updated_by` للسجلات الحساسة.
- حالات العمل Codes أو Enums على مستوى التطبيق مع `CHECK` على القيم المستقرة.
- المبالغ `DECIMAL(20,4)` والوزن `DECIMAL(20,6)` والنسب `DECIMAL(9,6)` وأسعار الصرف `DECIMAL(20,10)`.
- لا Soft Delete لحركات المخزون والدفعات والقيود والتدقيق؛ تستخدم حالة إلغاء/عكس.
- فهارس على المفاتيح الأجنبية، والحالة/التاريخ، والفرع/التاريخ، وأعمدة البحث المتكرر.
- Idempotency key فريد لكل مؤسسة وقناة للطلبات المالية عبر API.

### 8.2 المؤسسة والهوية

| الجداول | الغرض وأهم القيود |
|---|---|
| `organizations` | بيانات الشركة، العملة الوظيفية، المنطقة الزمنية، الحالة |
| `branches` | كود فريد للمؤسسة، منطقة زمنية وعنوان وتسلسلات |
| `warehouses`, `warehouse_locations` | مستودعات ومواقع رف/خزنة، نوع وملكية مسموحة |
| `cash_registers`, `shifts` | صندوق، وردية، رصيد افتتاح/إغلاق وحالة وفروق |
| `users`, `employees` | حساب المستخدم منفصل عن ملف الموظف |
| `roles`, `permissions` | قوالب RBAC وصلاحيات بصيغة `domain.action` |
| `role_user`, `permission_role` | تعيينات الأدوار والصلاحيات |
| `branch_user`, `warehouse_user` | نطاق الوصول المكاني مع صلاحيات إضافية اختيارية |
| `user_sessions`, `login_attempts`, `two_factor_methods` | إدارة الأجهزة والأمان |
| `settings`, `document_sequences` | إعدادات typed وتسلسل ذري لكل فرع/نوع/سنة |

### 8.3 المرجعيات والتسعير

| الجداول | الغرض وأهم القيود |
|---|---|
| `currencies`, `exchange_rates` | ISO code فريد، سعر تاريخي ومصدر وفترة صلاحية |
| `units`, `unit_conversions` | وحدة أساس وعامل تحويل موجب |
| `metals`, `purities` | معدن، كود عيار، نسبة نقاوة بين 0 و1 |
| `metal_prices` | معدن/عيار/فرع/عملة/نوع سعر/valid_from؛ سجل تاريخي لا يستبدل |
| `price_alert_rules`, `price_locks` | حدود التنبيه وإيقاف البيع وتثبيت السعر للصفقة |
| `taxes`, `tax_rates` | نوع الضريبة، شاملة/مضافة، نطاق وتواريخ نفاذ |
| `pricing_policies`, `pricing_rules` | طريقة المصنعية والهوامش والحدود بحسب الفئة/الفرع |

### 8.4 المنتجات والأحجار

| الجداول | الغرض وأهم القيود |
|---|---|
| `categories`, `brands`, `collections` | هياكل قابلة للتخصيص والترجمة |
| `products` | تعريف عام: اسم، وصف، تصنيف، طريقة التسعير |
| `product_variants` | المقاس/اللون/التصميم وSKU |
| `product_attributes`, `attribute_values`, `variant_attribute_values` | خصائص ديناميكية دون أعمدة عشوائية |
| `product_serials` | القطعة الفريدة: serial، barcode، RFID، أوزان، عيار، تكاليف، حالة، ملكية |
| `product_cost_components` | معدن/حجر/تصنيع/شحن/إضافي مع المصدر والتاريخ |
| `product_images` | مسار خاص، ترتيب، checksum، metadata |
| `gemstones` | النوع، طبيعي/مخبري، 4Cs، قيراط، أبعاد، تكلفة وحالة |
| `gemstone_certificates`, `laboratories` | مختبر وشهادة ورابط تحقق وملف محمي |
| `product_gemstones` | ربط حجر أو مجموعة حجر بقطعة، العدد والوزن |
| `warranties` | سياسة ورقم وضمان وتواريخ وحالة |

قيود تحقق رئيسية: الأوزان غير سالبة؛ مجموع أوزان الحجر والمواد لا يتجاوز الإجمالي؛ الرقم المسلسل فريد؛ القطعة ذات `tracking_type=serial` لا تتجاوز كميتها 1.

### 8.5 المخزون

| الجداول | الغرض وأهم القيود |
|---|---|
| `inventories` | رصيد سريع لكل منتج/قطعة/موقع/ملكية؛ يعاد بناؤه من الدفتر |
| `inventory_movements` | دفتر append-only: نوع، مصدر، وجهة، qty، weights، cost، reference |
| `inventory_movement_lines` | تفصيل المكونات عند الحركة المجمعة |
| `reservations` | قناة، عميل، قطعة، انتهاء، حالة؛ قيد فريد لحجز فعال للقطعة |
| `stock_transfers`, `stock_transfer_items` | طلب/اعتماد/شحن/استلام وفروقات |
| `stock_counts`, `stock_count_items` | نطاق الجرد، المتوقع، المعدود، الفروق والموافقات |
| `inventory_adjustments` | تسويات فاقد/تلف/تصحيح مع السبب والقيد |
| `ownership_accounts` | مالك المخزون وعقد الأمانة إن وجد |

يكون `inventory_movements` المصدر النهائي، و`inventories` إسقاطاً سريعاً يحدث في المعاملة نفسها. مهمة مصالحة دورية تعيد جمع الدفتر وتبلغ عن أي فرق ولا تصلحه بصمت.

### 8.6 المبيعات والمشتريات والأطراف

| الجداول | الغرض وأهم القيود |
|---|---|
| `customers`, `customer_addresses`, `customer_identities` | ملف العميل، KYC مشفر، حد ائتمان وموافقة تسويق |
| `suppliers`, `supplier_contacts`, `supplier_accounts` | المورد وشروطه وتقييمه |
| `sales`, `sale_items` | رأس الفاتورة وSnapshot تفصيلي للمعدن/العيار/الأوزان/السعر/التكلفة |
| `sale_payments`, `payments`, `payment_allocations` | دفعات عامة وتخصيصها للمستندات والعملات |
| `sale_returns`, `sale_return_items` | إرجاع مرتبط بالأصل، سبب وفحص وأثر عكسي |
| `purchase_requests`, `supplier_quotes`, `purchase_orders` | دورة ما قبل الشراء |
| `goods_receipts`, `goods_receipt_items` | استلام وفحص وفروقات |
| `purchases`, `purchase_items`, `purchase_payments` | فاتورة المورد ودفعاتها |
| `purchase_returns`, `purchase_return_items` | إرجاع المورد |
| `trade_ins`, `trade_in_items`, `used_gold_purchases` | استبدال/شراء مستعمل وفحص ووجهة |
| `coupons`, `gift_cards`, `gift_card_transactions` | قسائم وأرصدة محكومة بدفتر |
| `loyalty_accounts`, `loyalty_transactions` | نقاط بدفتر append-only |
| `installments`, `installment_payments` | جدول استحقاق وتحصيل ومتأخرات |

### 8.7 الخزينة والمحاسبة

| الجداول | الغرض وأهم القيود |
|---|---|
| `bank_accounts`, `bank_transactions`, `bank_reconciliations` | حسابات وحركات وتسويات |
| `receipts`, `receipt_allocations` | سند قبض وتخصيصه |
| `expenses`, `expense_categories` | مصروف وضرائب وموافقات |
| `chart_of_accounts` | دليل هرمي، نوع وطبيعة وحساب رقابي |
| `cost_centers`, `accounting_dimensions` | فرع/قسم/مشروع وسمات تحليلية |
| `fiscal_years`, `fiscal_periods` | حالات open/soft_close/closed |
| `journal_entries`, `journal_entry_lines` | قيود متوازنة، مصدر polymorphic، عملة وظيفية ومعاملة |
| `posting_rules`, `posting_rule_lines` | خرائط حسابات قابلة للتهيئة لكل حدث |
| `account_balances` | إسقاط قراءة دوري، وليس بديل دفتر الأستاذ |

### 8.8 الوحدات المتخصصة والإدارة

| الجداول | الغرض |
|---|---|
| `consignments`, `consignment_items`, `consignment_settlements` | أمانة المورد والبيع والتسوية |
| `repairs`, `repair_items`, `repair_status_history` | الاستلام والتقدير والتنفيذ والتسليم |
| `custom_orders`, `custom_order_specs` | طلبات خاصة ومواصفات ودفعات |
| `manufacturing_orders`, `manufacturing_stages`, `manufacturing_materials` | تصنيع ومراحل ومواد وفاقد وناتج |
| `workshops`, `workshop_accounts`, `workshop_transactions` | ورش داخلية/خارجية وكشوفها |
| `melting_batches`, `melting_inputs`, `melting_outputs` | دفعات صهر ومدخلات ونواتج وفاقد |
| `payrolls`, `payroll_items`, `commissions` | رواتب وعمولات واعتماد وعكس |
| `approval_workflows`, `approval_levels`, `approval_requests`, `approval_steps`, `approval_decisions` | محرك موافقات عام |
| `notifications`, `notification_preferences` | مركز التنبيه والقنوات |
| `attachments` | مرفقات polymorphic خاصة ومشفرة عند الحاجة |
| `audit_logs` | actor، action، before/after، IP، user-agent، reason، correlation_id |
| `integrations`, `integration_credentials`, `integration_logs`, `webhooks` | مزودون وأسرار وسجل محاولات |
| `backups`, `backup_restore_tests` | وصف النسخ ونتائج اختبار الاستعادة |

### 8.9 أهم العلاقات والقيود المركبة

- المؤسسة 1:N الفروع؛ الفرع 1:N المستودعات والصناديق والمستندات.
- المنتج 1:N المتغيرات؛ المتغير 1:N القطع؛ القطعة N:M الأحجار عبر تركيب مؤرخ.
- المستند 1:N البنود و1:N الدفعات و1:N القيود بحسب سياسة الترحيل.
- `unique(organization_id, serial_number)` و`unique(organization_id, barcode)` عندما لا يكون null.
- `unique(organization_id, branch_id, document_type, fiscal_year_id, sequence_no)`.
- `unique(organization_id, idempotency_key, channel)` للطلبات المالية.
- فهرس جزئي/بديل لضمان حجز فعال واحد لكل قطعة.
- `CHECK(debit_amount = 0 OR credit_amount = 0)` و`CHECK(debit_amount >= 0 AND credit_amount >= 0)`، مع تحقق توازن القيد في خدمة الترحيل وtrigger دفاعي اختياري.
- الارتباطات polymorphic للمرفقات والتدقيق لا تعني حذفها عند حذف الأصل؛ تحفظ حسب سياسة الاحتفاظ.

---

## 9. معمارية النظام

### 9.1 النمط المختار

Modular Monolith بطبقات واضحة:

```mermaid
flowchart TB
  UI["Livewire + Alpine + Tailwind"] --> APP["Application: Commands / Queries / DTOs"]
  API["REST API"] --> APP
  APP --> DOM["Domain: Entities / Services / Policies / Events"]
  APP --> INF["Infrastructure: Eloquent / Cache / Queue / Storage"]
  DOM --> PORTS["Contracts / Ports"]
  INF --> PORTS
  INF --> DB[(PostgreSQL)]
  INF --> REDIS[(Redis)]
  INF --> OBJ[(S3-compatible Storage)]
  INF --> EXT["Payment / Price / Messaging / Devices"]
```

### 9.2 مبادئ التنفيذ

- Controller/Livewire رقيق: التحقق والتفويض واستدعاء Use Case فقط.
- خدمات تطبيقية تدير المعاملة وقفل الصفوف وإطلاق الأحداث بعد commit.
- منطق الحساب pure domain services قابل للاختبار دون قاعدة بيانات.
- Repository فقط عند وجود استعلام معقد أو حد تبديل حقيقي؛ لا تغليف Eloquent شكلياً.
- Outbox للأحداث التي تغادر النظام لضمان عدم فقدها بين commit والطابور.
- Jobs قابلة لإعادة المحاولة وidempotent، مع dead-letter/failed jobs وتنبيه.
- CQRS خفيف: نماذج كتابة منضبطة واستعلامات تقارير محسنة، دون بنية موزعة مبكرة.
- Feature flags لإخفاء الوحدات غير المكتملة بالكامل.

### 9.3 التزامن والاتساق

عند بيع قطعة: تبدأ معاملة، يقفل `product_serials` والحجز الفعال، يتحقق النطاق والحالة، ينشئ البيع والبند وSnapshot، يسجل الدفعات، ينشئ حركة المخزون والقيد، يغير الحالة، ثم commit. إرسال الإشعار والطباعة والتكامل يحدث بعد commit. مفتاح idempotency يمنع تكرار البيع بسبب إعادة إرسال الشبكة.

### 9.4 هيكل مجلدات Laravel

```text
app/
  Modules/
    Identity/
      Application/{Commands,Queries,DTOs,Services}
      Domain/{Entities,Enums,Events,Policies,Services,Contracts}
      Infrastructure/{Models,Repositories,Listeners,Providers}
      Interface/{Http,Livewire,Resources}
      Database/{Migrations,Factories,Seeders}
      Tests/{Unit,Feature}
    Organization/
    Catalog/
    Pricing/
    Inventory/
    CRM/
    Sales/
    Purchasing/
    Treasury/
    Accounting/
    Approvals/
    Consignment/
    Repairs/
    Manufacturing/
    Melting/
    HR/
    Reporting/
    Integrations/
  Shared/
    Application/{Bus,Transactions}
    Domain/{Money,Weight,ExchangeRate,Identifiers,Clock}
    Infrastructure/{Audit,Outbox,Storage,Tenancy}
bootstrap/
config/
database/migrations/
lang/{ar,en}/
resources/views/{components,layouts}
routes/{web.php,api.php,console.php}
tests/{Architecture,Integration,E2E}
docs/{adr,api,operations,user-guide}
```

لكل وحدة Service Provider ومسارات وترحيلات واختبارات خاصة، مع منع اعتماد دائري باختبارات Architecture.

---

## 10. خطة الصلاحيات والموافقات

### 10.1 تسمية الصلاحية

صيغة `resource.action`، مثل:

- `products.view`, `products.create`, `products.update`, `products.view_cost`
- `sales.create`, `sales.discount`, `sales.discount_override`, `sales.sell_below_cost`
- `sales.void`, `sales.return`, `sales.backdate`
- `prices.update`, `inventory.transfer.approve`, `inventory.adjust.approve`
- `cash.open`, `cash.close`, `cash.close_with_pending`
- `accounting.view`, `accounting.post`, `accounting.reverse`, `accounting.period_reopen`
- `reports.financial`, `exports.sensitive`, `backups.manage`, `users.manage`

### 10.2 مصفوفة مختصرة

الرموز: م = مسموح، ط = طلب موافقة، — = ممنوع افتراضياً.

| الإجراء | المالك | مدير عام | مدير فرع | محاسب | صندوق | مبيعات | مستودع | مدقق |
|---|---:|---:|---:|---:|---:|---:|---:|---:|
| عرض تكلفة القطعة | م | م | م | م | — | — | م | م |
| بيع عادي | م | م | م | — | م | م | — | — |
| خصم فوق الحد | م | ط/م | ط | — | ط | ط | — | — |
| بيع تحت التكلفة | ط | ط/م | ط | — | ط | ط | — | — |
| إلغاء/إرجاع متأخر | ط | م | ط | ط | ط | ط | — | — |
| اعتماد تحويل | م | م | م | — | — | — | ط/م | — |
| تعديل سعر معدن | م | م | ط | — | — | — | — | قراءة |
| ترحيل قيد | م | م | — | م | — | — | — | قراءة |
| عكس قيد | ط | ط/م | — | ط | — | — | — | قراءة |
| تصدير حساس | م | ط/م | ط | ط | — | — | — | م |

هذه Defaults فقط؛ تنشأ مصفوفة تفصيلية قابلة للتهيئة، وتختبر كل Policy مع نطاق الفرع وحالة المستند.

### 10.3 محرك الموافقات

- القاعدة تحدد الحد والقيمة والفرع ونوع المستند ومجموعة الموافقين.
- يدعم تسلسلاً أو توازياً ومستوى واحداً أو عدة مستويات.
- القرار immutable، مع السبب والوقت والمستخدم والتوقيع المنطقي.
- أي تعديل مادي بعد الموافقة يبطلها ويعيد الطلب.
- انتهاء الطلب وتصعيده وتفويض الموافقة مؤرخ ومحدود المدة.
- يمنع self-approval عندما تفرض السياسة فصل المهام.

---

## 11. خطة المحاسبة

### 11.1 المبادئ

- محاسبة قيد مزدوج، أساس استحقاق، وعملة وظيفية واحدة للمؤسسة.
- دفتر أستاذ غير قابل للتعديل بعد الترحيل.
- قواعد الترحيل قابلة للتهيئة ومثبتة بإصدار على المستند.
- فصل حسابات المخزون: معدن، أحجار، مصنعية رأسمالية، أمانات، تحت التشغيل، وذهب مستعمل.
- مراكز تكلفة للفروع والورش والأقسام.

### 11.2 قيود نموذجية

بيع نقدي:

| مدين | دائن |
|---|---|
| صندوق/بنك بقيمة المقبوض | إيراد معدن |
|  | إيراد مصنعية |
|  | إيراد أحجار |
|  | ضريبة مخرجات |
| تكلفة بضاعة مباعة - معدن | مخزون معدن |
| تكلفة بضاعة مباعة - أحجار/تصنيع | مخزون أحجار/منتجات |

بيع آجل: يستبدل الصندوق بحساب العميل. البيع متعدد العملات يسجل مبلغ المعاملة والمبلغ الوظيفي؛ فروق التحصيل اللاحقة إلى ربح/خسارة صرف.

شراء آجل:

| مدين | دائن |
|---|---|
| مخزون/مصروف بحسب المكون | ذمم المورد |
| ضريبة مدخلات قابلة للاسترداد |  |

المرتجع يعكس الإيراد والضريبة وCOGS والمخزون وفق قابلية إعادة البيع. الذهب المستعمل يسجل مخزوناً مستقلاً مقابل نقد/ذمة للبائع. الأمانة لا تثبت كمخزون مملوك؛ تحفظ كمية خارج الميزانية/حساباً رقابياً ثم يثبت التزام المورد عند البيع وفق العقد.

### 11.3 الإغلاق والمصالحة

- مطابقة المبيعات مع الدفعات والصناديق يومياً.
- مطابقة دفتر المخزون مع GL حسب الفرع والملكية والمكون.
- مطابقة البنوك، الذمم والضرائب شهرياً.
- Soft close ثم close؛ إعادة الفتح بموافقة وسجل.
- لا يسمح بحذف أو تحديث قيد مرحل؛ `reversal_of_id` إلزامي للعكس.

---

## 12. خطة المخزون والأوزان

### 12.1 نموذج التتبع

- **Serial-tracked:** قطعة مجوهرات/سبيكة/حجر فريد؛ رصيد 0 أو 1.
- **Lot-tracked:** ذهب كسر، معدن خام، مواد تصنيع؛ يتتبع دفعة ووزناً وعياراً.
- **Quantity-tracked:** مواد تعبئة أو ملحقات متجانسة.

### 12.2 أنواع الحركات

استلام شراء، بيع، مرتجع بيع، إرجاع مورد، تحويل إرسال/استلام، حجز/فك (حالة لا ملكية)، جرد، تسوية، أمانة استلام/إرجاع، تصنيع صرف/ناتج، صهر صرف/ناتج، صيانة حيازة، فاقد وتلف.

### 12.3 تدفق التحويل

```mermaid
flowchart LR
  R["طلب"] --> A["اعتماد"] --> P["تجهيز"] --> S["شحن"] --> T["في الطريق"] --> V["فحص الاستلام"]
  V --> OK["استلام مطابق"]
  V --> D["تسجيل فرق"] --> AP["موافقة الفرق"] --> OK
```

لا تنقل الملكية عند الطلب. عند الشحن ينتقل الموقع إلى in-transit، وعند الاستلام إلى المستودع الهدف. الفرق يولد حركة منفصلة ولا يعدل حركة الشحن.

### 12.4 الجرد

يحدد نطاق الجرد ويأخذ Snapshot متوقعاً، ويمكن تجميد الحركة أو اعتماد عدّ مستمر بسياسة cutoff. يدعم العد الأعمى، أكثر من عدّاد، إعادة العد، ثم فرق مع سبب وموافقة وحركة تسوية وقيد.

### 12.5 دقة الحساب

تستخدم Value Objects للوزن والمال والعيار. لا تقبل وحدتان دون تحويل صريح. تحفظ قيمة الإدخال الأصلية ووحدتها، والقيمة المعيارية بالغرام. اختبارات Property-based تتحقق من أن التحويل ذهاباً وإياباً لا يتجاوز سماحية الدقة.

---

## 13. تصميم REST API

### 13.1 القواعد

- مسار `/api/v1` وإصدارات متوازية عند الكسر.
- Laravel Sanctum لتطبيق الطرف الأول، وOAuth2/OIDC عند شركاء متعددين.
- JSON موحد، UUID خارجي، تواريخ ISO-8601 UTC، ومبالغ كسلاسل عشرية لا Float.
- Pagination cursor للحركات الكبيرة، وpage pagination للشاشات الإدارية.
- `Idempotency-Key` إلزامي لإنشاء البيع والدفع والاستلام والتحويل.
- `ETag/If-Match` أو `version` للتحديث المتفائل على السجلات المناسبة.
- Rate limiting بحسب العميل والمستخدم والمسار.
- أخطاء RFC 9457 Problem Details مع `trace_id` وحقول validation.

### 13.2 الموارد الرئيسية

```text
POST   /api/v1/auth/login
POST   /api/v1/auth/2fa/verify
GET    /api/v1/me
GET    /api/v1/branches
GET    /api/v1/metals/{metal}/prices?branch_id=&currency=
GET    /api/v1/products?search=&category=&purity=&status=
GET    /api/v1/serials/{uuid}
POST   /api/v1/reservations
DELETE /api/v1/reservations/{uuid}
POST   /api/v1/sales
POST   /api/v1/sales/{uuid}/payments
POST   /api/v1/sales/{uuid}/post
POST   /api/v1/sales/{uuid}/returns
POST   /api/v1/purchases
POST   /api/v1/goods-receipts
POST   /api/v1/stock-transfers
POST   /api/v1/stock-transfers/{uuid}/approve
POST   /api/v1/stock-transfers/{uuid}/ship
POST   /api/v1/stock-transfers/{uuid}/receive
GET    /api/v1/customers/{uuid}/statement
GET    /api/v1/reports/inventory-valuation
POST   /api/v1/webhooks/{provider}
```

### 13.3 مثال عقد بيع مختصر

```json
{
  "branch_id": "uuid",
  "customer_id": "uuid",
  "currency": "ILS",
  "price_lock_id": "uuid",
  "items": [{"serial_id": "uuid", "discount": "0.0000"}],
  "payments": [{"method": "cash", "amount": "1250.0000", "currency": "ILS"}]
}
```

الاستجابة لا تقبل نجاحاً جزئياً؛ إما ترحيل كامل أو فشل كامل. العمليات الطويلة مثل تقرير ضخم تعيد `202 Accepted` ومعرف Job ورابط حالة ونتيجة موقعة مؤقتة.

### 13.4 Webhooks

توقيع HMAC، timestamp لمنع replay، معرف حدث فريد، تخزين raw payload المشفر عند الحاجة، معالجة idempotent، retries بتراجع أسي، وواجهة لإعادة المحاولة.

---

## 14. قائمة الشاشات

### 14.1 عامة وإدارية

- تسجيل الدخول و2FA واستعادة الحساب وإدارة الأجهزة.
- لوحة التحكم حسب الدور، مركز الإشعارات والموافقات.
- المؤسسات والفروع والمستودعات والمواقع والصناديق.
- المستخدمون والموظفون والأدوار ومصفوفة الصلاحيات ونطاق الفروع.
- الإعدادات، التسلسلات، العملات، الضرائب، الوحدات، قوالب الطباعة والتكاملات.
- سجل التدقيق، الدخول، التصدير، النسخ الاحتياطية واختبارات الاستعادة.

### 14.2 الكتالوج والأسعار

- المعادن والعيارات والوحدات والتحويلات.
- لوحة الأسعار الحالية، التاريخ، الاستيراد، التنبيهات، وتثبيت السعر.
- المنتجات والمتغيرات والقطع الفريدة؛ إنشاء/تعديل/استيراد/طباعة بطاقة.
- الأحجار والمختبرات والشهادات والضمانات والوسائط.

### 14.3 العمليات

- شاشة POS كاملة ولوحة بحث/مسح، سلة، عميل، تسعير، دفع وطباعة.
- قائمة المبيعات، التفاصيل، الدفعات، التعليق، الإلغاء والمرتجع.
- دورة المشتريات: الطلب، العرض، الأمر، الاستلام، الفاتورة، الدفع والإرجاع.
- أرصدة المخزون ودفتر الحركة وسلسلة حيازة القطعة.
- التحويلات: طلب، تجهيز، شحن، استلام وفروقات.
- الجرد: نطاق، عد محمول، مقارنة، إعادة عد واعتماد.
- العملاء والموردون والكشوف والائتمان والمرفقات.
- الورديات، الصناديق، القبض، الصرف، البنوك والتسوية.
- دليل الحسابات، القيود، الترحيل، الفترات ومراكز التكلفة.

### 14.4 متخصصة وتقارير

- شراء المستعمل والاستبدال والفحص.
- الأمانات والتسويات.
- الصيانة، الطلبات الخاصة، التصنيع، الورش والصهر.
- الحجوزات والأقساط والولاء والقسائم.
- الرواتب والعمولات.
- Dashboard وتقارير محفوظة وجدولة وتصدير.
- إدارة المتجر والطلبات الإلكترونية عند تفعيل الوحدة.

على الهاتف تعرض السجلات كبطاقات مع أهم الحقول وإجراءات سياقية، لا كجدول أفقي مصغر. كل شاشة لها Loading وEmpty وError وUnauthorized states، وتأكيد إضافي للعمليات الحساسة.

---

## 15. خطة مراحل التنفيذ ومعايير القبول

### المرحلة 1: الاعتماد والتحليل

**المخرجات:** هذه الوثيقة، قائمة القرارات، قاموس المصطلحات، نطاق MVP وأولويات القصص.  
**القبول:** اعتماد أصحاب القرار المالي والمخزني والتشغيلي؛ لا توجد قاعدة حرجة بلا مالك أو قرار؛ الاتفاق على البلد والعملة والضريبة والدقة وRPO/RTO.

### المرحلة 2: التصميم الفني التفصيلي

**المخرجات:** ERD كامل قابل للتوليد، قاموس أعمدة، ADRs، OpenAPI، Permission Matrix، خرائط القيود، Wireframes ونموذج تهديد.  
**القبول:** مراجعة DBA والمحاسب ومدير المخزون؛ كل Use Case حرج مرتبط بجداول وصلاحيات وقيود؛ إثبات تصميم البيع المتزامن والعكس.

### المرحلة 3: تأسيس المشروع والمنصة

**المخرجات:** Laravel مستقر حديث، CI، هوية و2FA، مؤسسة/فروع، RBAC، localization، layout، audit/outbox، بيئات وتشخيص.  
**القبول:** اختبارات الدخول والنطاق والصلاحيات ناجحة؛ العربية/الإنجليزية وRTL/LTR؛ لا أسرار في المستودع؛ فحص جودة وأمان ناجح.

### المرحلة 4: الوحدات الأساسية

تنفذ كل وحدة vertical slice مكتملة بهذا الترتيب: الهوية، الفروع، المرجعيات والأسعار، الكتالوج، المخزون، الأطراف، POS، المشتريات، الخزينة، المحاسبة.

**قبول كل Slice:** ترحيلات وقيود، Domain/API/UI، Policies، Audit، اختبارات Unit/Feature/Concurrency، توثيق ودليل تشغيل، ولا أزرار شكلية.  
**قبول المرحلة:** سيناريو شراء → استلام → بيع → دفع → مرتجع → إغلاق وردية → قيد وتقارير ينجح طرفاً لطرف وتتطابق الأرصدة.

### المرحلة 5: الوحدات المتخصصة

**المخرجات:** المستعمل والاستبدال، الصيانة، الطلبات، التصنيع، الصهر، الأمانات، الأقساط، الولاء، HR.  
**القبول:** لكل وحدة دورة حالة كاملة، حركات مخزون وقيود وموافقات وفروق واختبارات؛ لا خلط ملكية الأمانة بملكية الشركة.

### المرحلة 6: التقارير والتكاملات

**المخرجات:** Dashboard، تقارير، exports، notifications، API وشركاء/أجهزة مختارة.  
**القبول:** أرقام التقارير مصالحة مع GL والمخزون؛ التصدير يحترم النطاق والصلاحية ويسجل؛ التكامل idempotent وله retry ومراقبة.

### المرحلة 7: الاختبار والإطلاق

**المخرجات:** UAT، مراجعة أمن/أداء، ترحيل بيانات، runbooks، نسخ واستعادة، تدريب، أدلة، OpenAPI وإطلاق مرحلي.  
**القبول:** لا عيوب حرجة/عالية مفتوحة؛ نجاح restore drill؛ تحقيق أهداف الحمل؛ توقيع UAT؛ خطة rollback مجربة؛ مراقبة وتنبيهات فعالة.

### بوابة الانتقال بين الوحدات

لا تنتقل وحدة إلى Done إلا عند اكتمال: التصميم، القيود، الصلاحيات، التدقيق، الاختبارات، الوثائق، المراقبة، مراجعة الأمن، وترحيل قابل للعكس أو خطة forward-fix آمنة.

---

## 16. خطة الاختبارات

### 16.1 طبقات الاختبار

- **Unit:** Money/Weight/Purity، التسعير، المصنعية، الضرائب، التقريب، العمولات.
- **Property-based:** تحويل الوحدات والعيارات وتوازن القيود وثوابت المخزون.
- **Feature:** كل Command وPolicy وAPI وحالة مستند.
- **Integration:** PostgreSQL/Redis/S3 والطابور ومزودات الدفع والأسعار بعقود Sandbox.
- **Concurrency:** بيع وحجز وتحويل القطعة نفسها بالتزامن.
- **End-to-End:** POS والشراء والجرد والإغلاق والمسارات الحساسة.
- **Security:** تفويض أفقي/عمودي، CSRF/XSS، رفع الملفات، rate limit، webhooks.
- **Performance:** البحث، POS، دفتر ملايين الحركات، التقارير والتصدير.
- **Recovery:** استعادة قاعدة وملفات وأسرار والتحقق من الاتساق.

### 16.2 السيناريوهات الحرجة

1. طلبا بيع متزامنان لقطعة واحدة؛ ينجح واحد فقط.
2. إعادة إرسال POST بنفس Idempotency-Key؛ لا يتكرر البيع أو الدفع.
3. بيع متعدد الدفعات والعملات مع فرق صرف وتقريب.
4. خصم فوق الحد يولد موافقة ولا يرحل قبلها.
5. تغير سعر الذهب بعد الفاتورة لا يغير Snapshot أو الربح التاريخي.
6. مرتجع جزئي يعيد القطعة المناسبة ويعكس النسبة الصحيحة.
7. تحويل مع فرق وزن ينشئ فرقاً معلقاً ولا يختفي.
8. جرد مع نقص لا يعدل الرصيد قبل الاعتماد.
9. صهر يحافظ على معادلة الوزن الخالص ويفصل الفاقد.
10. قيد غير متوازن يفشل بالكامل.
11. إغلاق صندوق مع عملية معلقة يفشل دون صلاحية.
12. مستخدم فرع A لا يرى أو يعدل بيانات فرع B عبر UI أو API.
13. مخزون الأمانة لا يدخل قيمة مخزون الشركة.
14. ملف شهادة خاص لا يفتح برابط عام أو لمستخدم غير مصرح.

### 16.3 البيانات التجريبية

Factories وSeeders لبيئات التطوير والاختبار فقط، معنونة بوضوح وغير قابلة للتشغيل على الإنتاج دون flag صريح. تغطي فروعاً وعملات وعيارات وحالات قطع وفروقاً حقيقية، من دون تضمين بيانات شخصية حقيقية أو أسرار.

### 16.4 الجودة في CI

تنسيق وتحليل ساكن، اختبارات، فحص ترحيلات، فحص dependencies والأسرار، اختبارات architecture، بناء assets، وتقرير تغطية قائم على المخاطر. يمنع الدمج عند فشل أي فحص إلزامي.

---

## 17. خطة الأمان والخصوصية

### 17.1 الهوية والوصول

- Argon2id لكلمات المرور، 2FA إلزامي للأدوار الحساسة، وسياسة جلسات وخمول.
- تدوير session بعد الدخول، إبطال الأجهزة، وتنبيه جهاز جديد.
- Rate limit وتأخير تدريجي ومحاولات دخول وتقييد IP اختياري.
- Policies على كل Query/Command؛ إخفاء عناصر الواجهة ليس إجراء أمان.
- فصل مهام البيع/الإلغاء، الإنشاء/الاعتماد، القيد/الاعتماد وفق الحجم.

### 17.2 البيانات والملفات

- TLS، تشفير أقراص ونسخ، وتشفير حقول الهوية وأسرار التكامل بمفاتيح مدارة.
- ملفات في private bucket، روابط موقعة قصيرة، فحص نوع/MIME وحجم وبرمجيات خبيثة.
- منع path traversal وSVG النشط، وإزالة metadata الحساسة من الصور عند السياسة.
- سياسة احتفاظ وحذف/إخفاء للبيانات الشخصية مع عدم خرق حفظ السجلات المالية.

### 17.3 التطبيق والتدقيق

- حماية Laravel القياسية من CSRF وSQL injection عبر bindings، وترميز خرج ضد XSS.
- CSP، secure/HttpOnly/SameSite cookies، وحماية clickjacking.
- Audit append-only يتضمن correlation ID وقبل/بعد والسبب والطباعة والتصدير.
- Tamper evidence عبر hash chaining أو إرسال نسخة إلى مخزن مركزي محدود الكتابة.
- Dependency scanning، secret scanning، SAST وDAST واختبار اختراق قبل الإطلاق.

### 17.4 التهديدات الأعلى

| التهديد | الضوابط |
|---|---|
| بيع مزدوج | قفل صف، حالة ذرية، idempotency، unique constraints |
| تلاعب تكلفة/وزن | صلاحية منفصلة، approval، snapshots، audit |
| اختراق حساب مدير | 2FA، جهاز/IP، تنبيه، جلسة قصيرة |
| تسريب شهادات وهوية | تخزين خاص، تشفير، روابط موقعة، logging |
| تكرار webhook دفع | توقيع، timestamp، event id فريد، idempotency |
| حذف/فدية | نسخ immutable مشفرة، off-site، restore drills |

---

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

### 18.1 البيئات

Development، Test، Staging شبيه بالإنتاج، وProduction. لكل بيئة قاعدة وRedis وتخزين وأسرار منفصلة. لا تنسخ بيانات إنتاج شخصية إلى الاختبار دون إخفاء.

### 18.2 مكونات الإنتاج

- Load balancer/WAF ثم نسختان أو أكثر من PHP-FPM/Nginx.
- PostgreSQL مُدار أو primary/standby مع PITR.
- Redis للكاش والطوابير والأقفال، وWorkers منفصلة حسب الأولوية.
- Scheduler وحيد بقفل موزع.
- S3-compatible للوسائط والمستندات والنسخ.
- مراقبة مركزية للسجلات والمقاييس والأخطاء والتتبعات.

### 18.3 أسلوب النشر

1. بناء artifact ثابت واختباره وتوقيعه.
2. نسخ احتياطي/نقطة استعادة قبل التغيير عالي المخاطر.
3. ترحيلات expand/contract متوافقة رجعياً؛ لا حذف عمود في نفس إصدار توقف استخدامه.
4. نشر rolling أو blue/green، ثم smoke tests.
5. تفعيل Feature Flag تدريجياً ومراقبة مؤشرات العمل.
6. rollback للكود؛ وللبيانات forward-fix أو إجراء رجوع مجرب حسب الترحيل.

### 18.4 النسخ والتعافي

- النسخ المقترح: PITR مستمر، كامل يومي، ونسخة أسبوعية immutable خارج الموقع.
- ملفات ومفاتيح إعداد ضمن خطة مستقلة؛ لا تكفي نسخة قاعدة البيانات وحدها.
- تشفير النسخ، فصل صلاحية الحذف، تنبيه فشل، وتقرير نجاح.
- اختبار استعادة ربع سنوي على الأقل مع فحص القيود والمرفقات ومصالحة GL والمخزون.
- **اقتراح أولي:** RPO = 15 دقيقة، RTO = ساعتان؛ يعتمد تجارياً قبل الإطلاق.

### 18.5 المراقبة وSLO

- توافر، p95 latency، أخطاء 5xx، عمق الطوابير، failed jobs، اتصالات DB، slow queries.
- مؤشرات أعمال: بيع فاشل، فروق مخزون، قيود غير مرحلة، Webhooks معلقة، أسعار منتهية.
- تنبيهات ذات Runbook ومسؤول وتصعيد، مع عدم وضع بيانات شخصية أو أسرار في السجلات.

### 18.6 إطلاق وتشغيل أولي

ترحيل تجريبي مرتين على الأقل، مطابقة افتتاحية للأرصدة والأوزان والذمم، تدريب حسب الدور، تشغيل فرع Pilot، فترة مراقبة مكثفة، ثم تعميم تدريجي. خطة rollback تحدد آخر وقت آمن، وكيفية التعامل مع معاملات تمت بعد القطع.

---

## 19. المخاطر والتحديات

| الخطر | الأثر | التخفيف |
|---|---|---|
| اختلاف قوانين الضرائب والفوترة | إعادة تصميم مستندات وقيود | تحديد الدولة مبكراً ومحول ضريبي |
| بيانات افتتاحية غير نظيفة | أرصدة خاطئة | Profiling، تنظيف، dry runs، توقيع مصالحة |
| دقة الأوزان/الموازين | خسارة مالية | وحدة أساس، معايرة، سماحيات، سجل قراءة |
| تزامن القنوات والـPOS | بيع مزدوج | قفل وحجز وidempotency واختبارات حمل |
| اتساع النطاق | تأخر وفشل التبني | MVP وبوابات اعتماد وFeature flags |
| خرائط الحسابات غير المعتمدة | تقارير مالية خاطئة | ورش عمل مع محاسب واختبارات Golden cases |
| اعتماد مزود خارجي | توقف أسعار/دفع/رسائل | Adapter، circuit breaker، fallback ومراقبة |
| ضعف تبني الموظفين | أخطاء تشغيل | UX ميداني، تدريب، Pilot، صلاحيات واضحة |
| حساسية البيانات والقيمة | سرقة/احتيال | 2FA، فصل مهام، تدقيق غير قابل للعبث وتنبيهات |

---

## 20. قائمة قرارات مطلوبة للاعتماد

لا تمنع هذه الأسئلة اعتماد الهيكل العام، لكنها تمنع تثبيت قاعدة البيانات والقيود المحلية النهائية:

1. ما الدولة/الدول المستهدفة وما متطلبات الضريبة والفوترة الإلكترونية وKYC/AML؟
2. ما العملة الوظيفية وعملات البيع، وهل يسمح بصندوق متعدد العملات فعلياً؟
3. هل PostgreSQL معتمد أم يجب MySQL بسبب بيئة XAMPP الحالية؟
4. ما دقة الوزن المطلوبة (مثلاً 0.001g أو 0.000001g) وقواعد التقريب؟
5. ما نموذج تقييم المخزون: تكلفة فعلية لكل قطعة، وWeighted Average للمواد المجمعة، أم سياسة أخرى؟
6. متى تثبت المصنعية كمكون مخزون، ومتى تعد مصروف فترة؟
7. ما حدود الخصم والبيع تحت التكلفة والفروق والمصروف التي تشغل الموافقات؟
8. هل يمكن للمستخدم العمل في أكثر من فرع في الجلسة نفسها أم يختار فرعاً نشطاً؟
9. ما طرازات الطابعات والموازين وRFID وبوابات الدفع المطلوبة في أول إطلاق؟
10. ما حجم البيانات والمستخدمين والفروع المتوقع خلال 3 سنوات؟
11. ما RPO/RTO وفترة الاحتفاظ النظامية بالسجلات والملفات؟
12. ما البيانات الحالية ومصدرها وجودتها وخطة ترقيم القطع الافتتاحية؟

---

## 21. توصية الاعتماد والخطوة التالية

يوصى باعتماد الوثيقة على مستويين:

1. **اعتماد الأعمال:** النطاق، الحالات، القواعد، المحاسبة، الملكية، التقارير والموافقات.
2. **اعتماد تقني:** PostgreSQL/البنية، الدقة، التزامن، الأمن، API، التشغيل والتعافي.

بعد الإجابة عن قرارات القسم 20، تكون الخطوة التالية هي المرحلة الثانية: إنتاج ERD فيزيائي كامل، قاموس أعمدة وقيود، OpenAPI، مصفوفة صلاحيات تفصيلية، خرائط قيود محاسبية، وWireframes لـPOS والتحويل والجرد قبل إنشاء مشروع Laravel.

