Imported from 2030karim2-dev/alzhraERP (AGENTS.md). Install upstream with npx skills add 2030karim2-dev/alzhraERP. Copyright stays with the author.

Project Rules & Customizations (قوانين وقواعد مشروع الزهراء ERP)

1. Anti-Duplication & Data Integrity (قوانين منع التكرار وسلامة البيانات)

• نطاق المنشأة (company_id): جميع قيود التكرار وفهارس الأمان محصورة بـ company_id مع استبعاد السجلات المؤرشفة (WHERE deleted_at IS NULL).
• المنتجات (products):
  • يُمنع تكرار الباركود لنفس المنشأة مع التطبيع وإزالة الفراغات (ux_products_company_barcode).
  • يُمنع تكرار رمز الصنف الداخلي (sku) أو اسم المنتج لنفس المنشأة.
  • يُمنع تكرار تركيبة (رقم القطعة المصنعي part_number + الماركة brand) مع توحيد الأحرف الصغيرة والمسافات (LOWER(TRIM(...))).
• العملاء والموردين (parties): يُمنع تكرار اسم العميل/المورد، أو رقم الهاتف، أو الرقم الضريبي لنفس المنشأة والنوع (customer أو supplier).
• الفواتير والسندات (invoices, bonds):
  • ترقيم تسلسلي فريد وذري عبر دوال PostgreSQL RPC لمنع تصادم الأرقام في الفترات المزدحمة.
  • منع الإرسال المكرر والنقر المزدوج (Double Click Prevention) بالجمع بين تعطيل الأزرار أثناء التحميل ومفاتيح عدم التكرار (Idempotency Keys).
• الرسائل التنبيهية ومعالجة الأخطاء:
  • تحويل أي خطأ قاعدة بيانات (بما فيها 23505 للتكرار، 23503 للارتباط، 23514 للقيود، و 42501 للصلاحيات) عبر محرك errorUtils.ts إلى رسائل واضحة ومحددة باللغة العربية دون تسريب تفاصيل بنيوية.

2. Date & Timezone Handling (معايير التواريخ والمناطق الزمنية)

• منع انزياح التوقيت (No UTC Shift): يُمنع استخدام new Date().toISOString().split('T')[0] لإنشاء تواريخ المعاملات التجارية والفواتير، لتفادي إرجاع تاريخ اليوم السابق عند استخدام النظام ليلاً في منطقة الخليج ومصر (GMT+2 / GMT+3).
• الاعتماد الإلزامي على formatLocalDate(): يجب دائماً استيراد واستخدام formatLocalDate() من @/core/utils/dateUtils للحصول على تاريخ محلي دقيق ومطابق ليوم المستخدم.

3. Roles & Permissions Architecture (معمارية الأدوار والصلاحيات)

• الأدوار المعتمدة: يدعم النظام أدواراً واضحة (owner, admin, manager, accountant, sales, viewer).
• حارس المالك الصارم (assertOwner): العمليات السيادية الحساسة (مثل إغلاق السنة المالية أو التعديلات الهيكلية) تتطلب التحقق الصريح من دور owner.
• سلامة الرفض: لا يجوز لطبقات التراجع (Fallback) ابتلاع رفض الخادم الحقيقي للصلاحيات؛ وتعتمد حراسة الصلاحيات على البادئة الموحدة عذراً، لا تمتلك صلاحية لمنع التجاوز الصامت.

4. Quality Gates & TypeScript Standards (بوابات الجودة وضبط الأنواع)

• صفر أخطاء نوعية (Zero TypeScript Errors): يحافظ المشروع على سقف 0 أخطاء في ts-error-baseline.txt، ويُمنع رفع أي تعديل يزيد من الأخطاء النوعية.
• فحوصات ما قبل الرفع (pre-push) الإلزامية:
  • التأكد من سلامة ترميز النصوص العربية وخلوها من أي تشوهات (check:encoding).
  • التزام حدود الطبقات المعمارية ومنع استيراد عميل Supabase مباشرة في مكونات الواجهة (check:layers).
  • خلو الكلاسات من أي تعارضات في Tailwind وخلو الشيفرة من خطوط أصغر من 10px.

5. High-Density UI & Design System (معايير التصميم والواجهات)

• الكثافة المريحة (High-Density Ergonomics): تصميم الواجهات المحاسبية وشاشات نقاط البيع وجداول المخزون بكثافة بيانات عالية وواضحة تحدّ من التمرير غير الضروري.
• حدود الخطوط وأحجام النصوص: يُمنع استخدام أي أحجام خطوط أصغر من 10px (text-[10px] هو الحد الأدنى للوسوم التوضيحية والـ badges فقط، والنصوص التفاعلية تبدأ من 12px فأعلى).
• الألوان ودلالات الحالات: الالتزام بنظام الألوان المعتمد (الداكن والفاتح)، وتوافق ألوان التنبيه مع طبيعة الحدث (الزمردي/الأخضر للمسودات والنجاح، الأحمر للإلغاء والمخاطر، الكهرماني للفروقات والتنبيهات، والأزرق للعمليات الرئيسية).

6. Expenses & Multi-Currency Accounting Standards (معايير المصروفات والعملات المتعددة والتقارير)

• منع فرض العملة القسري وتذكر التفضيل (Currency Persistence): يجب أن تتذكر واجهة المصروفات آخر عملة استخدمها المستخدم تلقائياً، والاعتماد على الريال اليمني (YER) كافتراضي أولي للمصروفات النثرية في العمليات اليمنية لمنع تضخم المبالغ بـ 410 أضعاف.
• حارس المبالغ غير المنطقية بالريال السعودي: يُمنع تسجيل مبالغ كبيرة بالريال السعودي (>= 500 ر.س) للمصروفات النثرية دون تنبيه ذكي فوري يوضح المعادل بالريال اليمني ويوفر زراً سريعاً للتحويل المباشر.
• عزل تكلفة البضاعة المباعة (COGS / 5100): يُمنع إدراج حسابات تكلفة البضاعة المباعة (5100 وما يتبعها) في تقارير المصروفات التشغيلية (OperationalExpensesReport)؛ فتلك التكاليف تخص تكلفة المبيعات في مجمل الربح ولا يجوز خلطها بالمصاريف التشغيلية.
• منع استخدام Math.abs() في حساب المجاميع المحاسبية: في شاشات التقارير وقوائم الدخل، يُمنع تطبيق القيمة المطلقة على بنود الحسابات لتفادي تحويل القيود العكسية والتسويات الدائنة إلى مبالغ مضافة تؤدي لمضاعفة وتشويه المصروفات أو الإيرادات.