#هيكل المشروع

سواء قمت باستنساخ الكود المصدري من Git أو تهيئة مشروع باستخدام create-nocobase-app، فإن مشروع NocoBase الناتج هو في الأساس مستودع متعدد الحزم (monorepo) يعتمد على Yarn Workspace.

#نظرة عامة على الدلائل العليا

يستخدم المثال التالي my-nocobase-app/ كدليل للمشروع. قد تكون هناك اختلافات طفيفة في البيئات المختلفة:

my-nocobase-app/
├── packages/              # الكود المصدري للمشروع
│   ├── plugins/           # الإضافات قيد التطوير (غير المترجمة)
├── storage/               # بيانات وقت التشغيل والمحتوى الذي يتم إنشاؤه ديناميكيًا
│   ├── apps/
│   ├── db/
│   ├── logs/
│   ├── uploads/
│   ├── plugins/           # الإضافات المترجمة (بما في ذلك تلك التي تم تحميلها عبر واجهة المستخدم)
│   └── tar/               # ملفات حزم الإضافات (.tar)
├── scripts/               # سكربتات مساعدة وأوامر أدوات
├── .env*                  # إعدادات متغيرات البيئة للبيئات المختلفة
├── lerna.json             # إعدادات مساحة عمل Lerna
├── package.json           # إعدادات الحزمة الجذرية، تعلن عن مساحة العمل والسكربتات
├── tsconfig*.json         # إعدادات TypeScript (الواجهة الأمامية، الواجهة الخلفية، تعيين المسار)
├── vitest.config.mts      # إعدادات اختبار الوحدة Vitest
└── playwright.config.ts   # إعدادات اختبار E2E Playwright

#وصف الدليل الفرعي packages/

يحتوي الدليل packages/ على الوحدات الأساسية والحزم القابلة للتوسيع في NocoBase. يعتمد المحتوى على مصدر المشروع:

• المشاريع التي تم إنشاؤها عبر create-nocobase-app: بشكل افتراضي، تتضمن فقط packages/plugins/، وتُستخدم لتخزين الكود المصدري للإضافات المخصصة. كل دليل فرعي هو حزمة npm مستقلة.
• مستودع الكود المصدري الرسمي المستنسخ: ستجد المزيد من الدلائل الفرعية، مثل core/، plugins/، pro-plugins/، presets/، وما إلى ذلك، والتي تتوافق على التوالي مع جوهر الإطار، والإضافات المدمجة، والحلول المسبقة الرسمية.

بغض النظر عن الحالة، يُعد packages/plugins هو الموقع الرئيسي لتطوير وتصحيح الإضافات المخصصة.

#دليل وقت التشغيل storage/

يخزن storage/ البيانات التي يتم إنشاؤها أثناء وقت التشغيل ومخرجات البناء. فيما يلي وصف للدلائل الفرعية الشائعة:

• apps/: الإعدادات وذاكرة التخزين المؤقت لسيناريوهات التطبيقات المتعددة.
• logs/: سجلات التشغيل ومخرجات التصحيح.
• uploads/: الملفات وموارد الوسائط التي يرفعها المستخدمون.
• plugins/: الإضافات المعبأة التي تم تحميلها عبر واجهة المستخدم أو استيرادها عبر CLI.
• tar/: حزم الإضافات المضغوطة التي يتم إنشاؤها بعد تنفيذ yarn build <plugin> --tar.

يُنصح عادةً بإضافة دليل storage إلى .gitignore والتعامل معه بشكل منفصل أثناء النشر أو النسخ الاحتياطي.

#إعدادات البيئة وسكربتات المشروع

• .env، .env.test، .env.e2e: تُستخدم على التوالي للتشغيل المحلي، واختبار الوحدة/التكامل، واختبار شامل (end-to-end).
• scripts/: يخزن سكربتات الصيانة الشائعة (مثل تهيئة قاعدة البيانات، أدوات المساعدة في النشر، وما إلى ذلك).

#مسارات تحميل الإضافات وأولويتها

قد توجد الإضافات في عدة مواقع. عند بدء تشغيل NocoBase، سيتم تحميلها بالترتيب التالي حسب الأولوية:

1. إصدار الكود المصدري في packages/plugins (للتطوير المحلي والتصحيح).
2. الإصدار المعبأ في storage/plugins (الذي تم تحميله عبر واجهة المستخدم أو استيراده عبر CLI).
3. حزم الاعتماديات في node_modules (التي تم تثبيتها عبر npm/yarn أو المدمجة في الإطار).

عندما توجد إضافة بنفس الاسم في كل من دليل الكود المصدري والدليل المعبأ، سيعطي النظام الأولوية لتحميل إصدار الكود المصدري، مما يسهل عمليات التجاوز المحلية والتصحيح.

#قالب دليل الإضافة

لإنشاء إضافة باستخدام CLI:

yarn pm create @my-project/plugin-hello

هيكل الدليل الناتج هو كما يلي:

packages/plugins/@my-project/plugin-hello/
├── dist/                    # مخرجات البناء (يتم إنشاؤها حسب الحاجة)
├── src/                     # دليل الكود المصدري
│   ├── client/              # كود الواجهة الأمامية (الكتل، الصفحات، النماذج، إلخ.)
│   │   ├── plugin.ts        # الفئة الرئيسية للإضافة من جانب العميل
│   │   └── index.ts         # نقطة الدخول من جانب العميل
│   ├── locale/              # موارد متعددة اللغات (مشتركة بين الواجهة الأمامية والخلفية)
│   ├── swagger/             # وثائق OpenAPI/Swagger
│   └── server/              # كود الواجهة الخلفية
│       ├── collections/     # تعريفات المجموعة
│       ├── commands/        # أوامر مخصصة
│       ├── migrations/      # سكربتات ترحيل قاعدة البيانات
│       ├── plugin.ts        # الفئة الرئيسية للإضافة من جانب الخادم
│       └── index.ts         # نقطة الدخول من جانب الخادم
├── index.ts                 # تصدير جسر الواجهة الأمامية والخلفية
├── client.d.ts              # تصريحات أنواع الواجهة الأمامية
├── client.js                # ناتج بناء الواجهة الأمامية
├── server.d.ts              # تصريحات أنواع الواجهة الخلفية
├── server.js                # ناتج بناء الواجهة الخلفية
├── .npmignore               # إعدادات تجاهل النشر
└── package.json

بعد اكتمال البناء، سيتم تحميل دليل dist/ وملفات client.js وserver.js عند تفعيل الإضافة.
خلال مرحلة التطوير، تحتاج فقط إلى تعديل دليل src/. قبل النشر، قم بتنفيذ yarn build <plugin> أو yarn build <plugin> --tar.