9
Switch language to English

الهندسة المعمارية

السابقالتالي

مهندسة لإعادة الاستخدام والمجتمع، تستخدم نمطاً موحداً قائماً على الميزات، مع الحفاظ على كل مكون مستقلاً وقابلاً للاكتشاف.

من radix، shadcn، atoms، templates، blocks، micros — إلى تحفة كاملة.

هندستنا المعمارية مصممة من الصفر لإعادة الاستخدام والنمطية وتجربة مطور عالمية المستوى. إنها ليست مجرد نظام لبناء التطبيقات؛ إنها إطار لتكوين مكونات أتمتة "ذرية" في نظام بيئي قوي وتعاوني ومعزز بالذكاء الاصطناعي.

مبادئ الهندسة المعمارية الأساسية

  1. النمطية المدفوعة بالمكونات – مستوحاة من فلسفة shadcn/ui، توفر مكونات قابلة لإعادة الاستخدام والتخصيص في حالتها الأساسية والأدنى
  2. تجربة مطور متفوقة – هيكل بديهي ومتوقع للإنتاجية
  3. قائم على الميزات وقابل للتكوين – نهج الخدمات المصغرة والواجهات الأمامية المصغرة مع مكونات مستقلة
  4. السحابة أولاً – النشر على Vercel مع Neon Postgres لقاعدة بيانات سحابية
  5. أمان النوع افتراضياً – Prisma + Zod + TypeScript عبر المجموعة
  6. غير متزامن أولاً – طلبات سحب صغيرة، قرارات موثقة، تقدم ثابت

التسلسل الهرمي للتكوين

  • طبقة الأساس: Radix UI → shadcn/ui → نظام shadcn البيئي
  • اللبنات الأساسية: UI → Atoms → Templates → Blocks → Micro → Apps

نمط المرآة

كل مسار URL ينتج دليلين: واحد في app/ للتوجيه والتخطيطات، وواحد في components/ لكل منطق الميزة. هذا الربط 1:1 يعني إذا عرفت URL، تعرف فوراً أين تجد كلاً من الصفحة ومكوناتها.

على سبيل المثال، المسار /abc ينشئ:

  • app/[lang]/abc/ — page.tsx، layout.tsx
  • components/abc/ — content.tsx، actions.ts، form.tsx، validation.ts، types.ts، use-abc.ts، README.md، ISSUE.md، إلخ.

هذا الهيكل المتوقع يزيل التخمين. الميزات الجديدة تتبع نفس النمط. إعادة الهيكلة واضحة. أدوات الذكاء الاصطناعي تفهمها فوراً.

src/— Source code directory
app/— Next.js App Router (Routing & Layouts)
[lang]/— i18n support
abc/— URL route: /abc
page.tsx— Route entry point
layout.tsx— Route layout
components/— Component Logic (Mirrors app structure)
abc/— Mirrors app/[lang]/abc/
content.tsx— Page UI: headings, sections, layout
actions.ts— Server actions: validate, mutate
config.ts— Enums, option lists, defaults
validation.ts— Zod schemas & refinements
types.ts— Domain and UI types
form.tsx— Typed forms (RHF)
card.tsx— KPIs, summaries, quick actions
all.tsx— List view with table, filters
detail.tsx— Detail view with sections
column.tsx— Table column builders
use-abc.ts— Feature hooks
README.md— Feature purpose, APIs, decisions
ISSUE.md— Known issues and follow-ups
atom/— Atomic UI components
template/— Reusable layout templates
ui/— Base UI components (shadcn/ui)

مجموعة التقنيات

  • الإطار: Next.js 16.0.3 مع App Router وTurbopack، React 19.2.0، TypeScript
  • قاعدة البيانات: PostgreSQL مع Prisma ORM 6.16.2، Neon للسحابة
  • المصادقة: NextAuth v5 (beta) مع محول Prisma، OAuth وبيانات الاعتماد
  • التنسيق: Tailwind CSS v4 مع تنسيق ألوان OKLCH، نظام تصميم مخصص
  • مكونات UI: بدائيات Radix UI + مكونات shadcn/ui مخصصة
  • التدويل: i18n مخصص مع دعم الإنجليزية/العربية (RTL)
  • التوثيق: MDX مع مكونات مخصصة
  • استراتيجية وقت التشغيل: وقت تشغيل Node.js لصفحات Prisma/bcrypt، وقت تشغيل Edge للأخرى
  • أمان النوع: TypeScript Generics تُستخدم بكثافة لإعادة الاستخدام

أنماط الملفات المعيارية

كل دليل ميزة يتبع اصطلاحات التسمية هذه:

الملفالغرض
content.tsxتكوين واجهة الميزة/الصفحة: العناوين، الأقسام، تنسيق التخطيط
actions.tsإجراءات الخادم واستدعاءات API: التحقق، نطاق المستأجر، التغيير
config.tsالتعدادات، قوائم الخيارات، التسميات، الافتراضيات للميزة
validation.tsمخططات Zod والتحسينات؛ التحليل واستنتاج الأنواع
types.tsأنواع المجال والواجهة؛ مساعدات عامة للنماذج/الجداول
form.tsxنماذج مكتوبة (RHF) مع المحللين ومعالجة الإرسال
card.tsxمكونات البطاقات لمؤشرات الأداء الرئيسية، الملخصات، الإجراءات السريعة
all.tsxعرض القائمة مع الجدول، المرشحات، التصفح
featured.tsxقائمة ميزات منتقاة تعرض الاختيارات
detail.tsxعرض التفاصيل مع الأقسام، العلاقات، الإجراءات
util.tsأدوات نقية ومحولات تُستخدم في الميزة
column.tsxبناة أعمدة الجدول المكتوبة وعارضي الخلايا
use-abc.tsخطافات الميزة: الجلب، التغييرات، الحالة المشتقة
README.mdREADME الميزة: الغرض، APIs، القرارات
ISSUE.mdالمشكلات المعروفة والمتابعات للميزة

إطار القرار

  1. نمط المرآة أولاً: كل مسار جديد في app/[lang]/ يجب أن يكون له دليل معكوس في components/
  2. إعادة استخدام المكونات: ابدأ بمكونات shadcn/ui، وسّع فقط عند الضرورة
  3. الالتزام بنمط الملف: استخدم أسماء ملفات معيارية (content.tsx، action.ts، إلخ.)
  4. سلسلة أمان النوع: مخططات Zod → أنواع TypeScript → نماذج Prisma
  5. التوافق السحابي: افتراض وقت تشغيل Edge ما لم يكن Prisma/bcrypt مطلوباً
  6. عزل الميزة: كل ميزة يجب أن تكون قابلة للنشر والاختبار بشكل مستقل
  7. التحسين التدريجي: UI → Atoms → Templates → Blocks → Micro → Apps
  8. تجربة المطور: هيكل متوقع، تسمية واضحة، قرارات موثقة

اصطلاحات التسمية

  • المكونات: kebab-case للملفات (button.tsx، user-profile.tsx)
  • الصفحات: kebab-case لشرائح المسار (user-profile، sign-in)
  • الخطافات: اصطلاح البادئة use (use-leads.ts، use-upwork.ts)
  • الأنواع: PascalCase للواجهات والأنواع
  • الثوابت: UPPER_SNAKE_CASE أو camelCase للكائنات

مرجع الملفات الحرجة

الملفالغرض
src/auth.tsتكوين NextAuth
src/middleware.tsتوجيه Auth وi18n
src/routes.tsتعريفات المسارات العامة/الخاصة
prisma/schema.prismaمخطط قاعدة البيانات
src/app/globals.cssمتغيرات السمة
src/components/ui/مكونات shadcn/ui الأساسية
src/components/atom/مكونات التصميم الذري
src/components/template/قوالب التخطيط (header، sidebar)
CLAUDE.mdإرشادات الهندسة المعمارية على مستوى المشروع

كشف الأنماط المضادة

احترس من هذه الأخطاء الشائعة:

  • مكونات لا تتبع هيكل نمط المرآة
  • مكونات متجانسة يجب تفكيكها
  • سلسلة أمان نوع مفقودة (تحققات Zod، أنواع TypeScript)
  • ملفات لا تتبع اصطلاحات التسمية المعيارية
  • ميزات مع اقتران محكم يمنع النشر المستقل
  • قيم مشفرة بدلاً من استخدام config.ts
  • استعلامات قاعدة بيانات مباشرة بدلاً من استخدام أنماط actions.ts

تفاعل نموذجي

  1. يتفاعل مستخدم مع مكون من form.tsx على واجهة Next.js الأمامية، مما يُفعّل إجراء خادم من actions.ts
  2. يتم التحقق من حمولة الطلب بواسطة مخطط Zod من validation.ts
  3. تستخدم الوظيفة السحابية عميل Prisma الآمن للاستعلام عن Neon، باستخدام واجهات من types.ts
  4. يتم بث النتيجة وإدارتها بواسطة خطاف من use-abc.ts، مما يحدث الواجهة بكفاءة