- مقدمة
- العرض
- MVP
- خارطة الطريق
- متطلبات المنتج
- ابدأ الآن
- البيئة المحلية
- البنية المعمارية
- الهيكل
- الأنماط
- الحزمة التقنية
- قاعدة البيانات
- تعدّد المستأجرين
- الفهرس (Catalog)
- العمل دون اتصال
- المصادقة
- التهيئة (Onboarding)
- تدفق التكامل (Integration Flow)
- التهيئة (Provision)
- القبول
- الحضور
- الامتثال التنظيمي
- الملف الشخصي
- الاجتماعات
- إدارة الرسوم
- الفاتورة
- التدويل
- الترجمة
- دليل الترجمة
- أمان قاعدة البيانات
- المساهمة
- هَوْغوارتس
- عرض حي
- الإلهام
المبيعات والانتشار
تستخدم Hogwarts Next.js App Router مع مكونات قائمة على الميزات. المسارات تعكس المكونات 1:1 — إن عرفت الـURL عرفت مكان الكود. راجع الأنماط لأعراف الكود والبنية المعمارية لشرح نمط المرآة.
جذر المشروع
hogwarts/
├── public/ # أصول ثابتة
├── prisma/
│ ├── schema.prisma # datasource + generator + imports
│ ├── models/ # 73 ملف .prisma
│ └── seeds/ # سكربتات seed (تُشغَّل عبر pnpm db:seed:single)
├── src/
│ ├── app/ # مسارات Next.js App Router
│ ├── components/ # مكونات الميزات (مرآة لـapp/)
│ ├── lib/ # وحدات utilities
│ ├── types/ # تعريفات TypeScript عامة
│ ├── styles/ # أنماط عامة (typography.css)
│ └── proxy.ts # Edge proxy — استخراج النطاق وإعادة الكتابة
├── content/docs-en/ # وثائق MDX (إنجليزية)
├── content/docs-ar/ # وثائق MDX (عربية، مرآة)
├── scripts/ # سكربتات بناء + seed
├── tests/ # مجموعات E2E (Playwright)
├── .env # بيئة مركزية — لا .env.local أبداً
├── next.config.ts
├── package.json # pnpm فقط
└── tsconfig.json # @/* → ./src/*المسارات (src/app/)
كل المسارات تحت [lang]/ لتوجيه اللغة (ar, en). أربع نقاط دخول تُنفَّذ عبر مجموعات App Router.
نقاط الدخول
| المجموعة | الـURL | الغرض | الوصول |
|---|---|---|---|
(saas-marketing) | ed.databayt.org/ | تسويق SaaS عام | عام |
(saas-dashboard) | ed.databayt.org/dashboard | لوحة المشغّل | DEVELOPER فقط |
(school-marketing) | school.databayt.org/ | موقع المدرسة العام | عام |
(school-dashboard) | school.databayt.org/dashboard | منصة المدرسة | أدوار المدرسة المصادَق عليها |
شجرة المسارات
src/app/[lang]/
├── (saas-marketing)/ # ed.databayt.org عام
│ ├── page.tsx # الصفحة الرئيسية
│ ├── pricing/
│ ├── features/
│ ├── community/ # مركز الكتالوج
│ └── docs/ # عارض Fumadocs
│
├── (saas-dashboard)/ # المشغّل (DEVELOPER فقط)
│ ├── dashboard/
│ ├── tenants/ # إدارة المدارس
│ ├── billing/
│ ├── sales/
│ ├── domains/
│ ├── observability/
│ └── (catalog)/catalog/ # كتالوج محتوى المنصة
│
├── (auth)/ # تسجيل دخول، انضمام، إعادة تعيين، OAuth
├── onboarding/ # معالج إنشاء المدرسة
├── settings/
├── my-school/ # منتقي المدرسة
│
└── s/[subdomain]/ # مسارات لكل مستأجر (هدف إعادة الكتابة)
├── (school-marketing)/ # موقع المستأجر العام
│ ├── page.tsx # رئيسية المدرسة
│ ├── admissions/
│ ├── academic/
│ ├── about/
│ ├── tour/
│ └── inquiry/
│
├── application/ # تقديم عام من 9 خطوات
│
└── (school-dashboard)/ # المنصة المصادَق عليها
├── dashboard/
├── admission/ # إدارة القبول
├── attendance/ # تتبّع الحضور
├── timetable/
├── exams/
├── lumos/ # LMS
├── library/
├── finance/
├── billing/
├── messages/
├── notifications/
├── transportation/
├── settings/
└── (listings)/ # كيانات CRUD
├── announcements/
├── assignments/
├── classes/
├── classrooms/
├── events/
├── grades/
├── lessons/
├── parents/
├── staff/
├── students/
├── subjects/
└── teachers/مقطع s/[subdomain]/ داخلي فقط. الـmiddleware يعيد كتابة school.databayt.org/dashboard → /[lang]/s/school/dashboard. كود العميل يستخدم مسارات نسبية للمستأجر.
المكونات (src/components/)
المسارات تعكس المكونات 1:1. ملف الصفحة رفيع — يستورد ويعرض content.tsx للميزة.
// src/app/[lang]/s/[subdomain]/(school-dashboard)/(listings)/students/page.tsx
import { Content } from "@/components/school-dashboard/listings/students/content"
export default function StudentsPage() {
return <Content />
}مجلدات المكونات الرئيسية
| المجلد | الغرض |
|---|---|
ui/ | shadcn/ui primitives (button, input, card, dialog, …) |
atom/ | تركيبات من 2+ primitives لأنماط قابلة للإعادة |
template/ | تخطيطات صفحة كاملة (header, sidebar, footer) |
auth/ | المصادقة (login, join, reset, OAuth, بوابات الأدوار) |
onboarding/ | معالج إنشاء المدرسة من 18 خطوة |
school-dashboard/ | ميزات منصة المدرسة |
saas-dashboard/ | ميزات لوحة المشغّل |
saas-marketing/ | مكونات تسويق SaaS |
school-marketing/ | مكونات الموقع العام للمدرسة |
lumos/ | LMS (مساقات، dashboard، دفع) |
library/ | المكتبة الرقمية |
internationalization/ | i18n (مبدّل اللغة، RTL، قواميس) |
theme/ | مزوّد السمة + المبدّلات |
providers/ | React contexts |
tenant/, school-switcher/ | UI متعدد المستأجرين |
profile/ | ملف المستخدم (لكل دور) |
docs/, mdx/ | عرض الوثائق |
file/ | رفع، تصفّح، تصدير، استيراد، طباعة، توليد |
crud-modal/, view-toggle/ | أنماط CRUD وعرض عامة |
rich-text-editor/, chatbot/ | محرر نص + AI chat |
monitoring/, offline/ | Observability + PWA |
billingsdk/, sales/ | Billing + CRM |
لوحة المدرسة (src/components/school-dashboard/)
| الميزة الفرعية | ما تغطّيه |
|---|---|
listings/ | 12 كياناً CRUD (announcements, assignments, classes, classrooms, events, grades, lessons, parents, staff, students, subjects, teachers) |
dashboard/ | لوحات حسب الدور (admin / teacher / student / parent / staff / accountant / principal) |
attendance/ | 11 وضع التقاط + gamification + رؤى AI |
timetable/ | منشئ بصري + اكتشاف تعارضات + توليد |
admission/ | تقديم من 9 خطوات + مراجعة وثائق بـAI + ترتيب جدارة |
exams/ | امتحانات + mock + quizzes + qbank + شهادات + كروت درجات |
finance/ | مزدوج القيد + 6 بوابات دفع + Plaid + Dwolla + رواتب + فوترة |
library/ | كتالوج + دوران |
transportation/ | سائقون + مركبات + مسارات + رحلات + صعود geofence |
messaging/ | 1:1 + جماعي + reactions + read receipts + جسر WhatsApp |
notifications/ | in-app + بريد + push |
school/ | إعداد المدرسة + علامة + أكاديمي + bulk + تقارير + أمن |
analytics/, reports/ | تحليلات عابرة للميزات |
كيانات القوائم
12 كياناً CRUD، كل واحد يتّبع نمط ملفات الميزة.
| الكيان | إضافات بارزة |
|---|---|
announcements/ | نطاق (مدرسة / فصل / دور)، قوالب |
assignments/ | تتبّع التسليم |
classes/ | تصدير قائمة الفصل، تحليلات |
classrooms/ | السعة، النوع (مختبر، غرفة، خاصة) |
events/ | تسجيل |
grades/ | transcripts، كروت درجات، ترقية |
lessons/ | صفحات لكل مادة |
parents/ | إجراء ربط طفل |
staff/ | راتب، timesheet |
students/ | معالج 12 خطوة، ملف بـ8 تبويبات، تسجيل، أرشيف، أداء |
subjects/ | متصفّح كتالوج، مساهمات |
teachers/ | معالج 9 خطوات، أقسام، جدول |
القوالب (src/components/template/)
| القالب | الاستخدام |
|---|---|
platform-sidebar/ | sidebar لوحة المدرسة |
platform-header/ | header لوحة المدرسة |
platform-footer/ | footer لوحة المدرسة |
dashboard-sidebar/, dashboard-header/ | أسطح dashboard عامة |
marketing-header/, marketing-footer/ | أسطح تسويق SaaS |
saas-header/, saas-sidebar/ | لوحة المشغّل |
site-header/, site-footer/ | تسويق المدرسة |
docs-sidebar/ | الوثائق |
mobile-nav/ | تنقّل الجوال |
listing.tsx | قالب صفحة قائمة عام |
نمط الملفات الموحّد للميزة
كل مجلد ميزة يأخذ نفس الشكل. راجع الأنماط للمرجع الكامل.
| الملف | النوع | الغرض |
|---|---|---|
content.tsx | خادم | الواجهة الرئيسية، جلب بيانات، تنظيم تخطيط |
client.tsx | عميل | حدود "use client"، يستقبل بيانات الخادم |
actions.ts | server actions | تعديلات مع auth + tenant + validation |
queries.ts | خادم | استعلامات قراءة فقط |
authorization.ts | خادم | فحوص وصول حسب الدور |
validation.ts | مشترك | Zod schemas |
types.ts | مشترك | أنواع المجال + UI |
config.ts | مشترك | ثوابت، enums، افتراضيات |
form.tsx | عميل | نماذج إنشاء / تعديل (RHF + Zod) |
table.tsx | عميل | غلاف DataTable مع أعمدة الميزة |
columns.tsx | عميل | تعريفات الأعمدة (يستخدم useMemo إن وُجدت hooks) |
card.tsx, detail.tsx, views.tsx | عميل | بطاقات KPI، صفحة تفاصيل، مبدّلات عرض |
list-params.ts | عميل | URL search-param cache (nuqs) |
util.ts | خالص | helpers الميزة |
hooks.ts / use-<x>.ts | عميل | hooks الميزة |
README.md | وثيقة | سياق على مستوى الكتلة (~40 سطر) |
ISSUE.md | وثيقة | issues نشطة، سجل منجَز (~40 سطر) |
مخطط Prisma (prisma/)
prisma/
├── schema.prisma # datasource + generator + multi-file imports
├── models/ # 73 ملف .prisma (302 نموذج، 149 enum)
│ ├── school.prisma
│ ├── auth.prisma
│ ├── students.prisma
│ ├── staff.prisma
│ ├── academic.prisma
│ ├── timetable.prisma
│ ├── attendance.prisma
│ ├── catalog.prisma
│ ├── exam.prisma
│ ├── finance-core.prisma
│ ├── subscription.prisma
│ ├── stream.prisma
│ ├── transportation.prisma
│ └── … 60 آخر
└── seeds/ # سكربتات seed
├── index.ts # مدير — لا يُشغَّل مباشرة
├── single.ts # مشغّل seed وحيد — استخدمه دائماً
└── …شغّل seeds عبر pnpm db:seed:single <name>. لا تشغّل pnpm db:seed. راجع Safe seeds.
utilities المكتبة (src/lib/)
أبرز الأدوات التي ستلمسها كثيراً.
| الملف | الغرض |
|---|---|
db.ts | Prisma client singleton |
tenant-context.ts | حلّ سياق متعدّد المستأجرين — مصدر الحقيقة لـ schoolId |
google-translate.ts | عميل Google Translate API |
translate.ts | ترجمة مع تخزين DB |
content-display.ts | getText() للترجمة عند الطلب |
auto-translate.ts | utilities ترجمة تلقائية |
stripe.ts | مدفوعات Stripe |
cloudfront.ts | توقيع CloudFront CDN |
rate-limit.ts | تحديد معدل API |
oauth-redirect.ts | تعامل OAuth callback |
school-access.ts | تحكّم وصول المدرسة |
mapbox.ts | Mapbox geocoding |
format-date.ts | تنسيق التواريخ |
join-code.ts | توليد كود انضمام للمدرسة |
payment/providers/ | 6 بوابات دفع (stripe, bankak, tap, bank-transfer, cash, mobile-money) |
email-templates/ | قوالب React Email |
القواعد المفتاحية
| القاعدة | التفصيل |
|---|---|
| مدير الحزم | pnpm فقط (متطلب Vercel) |
| البيئة | .env واحد — لا .env.local ولا .env.development |
| عزل المستأجرين | كل استعلام DB يتضمّن schoolId |
| نمط المرآة | مسارات app/ تطابق 1:1 مجلدات components/ |
| HTML دلالي | لا فئات text-* / font-* مكتوبة |
| توجيه اللغة | كل المسارات تحت [lang]/ لـar / en |
| توجيه النطاق الفرعي | مسارات المدرسة تحت s/[subdomain]/ (داخلي فقط) |
| CSS منطقي | ms-*, me-*, ps-*, pe-* — لا ml-*, mr-*, pl-*, pr-* |
| Import alias | @/* → ./src/* |
| المنفذ | 3000 دائماً في التطوير |
| Seeding | دائماً pnpm db:seed:single <name> — لا pnpm db:seed |
استيرادات شائعة
import { auth } from "@/auth"
import { db } from "@/lib/db"
import { getTenantContext } from "@/lib/tenant-context"
import { cn } from "@/lib/utils"
import { Button } from "@/components/ui/button"
import { Card } from "@/components/ui/card"
import { PageHeader } from "@/components/atom/page-header"
import { Content } from "@/components/school-dashboard/listings/students/content"
import { PlatformSidebar } from "@/components/template/platform-sidebar"
import { getText } from "@/components/translation/display"انظر أيضاً
- البنية المعمارية — شرح نمط المرآة
- الأنماط — أعراف الكود لكل ميزة
- تعدد المستأجرين — توجيه النطاق الفرعي + سياق المستأجر
- قاعدة البيانات — نماذج Prisma + قواعد العزل
- الحزمة — اختيارات التقنية الكاملة
On This Page
جذر المشروعالمسارات (src/app/)نقاط الدخولشجرة المساراتالمكونات (src/components/)مجلدات المكونات الرئيسيةلوحة المدرسة (src/components/school-dashboard/)كيانات القوائمالقوالب (src/components/template/)نمط الملفات الموحّد للميزةمخطط Prisma (prisma/)utilities المكتبة (src/lib/)القواعد المفتاحيةاستيرادات شائعةانظر أيضاً