- مقدمة
- العرض
- MVP
- خارطة الطريق
- متطلبات المنتج
- ابدأ الآن
- البيئة المحلية
- البنية المعمارية
- الهيكل
- الأنماط
- الحزمة التقنية
- قاعدة البيانات
- تعدّد المستأجرين
- الفهرس (Catalog)
- العمل دون اتصال
- المصادقة
- التهيئة (Onboarding)
- تدفق التكامل (Integration Flow)
- التهيئة (Provision)
- القبول
- الحضور
- الامتثال التنظيمي
- الملف الشخصي
- الاجتماعات
- إدارة الرسوم
- الفاتورة
- التدويل
- الترجمة
- دليل الترجمة
- أمان قاعدة البيانات
- المساهمة
- هَوْغوارتس
- عرض حي
- الإلهام
وحدة الفاتورة هي سطح الفوترة المركزي للمدرسة. تُنشأ الفواتير يدويًا عبر المعالج أو تتولّد تلقائيًا من كل حدث قابل للفوترة (رسوم التسجيل، رسوم مسارات النقل، مشتريات الدورات/الفيديو)، وتُعرض كمستند بسيط جاهز للطباعة، وتُسلَّم عبر رابط مشاركة عام أو PDF أو بريد إلكتروني. عمليات التعديل تمرّ عبر حارس المالية (requireFinanceActor)؛ والقراءات مقيّدة بالمالك ليصل الطلاب وأولياء الأمور دائمًا إلى فواتيرهم.
الحالة
| الوحدة الفرعية | الحالة | ملاحظات |
|---|---|---|
| قائمة الفواتير | إنتاج | DataTable مع فلترة وفرز وترقيم صفحات و?status= |
| تدفّق المعالج | إنتاج | تدفّق الإنشاء/التعديل — التفاصيل + البنود، حفظ المسودّات |
| عرض المستند | إنتاج | صفحة كاملة بتصميم بسيط أحادي المسافة، جاهزة للطباعة |
| روابط مشاركة عامة | إنتاج | رابط برمز يفتحه وليّ الأمر ويطبعه دون حساب |
| تصدير PDF (A4) | إنتاج | التصميم نفسه؛ IBM Plex Mono / Rubik للعربية |
| تسليم البريد | إنتاج | Resend ثنائي اللغة، يربط الصفحة العامة عند تفعيل المشاركة |
| التوليد التلقائي | إنتاج | رسوم التسجيل، رسوم مسارات النقل، مشتريات Stripe |
| البنود المفصّلة | إنتاج | بند لكل مكوّن رسوم؛ تسوية عبر الخصم/التعديل |
| اللوحة | إنتاج | تحليلات الإيرادات بعملة المدرسة، إحصائيات 30 يومًا |
| الإعدادات | إنتاج | الشعار + التوقيع (PDF، البريد، المستند، الصفحة العامة) |
| تصدير CSV | جاهز | الأداة موجودة، لا زرّ لها بعد |
| الفواتير المتكرّرة | مخطّط | جدولة فواتير متكرّرة |
المسارات
| المسار | الصفحة | المكوّن |
|---|---|---|
.../finance/invoice | قائمة الفواتير | content.tsx |
.../finance/invoice/analysis | لوحة التحليلات | dashboard/content.tsx |
.../finance/invoice/invoice/create | ينشئ مسودّة ويحوّل إلى المعالج | صفحة مسار |
.../finance/invoice/invoice/edit/[invoiceId] | يحوّل إلى تفاصيل المعالج | صفحة مسار |
.../finance/invoice/invoice/view/[id] | مستند بصفحة كاملة + شريط أدوات | invoice/view-content.tsx |
.../finance/invoice/add/[id]/details | المعالج — التفاصيل (رقم مُعبّأ مسبقًا) | wizard/details/content.tsx |
.../finance/invoice/add/[id]/items | المعالج — البنود (مجاميع يتحقّقها الخادم) | wizard/items/content.tsx |
.../finance/invoice/settings | الهوية (الشعار، التوقيع) | settings/content.tsx |
.../finance/invoice/onboarding | إعداد الملف لأول مرة | onboarding/content.tsx |
/[lang]/invoice/[token] (عام) | فاتورة مشتركة — عرض + طباعة دون مصادقة | مسار على مستوى الجذر |
إجراءات الخادم
| الإجراء | البوابة | الغرض |
|---|---|---|
getInvoicesWithFilters | مصادقة + مستأجر، مقيّد بالمالك | قائمة مفلترة (الأدوار المخوّلة ترى الكل؛ غيرها فقط ملكه) |
getInvoiceById | مصادقة + مستأجر، مقيّد بالمالك | التفاصيل + المدفوعات المرتبطة + الهوية + حالة المشاركة |
deleteInvoice | requireFinanceActor(invoice, delete) | حذف مع تنظيف العناوين اليتيمة |
sendInvoiceEmail | requireFinanceActor(invoice, export) | بريد Resend (الرابط العام عند تفعيل المشاركة) |
markInvoicePaid | requireFinanceActor(invoice, edit) | قلب آمن من السباقات + قيد دفتري |
shareInvoice | requireFinanceActor(invoice, edit) | سكّ/إعادة استخدام الرمز العام (share.ts) |
revokeInvoiceShare | requireFinanceActor(invoice, edit) | تعطيل الرابط مع الاحتفاظ بالرمز (share.ts) |
getSharedInvoice | عام — الرمز هو بيانات الاعتماد | حمولة عرض دنيا + عدّاد مشاهدات (share.ts) |
updateSettings | مصادقة + مستأجر (صفّ المالك) | شعار الهوية + التوقيع |
getDashboardStats | مصادقة + مستأجر، مقيّد بالمالك | إحصائيات 30 يومًا + عملة المدرسة |
القراءات تتجاوز بوابة الصلاحيات عمدًا (تقييد الصفوف بالمالك هو التخويل) ليستمر عمل بوابة الطالب/وليّ الأمر — المسوَّغ موثّق على requireAuthAndTenant في actions.ts.
كيف تتولّد الفواتير
| المصدر | المُحفِّز | النتيجة |
|---|---|---|
| يدوي | «إنشاء فاتورة» ← المعالج | مسودّة بعملة المدرسة مع رقم تسلسلي مُعبّأ مسبقًا |
| التسجيل / إضافة طالب | ensureStudentFeeAssignments ← fee-invoice-sync | فواتير -ENR لكل تعيين رسوم، مفصّلة حسب مكوّنات الرسوم |
| رسوم مسارات النقل | «ترحيل إلى الفوترة» في صفحة رسوم النقل | هيكل لكل مسار + شهر ← تعيينات ← فواتير (آمن لإعادة التشغيل) |
| شراء دورة / فيديو | Stripe webhook عند نجاح الدفع | فاتورة -PUR مدفوعة مسبقًا (آمنة أمام إعادة التسليم) |
رسوم التسجيل المحصَّلة عند قبول العرض تُخصَّص على فاتورتها المولَّدة تلقائيًا داخل معاملة التسجيل نفسها، فتظهر الفاتورة «مدفوعة» فور اكتمال التسجيل.
التفصيل إلى بنود
فواتير الدفعة الواحدة تحمل بندًا لكل مكوّن رسوم غير صفري (دراسية، قبول، تسجيل، امتحانات، مكتبة، مختبر، رياضة، نقل، سكن، إضافة إلى otherFees المخصّصة) بتسميات بلغة المدرسة. عند منحة تخفّض المبلغ عن السعر المعلن يذهب الفارق إلى حقل الخصم؛ وعند الفوترة فوقه يُضاف بند «تسوية». فواتير الأقساط تحتفظ ببند «القسط N من M» لكل قسط.
الطباعة والمشاركة وPDF
- الطباعة — عرض المستند والصفحة العامة يُطبعان كورقة A4 نظيفة من المتصفح (تُزال واجهة التطبيق عبر أنماط الطباعة العامة).
- المشاركة — نافذة المشاركة تسكّ رابطًا عامًا (
/invoice/{token})؛ أي شخص لديه الرابط يعرض ويطبع دون حساب. الإلغاء يعطّل الوصول لكنه يحتفظ بالرمز، فإعادة التفعيل تستعيد الرابط نفسه. أرسل عبر واتساب أو البريد مباشرة من النافذة. - PDF — «تنزيل PDF» يُخرج التصميم البسيط نفسه عبر
react-pdf@(IBM Plex Mono للإنجليزية وRubik للعربية). - البريد — بريد Resend ثنائي اللغة ويربط الصفحة العامة عند تفعيل المشاركة، وإلا فصفحة التفاصيل المُصادَق عليها.
وصول الأدوار
| الدور | الوصول |
|---|---|
| مدير / محاسب / مطوّر | كامل — إنشاء، تعديل، حذف، تعليم كمدفوعة، مشاركة، بريد، إعدادات |
| طالب / وليّ أمر | فواتيره فقط — تقييد القائمة، قسم «مدفوعات الرسوم» في اللوحة، التفاصيل، PDF |
| حامل الرابط (دون حساب) | عرض + طباعة صفحة الفاتورة المشتركة |
المحاسبة
markInvoicePaid يقيّد «من ح/ النقدية إلى ح/ الذمم المدينة» في دفتر القيد المزدوج (آمن من السباقات، مفتاحه معرّف الفاتورة). فواتير المشتريات تُنشأ حاليًا دون قيد دفتري — قاعدة ترحيل نقطة البيع (من ح/ النقدية إلى ح/ الإيرادات) متعقَّبة كمتابعة.