تحليل — سير الاعتماد (Approval Workflows): شغّال وإيه لأ

١. السؤال (المطلوب)

المالك فتح /app/sales/approval-workflows وسأل: إيه دي؟ بتشتغل إزاي؟ موجودة في كل الموديولز ولا المبيعات بس؟ إزاي نفعّلها؟ وأهم حاجة: إيه المربوط بالكود فعليًا وإيه اللي واجهة/إعداد بس مش شغّال؟

٢. الخلاصة في ٤ نقاط

① فيه محرّكين اعتماد منفصلين تمامًا، مش متوصّلين ببعض:

(أ) المحرّك العام اللي الشاشة /sales/approval-workflows بتظبطه (مستويات متعدّدة + معتمِدون + حدود مبالغ) — مبني بالكامل وشغّال داخليًّا، لكن مفيش أي مستند بيستدعيه. صفر callers (مثبت بالبحث الشامل). يعني تقدر تعمل ورك-فلو وتحفظه… ومحصلش حاجة.
(ب) سلسلة الحالة المبرمَجة على المستند نفسه (مسودة ← معلّق ← معتمَد ← مرحّل) — دي اللي شغّالة فعلًا في المبيعات والمشتريات، بس بدائية: خطوة واحدة، بصلاحية بس، مش بتقرأ الحدود ولا الإعدادات ولا الورك-فلو المُعرَّف.

② الحدود (thresholds) ميتة في الحالتين: فاتورة بمبلغ كبير مش بتطلب اعتماد بالمبلغ في أي مكان. الإعدادين approval_workflow (none/simple/multi_level) وapproval_thresholds محفوظين ومش بيتقرأوا أبدًا.

③ التغطية: بس المبيعات + المشتريات عندهم سلوك اعتماد (السلسلة المبرمَجة). الإنتاج enum-case يتيم بلا أنواع مستندات. HRM/المخزون عندهم اعتماد خاص بيهم (إجازات/صرف جزئي) منفصل تمامًا عن المحرّك ده.

④ الحاجة الحلوة: المحرّك العام مكتوب صح ومكتمل (خدمة ApprovalWorkflowService فيها منطق الحدود + المستويات + السجلّات + الإشعارات + tab «قيد الاعتماد») — مجرد مش موصّل. التوصيل شغل محدود، مش إعادة بناء.

٣. إيه هو بالظبط + بيشتغل إزاي

المحرّك العام (أ) — البنية موجودة

٣ جداول (Core، مُهاجَرة 2026-02-24): approval_workflows (ورك-فلو واحد لكل نوع مستند/شركة) · approval_workflow_levels (المستويات: ترتيب + min/max مبلغ + نوع المعتمِد role/user) · approval_logs (سجلّ الاعتماد لكل مستند).
الخدمة Modules/Core/app/Services/ApprovalWorkflowService.php: submitForApproval() (بيلاقي ورك-فلو نشط، يفلتر المستويات بالحدود، auto-approve لو مفيش/كله تلقائي، وإلا ينشئ سجلّات ويبلّغ أول مستوى) + approve/reject/canUserApprove/getPendingForUser/notify. منطق الحدود موجود وصحيح — بس مفيش حد بينده الخدمة.
الـAPI (Core، عام): CRUD للورك-فلو + approval-logs/{id}/approve|reject. مفيش أي endpoint «submit» بيغذّي المحرّك من مستند حقيقي.
الشاشة (فرونت): تبويبين — «الورك-فلوز» (إنشاء/تعديل، بس أنواع المستندات مبيعات فقط hard-coded، مفيش قائمة موديول) + «قيد الاعتماد» (بيقرأ approval_logs). الحقول: مستويات + معتمِد (user؛ فرع الـrole مش مرسوم في الـHTML) + حدود مبلغ.

السلسلة المبرمَجة (ب) — دي اللي شغّالة

مسودة Draft──submitApproval──▶معلّق Pending──approve──▶معتمَد Approved──post──▶مرحّل Posted

الترحيل (post) بيشترط فعلًا حالة «معتمَد» (PostSalesInvoice.php:38 canPost()===Approved) — فمستحيل ترحّل بدون اعتماد. لكن «الاعتماد» ده مجرد انتقال واحد محكوم بصلاحية sales.invoices.approve: مش متعدّد المستويات، مش بيقرأ مبلغ، مش مربوط بورك-فلو مُعرَّف، وممكن يعتمد من المسودة على طول (خطوة «معلّق» اختيارية).
المشتريات نسخة طبق الأصل (PurchaseBillStatus canApprove/canPost).

٤. إيه اللي شغّال وإيه اللي مش شغّال (المهم)

المكوّن	الحالة	الدليل
سلسلة الحالة المبرمَجة (اعتماد قبل الترحيل)	✅ شغّال	المبيعات + المشتريات؛ الترحيل يشترط معتمَد. بس خطوة واحدة بصلاحية، بلا حدود/مستويات.
المحرّك العام (الشاشة كلها: ورك-فلوز/مستويات/سجلّات)	❌ ميّت	CRUD شغّال، بس `submitForApproval` صفر استدعاء — مفيش مستند بينشئ سجلّ. إعداد بلا تنفيذ.
الحدود بالمبلغ (thresholds)	❌ ميتة	الإعداد `approval_thresholds` صفر قُرّاء؛ حدود المستويات بتتقيّم جوّه خدمة مش بتتنده. فاتورة كبيرة مش بتطلب اعتماد.
إعداد `approval_workflow` (none/simple/multi_level)	❌ مش بيتقرأ في الباك	الفرونت بس بيفرّق «none» عن «مش-none»؛ الباك مبيقراهوش خالص. القيمة multi_level مالهاش أثر.
tab «قيد الاعتماد» + الموافقة/الرفض على السجلّات	⚠️ يعمل لكن فاضي	بيقرأ سجلّات مفيش حد بينشئها → القائمة دايمًا فاضية. معزول جوّه شاشة المبيعات.
الإنتاج في المحرّك	❌ يتيم	enum فيه `Production` بس مفيش أنواع مستندات ليه → ورك-فلو غير قابل للإنشاء.

باختصار: شاشة «سير الاعتماد» = واجهة إعداد لمحرّك متكامل لكن مفصول عن دورة حياة أي مستند. اللي بيحمي مستنداتك فعلًا حاجة تانية بدائية (سلسلة حالة بصلاحية واحدة). فأنت بتظبط حاجة… مالهاش تأثير.

٥. هل موجودة في كل الموديولز؟ — لأ

الموديول	في enum المحرّك؟	أنواع مستندات؟	المحرّك مفروض؟	سلسلة الحالة المبرمَجة؟
المبيعات	✅	quotation/order/invoice/return/delivery	❌	✅ (بصلاحية، بلا حدود)
المشتريات	✅	request/order/bill/return/grn	❌	✅ (بصلاحية، بلا حدود)
الإنتاج	✅ enum بس	❌ ولا نوع	❌	❌ (إشعارات أدوار بس)
المخزون	❌	—	❌	اعتماد صرف جزئي خاص به (منفصل)
الموارد البشرية	❌	—	❌	`LeaveApproval` خاص به (منفصل)
المحاسبة / POS / المعمل / CRM	❌	—	❌	❌

٦. إزاي «نفعّلها» فعليًا

النهارده: لو عايز اعتماد بسيط (خطوة واحدة قبل الترحيل) — هو شغّال أصلًا في المبيعات/المشتريات: امنح المستخدم صلاحية العرض/الإنشاء من غير *.approve، وامنح *.approve للمدير بس. فالموظف يعمل مسودة، والمدير يعتمد، وبعدها الترحيل. (ده يحقق «مش يرحّل غير بعد اعتماد».)

لكن ده لسه بدائي: خطوة واحدة، بلا حدود مبالغ، بلا مستويات، والشاشة اللي بتظبط الورك-فلو مالهاش أي أثر. عشان الشاشة تشتغل بجد (متعدّد المستويات + حدود + معتمِد مخصّص لكل مستوى) لازم توصيل الكود (الخطة تحت).

٧. الملفات المتأثرة (للتوصيل)

باك (التوصيل الأساسي)

Modules/Sales/app/Actions/PostSalesInvoice.php + SalesInvoiceController (submitApproval/approve) — ينادوا ApprovalWorkflowService::submitForApproval ويحجبوا الترحيل لحد ما السجلّ يبقى معتمَد
Modules/Purchases/…/PostPurchaseBill.php + كونترولرات المشتريات — نفس التوصيل
ApprovalWorkflowService.php (موجود، جاهز) · enums ApprovalModule/DocumentType (توسيع للإنتاج لو اتقرّر)
قراءة إعداد approval_workflow/approval_thresholds (أو الاعتماد على جداول المحرّك مباشرة)

فرونت

features/sales/approval-workflows/* — قائمة موديول/أنواع مستندات (مش مبيعات فقط) + إظهار فرع الـrole وauto_approve
شاشات المستندات — ربط زر «تقديم للاعتماد» بحالة المحرّك الحقيقية (سجلّ pending) بدل السلسلة المبرمَجة
inbox موحّد «اعتماداتي» (بدل الـtab المدفون)

٨. خطة التنفيذ المقترحة (WPs) — لو قرّرت التوصيل

P0 توصيل المحرّك بالمبيعات والمشتريات: عند submit/approve/post، نادِ ApprovalWorkflowService::submitForApproval(module,docType,id,amount)؛ لو رجع pending احجب الترحيل لحد ما كل سجلّات المستند تبقى معتمَدة. ده بيحيي المستويات + الحدود + المعتمِد المخصّص. [FIN — يمسّ ترحيل المستندات].

P1 الفرونت: شاشة الإعداد تدعم كل الموديولات (قائمة موديول + أنواع مستندات) + فرع الـrole + auto_approve؛ وربط زر «تقديم للاعتماد» بحالة المحرّك؛ inbox موحّد «اعتماداتي».

P2 توسيع للموديولات التانية (إنتاج/مخزون…) حسب الحاجة — إضافة أنواع مستنداتها للـenum + نقاط التوصيل.

P2 توحيد: إمّا نخلّي المحرّك العام هو المصدر الوحيد ونلغي السلسلة البدائية، أو نخلّي البدائية «مستوى ٠» داخله. + تصليح تضارب صلاحية الشاشة (core مقابل sales.approval-workflows).

٩. قرارات تحتاج المالك (مع توصية)

القرار	الخيارات	التوصية
هل نوصّل المحرّك أصلًا؟	(أ) نوصّله ليشتغل بجد (مستويات+حدود) · (ب) نكتفي بالسلسلة البسيطة الحالية · (ج) نخفي الشاشة لحد ما نوصّل	لو محتاج اعتماد بحدود/مستويات فعليًا → (أ). لو خطوة واحدة تكفي → (ب) + (ج) نخفي الشاشة المضلِّلة لحد التوصيل.
نطاق التوصيل	مبيعات+مشتريات أولًا · ولا كل الموديولات	مبيعات+مشتريات أولًا (نقاط التوصيل جاهزة)؛ الباقي لاحقًا.
مصير السلسلة البدائية	تُدمج في المحرّك · تُلغى · تتعايش	تُدمج (مستوى واحد داخل المحرّك) لتفادي محرّكين متوازيين.

مفيش «معاينة UI» تفصيلية هنا لأن ده تحليل فهم (مش WP UI معتمد). لو وافقت على التوصيل، الخطة التنفيذية هتتضمّن معاينات قبل/بعد لشاشة الإعداد والـinbox.

تحليل قراءة-فقط · فحص Opus لـ BE+FE + KB (production.md «ApprovalWorkflow غير موصّل») · لم تُعدَّل أي بيانات أو كود. بانتظار قرار المالك قبل أي تنفيذ.