الفوترة على المراحل والفوترة الإلكترونيةStaged billing and ZATCA e-invoicing

كل مرحلة في عقد الأتعاب لها محفّز (التوقيع، القيد، الحكم الابتدائي، حكم الاستئناف، فتح التنفيذ، التحصيل)؛ عند وقوعه تُنشأ فاتورة مسودة مربوطة بالملف، يعتمدها المحاسب، ثم يرسلها تطبيق KSA Compliance إلى ZATCA. لا نبرمج تشفير الفوترة بأنفسنا.

بطاقة الميزة

5الهدف التجاري والمشكلة التي تعالجها

الفوترة اليدوية تتأخر عن الحدث فيضيع التحصيل، والخطأ في الفاتورة الإلكترونية مكلف ضريبيًا.

6المجال القانوني المرتبط للمطوّر غير المتخصص

ضريبة القيمة المضافة والفوترة الإلكترونية بمرحلتيها تتولاها الهيئة هيئة الزكاة والضريبة والجمارك — الفوترة الإلكترونية. أتعاب النجاح تُفوتر عند التحصيل الفعلي لا عند الحكم (دليل المطور ص34). الفاتورة الضريبية لدفعة مقدمة لها توقيت نظامي ذكرته الوثيقة المعمارية (الوثيقة المعمارية) يحتاج اعتمادًا قانونيًا. كل مكتب له رقمه الضريبي وشهادته وسلسلة التجزئة الخاصة به (الوثيقة المعمارية).

7المستخدمون والأدوار والصلاحيات

المحاسب يعتمد ويرسل ويصدر إشعارات الدائن. الشريك يرى التحصيل. الموكّل يرى فواتيره ويدفع B35 بوابة الموكّل وتطبيقه.

8شروط البدء والاعتماديات

تثبيت KSA Compliance على إصدار ERPNext المعتمد (OD-01)، تسجيل وحدة الفوترة (EGS) لكل مكتب يحتاج تحققًا أو موافقة رسمية. B22 العقود الإلكترونية واتفاقيات الأتعاب والتوقيع مراحل العقد.

9السيناريو الأساسي خطوة بخطوة

1. جدول المراحل في Fee Agreement: الاسم، المحفّز، المبلغ أو النسبة، الحالة، الفاتورة.
2. المحفّز يقع (حدث في النظام) ← فاتورة مسودة Sales Invoice مع legal_matter.
3. المحاسب يراجع ويعتمد (التصحيح بإشعار دائن).
4. KSA Compliance يُنشئ XML ويرسل للاعتماد (فاتورة قياسية) أو الإبلاغ (مبسطة) ويُرفق QR وPDF/A-3 (الوثيقة المعمارية).
5. رابط دفع عبر بوابة محلية مربوط بـ Payment Entry بوابة الدفع المحلية.
6. بالساعة: فاتورة شهرية من الساعات المعتمدة؛ الاشتراك السنوي: Auto Repeat شهري (دليل المطور ص34).

10السيناريوهات البديلة والاستثناءات

رفض الهيئة: الفاتورة في قائمة «مرفوضة» بسبب الرفض، ويصحح المحاسب. انقطاع: إعادة محاولة من التطبيق. مصروفات قابلة للفوترة: تُضاف للفاتورة التالية بحسب سياسة المكتب (دليل المطور ص34). معاملة ضريبية للمصروفات: إعداد لكل نوع مصروف بعد رأي ضريبي (الوثيقة المعمارية) يحتاج اعتمادًا قانونيًا.

11المدخلات والحقول

12المخرجات والإشعارات والسجلات والتقارير

فواتير بأرصدة مرتبطة بالملفات. تقارير أعمار الديون. قائمة الفواتير المرفوضة.

13قواعد العمل بصيغة قابلة للتحويل إلى كود

RULE B23.1  trigger event -> draft Sales Invoice (never auto-submit)
RULE B23.2  legal_matter mandatory on Sales Invoice for legal revenue accounts (accounting dimension)
RULE B23.3  success fee invoiced on actual collection
RULE B23.4  corrections via Credit Note only after submission
RULE B23.5  ZATCA crypto/XML/QR handled by ksa_compliance; no custom implementation
RULE B23.6  approved timesheets billed -> locked (B19)

14حالات السجل وانتقالاتها وشروطها

المرحلة: بانتظار ← مستحقة ← مفوترة ← مدفوعة. الفاتورة: مسودة ← معتمدة ← مرسلة للهيئة (مقبولة / مرفوضة).

15نموذج البيانات والعلاقات والقيود والفهارس

Fee Agreement 1 → n Fee Stage؛ Fee Stage 1 ↔ 1 Sales Invoice. البُعد المحاسبي «القضية» على بنود الفاتورة.

16DocTypes المطلوبة في Frappe

• Fee Agreement (دليل المطور ص11)، Fee Stage (فرعي) (الوثيقة المعمارية)، Custom Field legal_matter على Sales Invoice.

17الشاشات والعناصر والأزرار ورسائل الخطأ

تبويب «الأتعاب» في الملف بجدول المراحل وحالتها. قائمة المحاسب «فواتير بانتظار الاعتماد».

18خدمات Backend ومسؤولية كل خدمة

legal_erp.billing.on_trigger(event)، legal_erp.billing.monthly_hourly.

19واجهات API الداخلية

لا توجد واجهة API خاصة بهذه الميزة.

20الأحداث والمهام الخلفية والجدولة وإعادة المحاولة

شهري: فوترة الساعات. Auto Repeat للاشتراكات. حالة الإرسال للهيئة من التطبيق.

21التكاملات المرتبطة بالميزة وحدودها

هيئة الزكاة والضريبة والجمارك — الفوترة الإلكترونية عبر KSA Compliance؛ يحتاج إعداد كل مكتب وتسجيله يحتاج تحققًا أو موافقة رسمية. بوابة الدفع المحلية.

22الأمن والخصوصية والتدقيق والاحتفاظ والحذف

شهادة الفوترة ومفاتيحها في خزنة الأسرار لكل موقع، لا في الكود. حفظ الفواتير داخل المملكة المدة النظامية B38 الاحتفاظ والإتلاف والتجميد القانوني.

23حالات الاختبار

24معايير القبول

• كل فاتورة مربوطة بملف.
• لا كود تشفير خاص.
• اختبار بيئة الهيئة ناجح.

25تعريف الاكتمال (Definition of Done)

• كل قواعد العمل في هذه الصفحة منفذة في الخادم (Controller أو Service)، لا في الواجهة وحدها.
• حالات الاختبار المذكورة هنا مكتوبة اختباراتٍ آلية في إطار اختبار Frappe، وتنجح مع كل دفعة كود.
• اختبارات الصلاحيات تثبت أن مستخدمًا خارج فريق الملف لا يرى السجل في القائمة ولا برابطه المباشر ولا في البحث العام ولا في العدّادات.
• الحقول المخصصة والأدوار ومسارات الاعتماد مُصدَّرة في Fixtures التطبيق، وتظهر بعد تثبيت نظيف على موقع فارغ دون إعداد يدوي.
• لا تعديل في ملفات Frappe أو ERPNext.
• كل قيمة قانونية (مدة، نسبة، مبلغ، قائمة) محفوظة في إعداد قابل للتعديل، وموسومة بحالة اعتمادها.
• نصوص الواجهة ورسائل الخطأ بالعربية، وتخبر المستخدم بما يفعله.
• معايير القبول في هذه الصفحة مُتحقق منها ومسجلة في مصفوفة التتبع.

26القرارات المفتوحة والمخاطر والاعتمادات المطلوبة

توافق KSA Compliance مع v16 (OD-01). موعد إلزام موجة المكتب في الربط بحسب إيراداته يحتاج تحققًا أو موافقة رسمية.