הגדרת Medusa 2 Admin: ווידג'טים, פריסה, אופטימיזציה

Medusa JS אדמין פאנל: היכן נשברת שליטה בחנות

פאנל האדמין הסטנדרטי של Medusa JS מכסה את התרחיש הבסיסי: מוצרים, הזמנות, לקוחות, מחסנים. כל עוד הקטלוג הוא מאה פריטים ואזור אחד, הכל עובד. ברגע שמופיעים מספר מחסנים, עשרות אלפי SKU ותפקידי עובדים, מתחילות להופיע נקודות צוואר בקבוק.

הראשון — טעינה איטית של רשימות מוצרים. האדמין שולח בקשות ליחסים (וריאנטים, מחירים, מלאי, קולקציות) ובלי ציון מפורש של שדות מושך את כל האובייקט בשלמותו. בעשרים עד שלושים אלף פריטים הדף נפתח בעשרות שניות, הפילטרים "נתקעים", והמנהל עובר לעבוד בטבלה.

השני — פעולות ידניות: עריכה המונית של מחירים, שיוך קטגוריות, חישוב מחדש של הנחות נעשים מוצר אחר מוצר, כי אין פעולות המוניות סטנדרטיות.

השלישי והיקר ביותר — אי-התאמה במלאי. הזמנות, החזרות ומחיקות מתקיימות במקומות שונים, הסנכרון עם 1С או מרקטפלייס מתבצע לפי לוח זמנים, וברגע נתון האדמין מציג לא את מה שבאמת נמצא במחסן. התוצאה — מכירה של מה שאין, ובדיקה ידנית.

הרביעי — היעדר ווידג'טים נדרשים: למחלקה יש מטריקות משלה (מחזוריות, שיעור ביטולים, סטטוס אספקה), אבל אי אפשר להטמיע אותן בדשבורד בלי לשנות קוד.

התאמה אישית של אדמין Medusa פותרת זאת נקודתית: שאילתות מוגדרות עם עימוד ופילטרים בצד השרת, פעולות המוניות, ווידג'טים לתפקידים ספציפיים, מקור אמת אחיד למלאי. מפרקים כיצד זה נסגר.

מה נותן ממשק הניהול המשודרג: ווידג'טים, תפקידים, מהירות

ווידג'טים מותאמים אישית במקום שינוי הליבה

לוח הניהול הסטנדרטי מכסה תרחישים בסיסיים, אך ברגע שמופיעות ישויות משל עצמך — מחסן, תוכנית נאמנות, אישורים — הצוות מתחיל לערוך את הליבה. ווידג'טים ב-Medusa 2 מתחברים דרך נקודות הרחבה וחיים בנפרד מבסיס הקוד הראשי: עדכון הפלטפורמה אינו שובר את ההתאמות.

בפועל הדבר מקטין את נפח הקוד שיש לבדוק מחדש בכל שדרוג פי כמה — במקום עריכת עשרות קבצים נשאר מודול מבודד אחד.

תפקידים והרשאות: גישה לפי פעולות, ולא "הכול לכולם"

הפרדת הגישה נבנית על תפקידים עם סט הרשאות לפעולות ספציפיות: מנהל רואה הזמנות, אך אינו נוגע במחירים ובהגדרות תשלומים; עורך תוכן עובד עם כרטיסי מוצרים ללא גישה לנתונים פיננסיים. ההרשאות נבדקות גם בממשק וגם בצד ה-API — כפתור מוסתר אינו מחליף בדיקה בשרת. הדבר מסיר סוג שלם של תקלות, שבהן עובד עם הרשאות מיותרות משנה בטעות מחירים או מוחק הזמנה.

אופטימיזציה של שאילתות: לוח הניהול מפסיק "להיתקע" בקטלוגים גדולים

הסיבה העיקרית לממשק ניהול איטי — רשימות שמושכות נתונים מקושרים בשלמותם. אנו מגבילים את בחירת השדות, מוסיפים עימוד ואינדקסים לפי מסננים אמיתיים, ומטמיעים מטמון למדריכים.

רשימת הזמנות עם עשרות אלפי רשומות נפתחת בשניות במקום עשרות שניות, ומסננים לפי סטטוס ותאריך מפסיקים לחסום את הממשק.

לשליטה בביצועים אנו משתמשים בפרופיילינג של שאילתות על נפחי נתונים אמיתיים — Medusa מספקת מדדים לכל פנייה ל-API, ולפיהם ניתן לראות איזה קטע מאט.

כיצד אנו מיישמים התאמות: שלבי עבודה הנדסית

את העבודה מתחילים בסקירה של לוח הניהול: בודקים אילו ישויות וקשרים כבר קיימים במודל הנתונים, כיצד בנויים ההרחבות הקיימות, והיכן חלים פערים בין הרשאות התפקידים לבין תחומי האחריות בפועל של העובדים. התוצר — מפת נקודות ההרחבה ורשימת תרחישים שנשברים כעת או יישברו לאחר ההתאמה.

בהמשך מתכננים את סכימת האינטגרציה של הווידג'טים: אילו בלוקים מוטמעים בכרטיס ההזמנה, אילו חיים בעמוד נפרד, מה מושך נתונים ממערכות חיצוניות ומה כותב בחזרה.

1. סקירת לוח הניהול ומודל הנתונים. מתעדים את הישויות הנוכחיות, השדות המותאמים אישית, ההרחבות והפערים בין הרשאות התפקידים לבין המשימות בפועל של העובדים.
2. סכימת האינטגרציה של הווידג'טים. מגדירים נקודות הטמעה, מקורות נתונים ואופן החיבור לשירותים חיצוניים — דרך הרחבות תקניות או שכבה נפרדת מעל.
3. הגדרת תפקידי גישה. מפרידים הרשאות לפי תפקידים: מי רואה את ההזמנה כולה, מי רק את חלקו, מי מנהל מוצרים ומחירים. בודקים שההגבלות פועלות ברמת השאילתות, ולא רק בממשק.
4. בדיקת תרחישים. מריצים מסלולים מקצה לקצה: ביצוע הזמנה, החזרה, שינוי סטטוס, פעולות מרובות. בנפרד — התנהגות בעת כשלים של שירותים חיצוניים ובקשות חוזרות.
5. אופטימיזציה. מסירים שאילתות מיותרות ברשימות, מוסיפים אינדקסים עבור סינונים תכופים, בודקים זמן תגובה על מבחרים גדולים.
6. פריסה. מרכיבים תצורת סביבות, מיגרציות ומשתנים, מרימים בסביבת בדיקה, ולאחר מכן במתאר העבודה עם אפשרות לחזרה לאחור.
7. מסירת התצורה. מוסרים את לוח הניהול המוגדר, סכימת האינטגרציה, מדיניות הגישה והתיעוד לפעולות טיפוסיות.

כל שלב מסתיים בתוצאה ניתנת לבדיקה: מפת הרחבות, סכימה, מטריצת הרשאות, דוח תרחישים, תצורת סביבות. תארו את המשימה — נחזור עם הערכה ותוכנית עבור המתאר שלכם.

במה שונה ווידג'ט מותאם אישית מעריכת הליבה של Medusa?

ווידג'ט מותאם אישית הוא מודול נפרד שמתחבר ל-medusa js אדמין פאנל דרך נקודת הרחבה וחי מעל הליבה, בלי לשנות את הקבצים שלה. עריכת ליבה היא כאשר מהנדס פותח את קוד המקור של @medusajs/admin או חבילות השרת ועורך אותן ישירות: כותב מחדש ראוט, מוסיף שדה למודל, משנה את לוגיקת ביצוע ההזמנה.

מבחוץ התוצאה זהה — כפתור חדש בממשק או שדה חדש בכרטיס המוצר. ההבדל מתגלה לא ברגע הפיתוח, אלא ברגע העדכון הראשון.

ארכיטקטורת ההרחבות בנויה על כך שהליבה נשארת ארטיפקט בלתי משתנה מהרג'יסטרי של החבילות. הווידג'ט נרשם בקובץ קונפיגורציה נפרד, מקבל גישה לנתונים הדרושים דרך הוקים ו-API פומביים ואינו יודע דבר על המבנה הפנימי של המודולים השכנים.

כאשר יוצאת גרסה חדשה של Medusa, אתם מעדכנים את גרסת החבילה ובונים מחדש את האדמין — הקוד שלכם נשאר במקומו, כי הוא מעולם לא הוטמע בתוך קוד זר. בעת עריכת הליבה העדכון הופך למיזוג ידני: יש להשוות שורה אחר שורה את השינויים שלכם עם הגרסה החדשה, להעביר אותם מחדש ולבדוק ששום דבר לא נשבר.

ככל שנצברו יותר עריכות, כך יקר יותר כל עדכון וכך גבוה יותר הסיכוי שהצוות יחליט "בינתיים לא נוגעים" — ויישאר על גרסה מיושנת עם חולשות אבטחה ידועות.

הסיכונים של עריכת הליבה מצטברים מבלי לשים לב. השינוי הראשון נראה תמים, אבל כל שינוי עוקב מונח על גבי הקודם, ואחרי כמה איטרציות כבר אף אחד לא זוכר לשם מה הוגדר מחדש מתודה מסוימת.

בדיקות שנכתבו עבור ההתנהגות הסטנדרטית מתחילות להיכשל בבילד שלכם, ואי אפשר ליישם דיווחי באגים מהספק, כי אי אפשר לשחזר את הבעיה על ליבה ששונתה. ווידג'ט מוציא מחוץ לתחום סוג כזה של בעיות: הוא מבודד, אפשר לכבות אותו בשורה אחת בקונפיגורציה, והתנהגות המערכת תחזור לזו של התקן.

הכלל המעשי פשוט: כל מה שאפשר לעשות דרך ווידג'ט, אירוע או מודול נפרד — נעשה כך. עריכה ישירה של הליבה מוצדקת רק במקום שבו באמת אין נקודת הרחבה פומבית — ואז זה מוגש כפאץ' עם בדיקה נפרדת וסימון שהצוות מחויב לבחון מחדש בכל עדכון. תמיכה בעדכונים במקרה כזה הופכת לתהליך מנוהל, ולא למרתון חירום אחת לרבעון.

מקרה בוחן: האצנו את ממשק הניהול והסרנו פעולות ידניות

הפרויקט — מרקטפלייס על Medusa עם קטלוג של כמה עשרות אלפי מוצרים וכעשרה ספקים. המפעילים התלוננו שרשימת ההזמנות נפתחת תוך 8-12 שניות, וחלק מהפעולות השגרתיות — התאמת מלאי, קביעת סטטוסים, הפקה מחדש של כרטיסים לאחר ייבוא — נעשו ידנית בטבלאות. שגיאות מהזנה ידנית הצטברו במשך שבועות: אי-התאמות במלאי, פריטים כפולים, סטטוסים שאבדו.

מה עשינו

את ממשק הניהול שיפרנו ולא כתבנו מחדש: הוספנו ווידג'טים לכרטיס ההזמנה והמוצר, הוצאנו פעולות תכופות לכפתורים עם אישור, ורשימות כבדות העברנו לעימוד בצד השרת ולסינון בצד ה-API. ייבוא ספקים הפך למשימת רקע עם יומן — המפעיל רואה מה עבר, מה נכשל ולמה, במקום להמתין מול המסך.

מדדים לפני ואחרי

הפעולות הידניות לא נעלמו לחלוטין — הן נשארו במקומות שבהם נדרשת החלטה של אדם. אבל השגרה עברה לאוטומציה עם יומן: אם משהו השתבש, רואים באיזה שלב ועם אילו נתונים.

מה זה נתן

הצוות הפסיק לבזבז זמן על התאמות ופתרון אי-התאמות — השעות שהתפנו עברו לעבודה עם המגוון והספקים. סוג השגיאות "האדם שכח/התבלבל" כמעט נעלם: במקום שבו קודם תיקנו ידנית, כעת פועלת בדיקה בכניסה.

עבדנו על סטאק Medusa — Medusa מספק ממשק ניהול ו-API מוכנים, ולכן השיפורים ישבו מעל בלי לכתוב מחדש את הליבה. אם יש לכם מצב דומה — תארו את המשימה, נחזור עם הערכה ותוכנית.

תאימות, מיגרציה וחזרה לאחור: מה יש לדון לפני ההתחלה

לפני ההתחלה חשוב לתעד כיצד לוח הניהול ב-Medusa ישתלב במערך הקיים: היכן יושבת מסד הנתונים, כיצד בנויה ההזדהות, מי ובאילו תפקידים נכנס לממשק.

אם בפרויקט כבר קיימת שכבת אימות משלנו או ספק כניסה חיצוני, אנו מתכננים את החיבור מראש — אחרת לאחר הפריסה צצים קונפליקטים של סשנים וכפילויות של חשבונות. בנפרד אנו מפרטים את מיגרציית הנתונים: מעבירים את הקטלוג, ההזמנות וההגדרות כך שלא נעצור את פעילות החנות.

מה אם יידרש חזרה לאחור? תוכנית החזרה לאחור מוכנה לפני השינוי הראשון בפרודקשן: מתעדים נקודת שחזור של מסד הנתונים, מנהלים גרסאות של התצורה ושומרים על הגרסה התקינה הקודמת זמינה לחזרה. אם לאחר ההעלאה משהו משתבש, חוזרים למצב המתועד תוך דקות, ולא בונים הכול מחדש.

מה בנוגע להרשאות? תפקידים והרשאות מוגדרים לפי עקרון המינימום ההכרחי: מנהל רואה הזמנות אך לא נוגע בהגדרות, אדמיניסטרטור מנהל את הקטלוג, מפתח מקבל גישה לתצורה. כל המפתחות ופרטי ההזדהות מועברים בערוץ מאובטח, ולא בהתכתבות.

לאחר המסירה תקבלו לידיכם ערכה מלאה:

• תצורה של ווידג'טים ושדות מותאמים אישית בלוח הניהול;
• סכמת תפקידים ומטריצת הרשאות גישה;
• סקריפטים למיגרציית נתונים עם תיאור סדר ההרצה;
• הוראות פריסה והגדרת סביבות;
• נוהל גיבוי ושחזור;
• תוכנית חזרה לאחור עם נקודות שחזור;
• תיעוד של האינטגרציות והשירותים החיצוניים המחוברים.

תארו את התשתית הנוכחית שלכם ואת המשימה — נחזור עם הערכה, תוכנית מיגרציה ולוחות זמנים.

לוחות זמנים של שלבי ההטמעה: מהביקורת ועד למסירה

לוחות הזמנים אינם תלויים בגודל הצוות, אלא במצב המערכת הקיימת: ככל שיש פחות פעולות ידניות ו"תקיעויות" בין המערכות בפרויקט, כך כל שלב קצר יותר. להלן הערכה למשך זמן בפרויקט טיפוסי, שבו לוח הניהול של Medusa 2 משודרג ומועלה לפרודקשן. ההערכה מתחדדת לאחר הביקורת: הפער נוצר בדרך כלל לא מהפיתוח, אלא מתיאומים והרשאות גישה.

השלבים מתבצעים בחפיפה: התכנון מתחיל לפני סיום הביקורת, והבדיקות — במקביל לשדרוג הסופי. הדבר מקצר את משך ההטמעה הכולל בכשליש בקירוב לעומת הרצה עוקבת. את משך השלבים אנו מתעדים בתוכנית ההטמעה, כדי שהלקוח יראה באיזה שלב נמצא הפרויקט ומה נדרש ממנו כקלט.

אם חלק מהעבודה כבר בוצע או שהאינטגרציות סטנדרטיות, לוחות הזמנים מתקצרים. אם נדרשת מיגרציית נתונים ממערכת ישנה או תרחישי תפקידים לא סטנדרטיים — נוסיף מרווח ביטחון. הערכה מדויקת ניתנת לאחר הביקורת: תארו את המשימה, ונחזור עם תוכנית ולוחות זמנים לכל שלב.