متطلبات المنتج

Hogwarts منصة مفتوحة المصدر متعددة المستأجرين لمدارس K-12.

للقدرات المنجزة راجع MVP. للتوجه راجع Roadmap. للطبقة التجارية راجع نموذج العمل.

البنية

الحزمة التقنية

مساحة السطح

تعدد المستأجرين

تعدد المستأجرين القائم على النطاقات الفرعية يُحلّ على edge.

Copyالإنتاج:      school.databayt.org             →  /[lang]/s/school/...
المستأجر التجريبي: kingfahad.databayt.org    →  /[lang]/s/kingfahad/...
معاينة:        tenant---branch.vercel.app     →  /[lang]/s/tenant/...
التطوير:       subdomain.localhost:3000       →  /[lang]/s/subdomain/...
نطاق مخصص:    www.theirschool.com (CNAME)    →  منصة Hogwarts

تدفق الحل:

1. proxy.ts على edge يستخرج النطاق الفرعي من host.
2. النطاقات المخصصة → نطاق فرعي قانوني عبر Upstash Redis (custom-domain:${host}).
3. إعادة كتابة داخلية إلى /[lang]/s/[subdomain]/... — /s/[subdomain] داخلي فقط، لا يُستخدم في redirect() ولا Link href ولا router.push.
4. هيدر x-subdomain يُضبط لمعالجات لاحقة.
5. getTenantContext() يقرأه ويحلّ schoolId لكل استعلام Prisma.

تخزين بلغة واحدة

لا تستخدم Hogwarts أعمدة ثنائية اللغة. كل المحتوى يُخزَّن بلغة المدرسة المختارة مع حقل lang. القراءات بلغة أخرى تمرّ عبر Google Translate وتُخزَّن مؤقتاً في Translation. نصوص الواجهة في القواميس (src/components/internationalization/dictionaries/)، وgetText() (@/components/translation/display) هو الوصول القانوني.

الأدوار

ثمانية أدوار في prisma/models/auth.prisma:UserRole. الصلاحيات عبر CASL abilities (@/lib/abilities) وبوابات الأدوار على المسارات.

النطاق الوظيفي

الحالة المنجزة عبر 14 ملحمة في MVP. التالي + الرؤية في Roadmap. وثائق التفاصيل لكل ملحمة بجانبها في content/docs-en/. وكل CLAUDE.md على مستوى الكتلة (src/components/<feature>/CLAUDE.md) يوثّق عقود التنفيذ لكل ميزة.

تستطيع المدرسة: قبول المتقدمين → تسجيل الطلاب → إدارة الفصول والشُعب والمواد والجداول → تسجيل الحضور (11 وضع التقاط) → تقييم الامتحانات + توليد كروت الدرجات → تحصيل الرسوم (6 بوابات دفع) → مراسلة الأهل (تطبيق + بريد + WhatsApp) → إدارة LMS → إدارة المكتبة والنقل. كل ذلك على منصة واحدة بعزل عبر schoolId.

المتطلبات غير الوظيفية

الأداء

الأمن

• AES-256 في الراحة، TLS 1.3 في النقل.
• كلمات مرور Bcrypt (cost 12)، جلسات JWT، 2FA عبر TwoFactorToken + TwoFactorConfirmation.
• حماية brute-force عبر LoginAttempt audit + rate limits.
• RBAC على كل مسار، عزل المستأجرين على الخادم.
• تحقّق Zod على الخادم، حماية من SQL-injection وXSS.
• AuditLog بمدة احتفاظ مع أنواع أحداث منظَّمة للتعديلات الحساسة.
• 11 cron job يومياً للصيانة.

قابلية التوسّع

• Prisma connection pooling على Neon serverless PostgreSQL.
• Vercel serverless، دوال stateless، outputFileTracingExcludes للبقاء تحت 300 ميغابايت.
• S3 + CloudFront لتسليم الأصول.
• experimental.serverActions.bodySizeLimit: "10mb" للرفع.

إمكانية الوصول

• WCAG 2.1 AA كهدف.
• تنقّل بلوحة المفاتيح، دعم قارئ الشاشة، تباين ألوان ≥ 4.5:1.
• خصائص CSS منطقية — لا ml-* / mr-*. RTL يعمل بدون تجاوزات.
• HTML دلالي — لا text-* / font-* مكتوبة في كود الميزات.

الامتثال

القيود

تنطبق على كل مساهمة. تُفرَض عبر hooks وagents وبوابات المراجعة.

• الترخيص — SSPL-1.0. استضافة ذاتية مجانية. إعادة بيع Hogwarts كخدمة مُستضافة تتطلّب ترخيصاً تجارياً.
• سلامة تعدد المستأجرين. كل استعلام Prisma يتضمّن schoolId (أو يكون النموذج عاماً ويُصرَّح بذلك). اختبارات العزل في tests/multi-tenant/.
• تخزين بلغة واحدة. لا أعمدة ثنائية اللغة، حقل lang واحد لكل صف.
• CSS منطقي فقط. ms-* / me-* / ps-* / pe-* — لا ml-* / mr-* / pl-* / pr-*.
• لا عناصر HTML خام في المكونات. استخدم shadcn ui/. لا <button> / <input> / <select> خام في كود الميزات.
• نمط المرآة. المسارات تستورد من src/components/<feature>/content.tsx. الأسماء الموحّدة: content.tsx, actions.ts, queries.ts, authorization.ts, validation.ts, form.tsx, table.tsx, columns.tsx.
• .env مركزي واحد. لا .env.local ولا .env.development ولا غيرها.
• منفذ 3000 في التطوير دائماً.
• pnpm tsc --noEmit قبل أي بناء. بناء Vercel فيه typescript.ignoreBuildErrors: true لتجنّب OOM، فالـtype-check بوابة منفصلة.
• سلامة إعادة الكتابة الداخلية. /s/[subdomain] داخلي فقط. الواجهة تستخدم مسارات نسبية للمستأجر.
• كل نص واجهة عبر مفاتيح القاموس. لا نصوص إنجليزية أو عربية مكتوبة في المكونات.

مستويات الاشتراك

راجع نموذج العمل للتسعير والإيرادات. راجع المبيعات للعملية التجارية.

API والتكاملات

REST API v1

• عقد OpenAPI 3.0.
• API key auth مع rate limiting حسب المستوى.
• أحداث Webhook: student.enrolled, payment.received, grade.updated (سجل كامل في webhooks.prisma:ProcessedWebhookEvent).
• توقيع طلبات HMAC-SHA256، إعادة محاولة بـ exponential backoff.

SSO (Enterprise)

• SAML 2.0 — Okta، Azure AD، OneLogin.
• OAuth 2.0 — Google Workspace، Microsoft 365.
• SCIM لتزويد المستخدمين.

اتصالات الطرف الثالث (مبنية أو موصولة)

Stripe + bankak + tap + mobile-money + bank-transfer + cash، Plaid + Dwolla، Resend، Twilio، WhatsApp Evolution API، Google Translate، AWS S3 + CloudFront، Upstash Redis، Sentry، Mapbox + Leaflet، Anthropic + OpenAI + Groq.

نظام التصميم

التدويل

راجع الترجمة لعقد القاموس الكامل.

نهج التطوير

• إيقاع sprints أسبوعي.
• conventional commits، موقَّعة.
• مراجعة الكود بمراجع واحد على الأقل قبل الدمج إلى main.
• استهداف تغطية 80%+ على المسارات الحرجة.
• ميزانيات أداء (Lighthouse ≥ 90).
• 20% من سعة الـsprint للديون التقنية.

هرم الاختبارات

تدفق DB المحلي

عمليات Prisma المدمّرة (db execute, db push --accept-data-loss, migrate reset, DROP TABLE, TRUNCATE) محظورة عبر hooks. استخدم بروتوكول Branch-Before-Touch على Neon للعمليات الخطرة. لا تشغّل pnpm db:seed مباشرة — استخدم دائماً pnpm db:seed:single <name>.

كيف تساهم

1. اقرأ ابدأ الآن للإعداد المحلي.
2. تصفّح البنية المعمارية والأنماط.
3. اختر عنصراً من قائمة "Next" في خارطة الطريق أو افتح issue ميزة.
4. اتّبع نمط المرآة + القيود أعلاه.
5. منظومة Claude في .claude/ (50 agents، 47 commands، 16 skills) موصولة لتفرض معظم القواعد تلقائياً — pnpm dev مع CLAUDE.md للمشروع كافٍ.

نموذج المساهمة OSS — وكيف يتحوّل الوقت إلى تقدير أو حصة إيراد — في الاقتصاد المشترك.

AGENTS.md حالياً AGENTS.md.draft في جذر المستودع، وترقيته إلى AGENTS.md متابعة في Roadmap.

انظر أيضاً

• MVP — حالة 14 ملحمة منجزة مع شارات النضج
• Roadmap — الميل الأمامي والرؤية
• البنية المعمارية — تصميم النظام والأنماط
• الأنماط — أعراف الكود
• الترجمة — عقد i18n
• الاقتصاد المشترك — مساهمة OSS ومشاركة القيمة
• نموذج العمل — التسعير، المستويات، توقّعات ARR
• ابدأ الآن — الإعداد المحلي