الهيكل

هيكل الدلائل

نظرة عامة

يتبع Databayt بنية نمطية قائمة على الميزات مصممة للتوسع وإعادة الاستخدام وسهولة الصيانة. يدعم هيكلنا أنماط الخدمات المصغرة والواجهات الأمامية المصغرة.

المبادئ الأساسية

• تنظيم مدفوع بـ URL: كل مسار URL يرتبط مباشرة بهياكل دلائل متوقعة
• نمطية قائمة على الميزات: كل ميزة مكتفية ذاتياً مع أنماط ملفات متسقة
• طبقات المكونات: مكونات UI منظمة في طبقات ذرية وقوالب وميزات
• أنماط قابلة لإعادة الاستخدام: اصطلاحات ملفات معيارية عبر جميع الميزات
• صديق للمصدر المفتوح: هيكل واضح وموثق لمساهمات المجتمع

هيكل جذر المشروع

CopyDatabayt/
├── public/                     # الأصول الثابتة
├── src/                       # الكود المصدري
│   ├── app/                   # صفحات وتوجيه Next.js App Router
│   ├── components/            # المكونات القابلة لإعادة الاستخدام
│   ├── lib/                   # الأدوات والتكوينات المشتركة
│   └── types/                 # تعريفات TypeScript العامة
├── docs/                      # التوثيق
├── .env.local                 # متغيرات البيئة
├── next.config.js             # تكوين Next.js
├── package.json               # التبعيات
├── tailwind.config.js         # تكوين Tailwind CSS
└── tsconfig.json              # تكوين TypeScript

هيكل دليل المصدر (src/)

دليل App (src/app/)

Copysrc/app/
├── globals.css               # الأنماط العامة
├── layout.tsx                # التخطيط الجذري
├── page.tsx                  # الصفحة الرئيسية
├── loading.tsx               # واجهة التحميل العامة
├── error.tsx                 # واجهة الخطأ العامة
├── not-found.tsx             # صفحة 404
├── gallery/                  # مسار الميزة: /gallery
│   ├── page.tsx              # صفحة المعرض الرئيسية
│   ├── layout.tsx            # تخطيط المعرض
│   └── [slug]/               # مسارات المعرض الديناميكية
└── dashboard/                # مسار الميزة: /dashboard
    ├── page.tsx              # صفحة لوحة التحكم الرئيسية
    └── analytics/            # مسار متداخل: /dashboard/analytics

دليل المكونات (src/components/)

بنية مكونات من ثلاث طبقات لأقصى قابلية لإعادة الاستخدام:

Copysrc/components/
├── ui/                       # مكونات shadcn/ui
│   ├── button.tsx
│   ├── input.tsx
│   └── ...
├── atoms/                    # مكونات ذرية قابلة لإعادة الاستخدام
│   ├── logo.tsx
│   ├── badge.tsx
│   └── spinner.tsx
├── templates/                # مكونات التخطيط والقوالب
│   ├── header.tsx
│   ├── footer.tsx
│   └── sidebar.tsx
└── gallery/                  # مكونات خاصة بالميزة
    ├── constants.ts          # ثوابت المعرض
    ├── types.ts              # تعريفات أنواع المعرض
    ├── validation.ts         # مخططات التحقق
    ├── actions.ts            # إجراءات الخادم
    ├── use-gallery.tsx       # خطافات React المخصصة
    ├── form.tsx              # مكونات النماذج
    └── card.tsx              # مكون البطاقة

نمط دليل الميزة

كل مسار URL له دليل ميزة مقابل في كل من src/app/ و src/components/.

للمسار /gallery:

• src/app/gallery/ – يحتوي مكونات صفحة Next.js ومنطق التوجيه
• src/components/gallery/ – يحتوي مكونات UI ومنطق خاص بالميزة

ملفات الميزة القياسية

تعريفات طبقات المكونات

طبقة UI (src/components/ui/)

• الغرض: مكونات نظام التصميم الأساسية من shadcn/ui
• الاستخدام: تُثبَّت عبر npx shadcn-ui@latest add [component]
• أمثلة: Button، Input، Card، Dialog، Sheet

طبقة Atoms (src/components/atoms/)

• الغرض: مكونات صغيرة قابلة لإعادة الاستخدام تتبع أنماط shadcn
• الاستخدام: مكونات ذرية مخصصة مبنية فوق طبقة UI
• أمثلة: Logo، Badge، Avatar، Spinner

طبقة Templates (src/components/templates/)

• الغرض: مكونات التخطيط والهيكل
• الاستخدام: تخطيطات الصفحات، التنقل، أقسام الصفحة الشائعة
• أمثلة: Header، Footer، Sidebar، Navigation

طبقة الميزة (src/components/[feature]/)

• الغرض: مكونات منطق الأعمال الخاصة بالميزة
• الاستخدام: المكونات التي تنفذ ميزات أعمال محددة
• أمثلة: مكونات المعرض، أدوات لوحة التحكم

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

المكونات

• مكونات React: kebab-case.tsx (مثال: user-profile.tsx)
• الخطافات: use-feature-name.tsx (مثال: use-gallery.tsx)
• الأنواع: kebab-case.ts (مثال: gallery-types.ts)

الصفحات (App Router)

• الصفحات: page.tsx
• التخطيطات: layout.tsx
• التحميل: loading.tsx
• الأخطاء: error.tsx
• غير موجود: not-found.tsx

الأدوات

• الثوابت: constants.ts أو config.ts
• الإجراءات: actions.ts
• التحقق: validation.ts
• الأدوات: utils.ts

أفضل الممارسات

تنظيم المكونات

1. مسؤولية واحدة: كل مكون يجب أن يكون له غرض واحد واضح
2. تسمية متسقة: اتبع أنماط التسمية المحددة عبر الميزات
3. أمان النوع: استخدم TypeScript لجميع المكونات والأدوات
4. أنماط التصدير: استخدم التصدير المسمى للمكونات، الافتراضي للصفحات

هيكل الملفات

1. مسارات متوقعة: هيكل URL يرتبط مباشرة بهيكل الدليل
2. عزل الميزات: حافظ على منطق الميزة داخل دلائل الميزة
3. الموارد المشتركة: ضع الكود المشترك حقاً في lib/ و components/atoms|templates/
4. التوثيق: أضف ملفات README.md للميزات المعقدة

إرشادات المساهمة

عند إضافة ميزة جديدة:

1. أنشئ هيكل المسار في src/app/[feature]/
2. أنشئ دليل المكونات في src/components/[feature]/
3. اتبع اصطلاحات الملفات باستخدام أسماء ملفات قياسية
4. أضف أنواع TypeScript لجميع هياكل البيانات
5. نفذ مخططات التحقق للنماذج وAPIs
6. اكتب خطافات مخصصة لإدارة الحالة
7. ابنِ مكونات UI تتبع أنماط نظام التصميم
8. أضف التوثيق لشرح استخدام الميزة

هذا الهيكل يضمن بقاء قاعدة كودنا منظمة وقابلة للتوسع وصديقة للمساهمين.