#מבנה תיקיות הפרויקט

בין אם אתם משכפלים את קוד המקור מ-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: משמשים להרצה מקומית, בדיקות יחידה/אינטגרציה, ובדיקות קצה-לקצה (E2E), בהתאמה.
• 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/      # סקריפטים להעברת נתונים (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.