الأنماط

الاتساق هو الأساس. كل ميزة تأخذ نفس الشكل، وكل ملف له دور قانوني. الكود الجديد الذي يطابق هذه الأنماط يصبح قابلاً للمراجعة في دقائق، والذي لا يطابقها يولّد احتكاكاً.

التسمية

الملفات والمجلدات

• المكونات والملفات — kebab-case (button.tsx, user-profile.tsx).
• المسارات — مقاطع kebab-case (/user-profile, /sign-in).
• Hooks — بادئة use- (use-leads.ts).
• الأنواع — معرّفات PascalCase (interfaces, type aliases, enums).
• الثوابت — UPPER_SNAKE_CASE للقيم الأولية، camelCase للكائنات.

المعرّفات في الكود

• المكونات — PascalCase (export function UserCard()).
• الدوال — camelCase (formatCurrency).
• المتغيرات — camelCase (const userData = ...).
• الثوابت — UPPER_SNAKE_CASE (const API_BASE_URL = "...").
• الأنواع والواجهات — PascalCase (interface UserData, type ApiResponse).

قاعدة البيانات والـ API

• الجداول — snake_case (user_profiles).
• مسارات API — kebab-case (/api/user-profile).
• متغيرات البيئة — SCREAMING_SNAKE_CASE (DATABASE_URL).

أنماط الدوال

استخدم function declarations للمكونات، route handlers، والدوال المُصدَّرة — تُرفَع وتُنتج stack traces أفضل. استخدم arrow functions لـ utility callbacks القصيرة.

Copy// utility — arrow مناسب
const formatPrice = (amount: number) =>
  new Intl.NumberFormat("en-US", { style: "currency", currency: "USD" }).format(amount)
 
// component — function declaration
export function UserProfile({ userId }: Props) {
  const { user, loading } = useUser(userId)
  if (loading) return <Skeleton />
  return <Card>{user.name}</Card>
}

Server actions وجلب البيانات

• التعديلات في actions.ts مع "use server" في الأعلى.
• القراءات في queries.ts. دوال خادم خالصة، لا حاجة لـ"use server" ما لم تُستدعَ من العميل.
• كل server action يشغّل التدفق المؤلَّف من 5 خطوات: auth → tenant → permission → validate → execute + revalidate.
• Server actions تُعيد ActionResponse<T> من @/lib/action-response.
• مكونات الخادم تجلب عبر queries.ts وتمرّر البيانات لمكونات العميل كـ props.

هرم المكونات

نمط المرآة

كل URL ينتج مجلدين — أحدهما في app/ (التوجيه، اللوايآت، page.tsx)، والآخر في components/<feature>/ (كل ما عدا ذلك). راجع وثيقة البنية المعمارية للخريطة الكاملة.

src/app/[lang]/s/[subdomain]/(school-dashboard)/students/page.tsx
  → يستورد من src/components/school-dashboard/listings/students/content.tsx

أنماط الملفات الموحّدة لكل ميزة

المحتوى القانوني الكامل لكل ملف يعيش في الوثيقة المرتبطة — هذه الصفحة فهرس.

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

• كل نموذج أعمال يحمل schoolId.
• كل استعلام يُحدَّد بـ schoolId. غياب schoolId = تسريب بيانات.
• getTenantContext() هو مصدر الحقيقة لـ schoolId الحالي.
• اكتشاف النطاق الفرعي يحدث في الـmiddleware، وسياق المستأجر يحلّه.

راجع تعدد المستأجرين للبنية الكاملة.

TypeScript

• strict mode مُفعَّل. لا any، ولا as any.
• import type للاستيرادات النوعية فقط.
• اشتقاق الأنواع من Zod عبر z.infer. اشتقاق أنواع صفوف Prisma عبر Prisma.XxxGetPayload.
• discriminated unions لآلات الحالة (ActionResponse<T>, حالة خطوات المعالج).
• enum فقط حين تعبر القيم حدود runtime، وإلا فضّل string literal unions.

التنسيق

• Tailwind 4 مع OKLCH tokens.
• HTML دلالي — لا text-* / font-* مكتوبة في كود الميزات، اعتمد على المُصيِّر.
• tokens واعية للسمة فقط — text-foreground, bg-card, border-border. لا hex.
• خصائص منطقية للـRTL — ms-, me-, ps-, pe-, start-, end-. لا ml- ولا pl- ولا left- ولا right-.

معالجة الأخطاء

• server actions تُعيد errorCode، لا نصوصاً إنجليزية. القاموس يربطها على العميل.
• لا ترمي خطأً للعميل أبداً. التقطه في الـaction وأعد استجابة منظَّمة.
• حدود error.tsx تتولّى استثناءات شجرة المكونات.
• console.error لتشخيصات الخادم، ولا تستخدم console.log في الكود المشحون.

الأداء

• مكونات الخادم افتراضياً، "use client" فقط عند الحاجة.
• وازِ awaits المستقلة بـ Promise.all.
• revalidatePath بعد التعديلات.
• لفّ الحسابات الثقيلة في useMemo، ولفّ الـcallbacks المستقرة في useCallback عند القياس فقط.
• بثّ حيث أمكن — حدود Suspense داخل مكونات الخادم.

الاعتماد

عند إضافة كود جديد:

1. اختر أقرب مجلد ميزة قائم وانسخ شكله.
2. طابق التسمية ومجموعة الملفات تماماً.
3. قاوم رغبة اختراع ملف جديد (utils.ts, helpers.ts)، استخدم الأسماء القانونية.
4. إن لم يلائم شيءٌ فعلاً، اكتب ملاحظة في README.md كي يعرف من بعدك السبب.