ארכיטקטורת המערכת המלאה
מדריך מלא לארכיטקטורת הפורטל - רישום עסקים, בוט חכם, וזרימת תהליכים
גרסה 3.0 - עדכון אחרון: 29.8.2026
זרימת תהליך רישום ואישור עסקים
1
🏢 יצירת טיוטה (BusinessRegistration)
עסק נרשם באחת מהדרכים:
• ידנית דרך דף CompanyRegistration
• ייבוא CSV המוני דרך AdminImportBusinesses
• גירוד אוטומטי מאתר העסק (scrapeBusinessWebsite)
Status: draft
2
✏️ בעל העסק ממלא ומשלים פרטים
• נכנס דרך קישור ייחודי לעריכה
• משלים פרטים חסרים (תמונות, תיאור, שעות)
• רואה תצוגה מקדימה של העסק (BusinessDraftPreview)
• לוחץ "הגש לבדיקה"
אימות: user.email = personal_email
3
📨 הבקשה נשלחה לאישור אדמין
• סטטוס משתנה ל-"submitted"
• התראה נשלחת לאדמין (מייל + Notification entity)
• הבקשה מופיעה בדף Dashboard / RegistrationApproval
Status: submitted
4
👨💼 אדמין בודק ומאשר/דוחה
✅ אישור
1. יוצר ישות Business חדשה
2. מעתיק נתונים מ-BusinessRegistration
3. מריץ Geocoding אוטומטי
4. עדכן סטטוס ל-"approved"
5. שולח מייל לבעל העסק
approveBusinessRegistration
❌ דחייה
1. עדכן סטטוס ל-"rejected"
2. שמור סיבת דחייה
3. שלח מייל לבעל העסק
4. אפשר לערוך מחדש
5
🎉 העסק פעיל בפורטל!
הישות Business מאושרת ומופיעה בחיפושים, מפות והמלצות
is_approved: true
זרימת הבוט החכם - חיפוש והמלצות
1
👤 משתמש מזין שאילתה
דוגמאות: "מתנות לעובדים בצפון", "יועץ לבניית צ'אטבוט", "מה זה הפורטל?"
2
🚀 Main Router (smartRecommendation)
מזהה את סוג הבקשה הכללי באמצעות LLM:
ProductSearch
ServiceSearch
GeneralInformation
Other
3
🔀 Sub-Routers (ניתוב משני)
ProductSearch Sub-Router
מזהה מהות המוצר:
GiftForEmployees
EventItem
Other
ServiceSearch Sub-Router
מזהה מהות השירות:
BusinessConsulting
WellbeingDay
Other
GeneralInfo Agent
עונה על שאלות כלליות על הפורטל
4
🤖 Specialized Agents (סוכנים מיוחדים)
🎁 GiftAgent
- • מזהה פרמטרים (תקציב, כמות, אזור)
- • שואל שאלות הבהרה במידת הצורך
- • מייצר רעיונות למתנות
- • מדרג עסקים לכל רעיון
💼 ConsultingAgent
- • מזהה דרישות טכניות
- • מחפש עסקים לפי מומחיות
- • מדרג לפי התאמה לפרויקט
- • שואל על תקציב והיקף
5
✅ תוצאות למשתמש
המלצות מותאמות אישית, עסקים רלוונטיים, או שאלות הבהרה נוספות
מבנה הקבצים והתלויות
Backend Functions - רישום עסקים
functions/scrapeBusinessWebsite.js
גורד נתונים מאתר עסק
קריאה מ-CompanyRegistration
functions/bulkImportBusinesses.js
ייבוא המוני מ-CSV
AdminImportBusinesses
functions/approveBusinessRegistration.js
אישור/דחיית בקשה ויצירת Business
RegistrationApproval
functions/geocodeBusinesses.js
מיקום גיאוגרפי אוטומטי
אוטומטי באישור
Backend Functions - בוט חכם
functions/smartRecommendation.js
Main Router - נקודת הכניסה הראשית
קריאה מ-Frontend
functions/productSearchRouter.js
Sub-Router למוצרים
נקרא מ-smartRecommendation
functions/serviceSearchRouter.js
Sub-Router לשירותים
נקרא מ-smartRecommendation
functions/giftAgent.js
Agent למתנות
נקרא מ-productSearchRouter
functions/consultingAgent.js
Agent לשירותים וייעוץ
נקרא מ-serviceSearchRouter
functions/generateGiftIdeas.js
יוצר רעיונות למתנות
נקרא מ-giftAgent
functions/rankBusinessesForIdea.js
מדרג עסקים לרעיון
נקרא מ-giftAgent
Frontend Pages - רישום עסקים
pages/CompanyRegistration.js
טופס רישום עסק + עריכת טיוטה
• תמיכה ב-editId לעריכה
• אימות הרשאות (user.email = personal_email)
• גירוד אוטומטי מאתר
pages/AdminImportBusinesses.js
ייבוא CSV המוני עם מיפוי שדות
pages/Dashboard.js
ניהול בקשות (כל הסטטוסים)
pages/RegistrationApproval.js
אישור/דחיית בקשות אדמין
components/BusinessDraftPreview.jsx
תצוגה מקדימה של עסק בטיוטה
יש ליצור
Frontend Pages - בוט חכם
pages/Home.js
דף הבית - קורא ל-smartRecommendation
base44.functions.invoke('smartRecommendation', { query })components/ClarificationDialog.js
מציג שאלות הבהרה
Entities (Database)
entities/Business.json
עסקים מאושרים ופעילים
Source of Truth
entities/BusinessRegistration.json
טיוטות ובקשות רישום
סטטוסים: draft → submitted → approved/rejected
entities/Notification.json
התראות לאדמינים ומשתמשים
💡 עקרון חשוב:
Base44 = Source of Truth. כל הנתונים על עסקים חייבים להיות ב-Base44 Entities. Monday.com משמש רק לניהול תהליכי עבודה אנושיים.
פתרון בעיות נפוצות
❌ שגיאה 500 / "Canceled"
סיבות אפשריות:
- פונקציה קרסה במהלך הריצה
- שגיאת parsing ב-JSON או בפרומפט
- הצהרת משתנה (`const`/`let`) בתוך `case` ללא סוגריים
- קריאה לפונקציה שלא קיימת
- בעיית אימות (auth.me() כושלת)
פתרון:
- בדוק את הלוגים ב-Dashboard → Code → Functions
- חפש את הפונקציה האחרונה שהצליחה לרוץ
- בדוק שכל ה-case בלוקים עטופים בסוגריים מסולסלים
- ודא ש-JSON בפרומפטים תקין
- השתמש ב-auth.isAuthenticated() במקום auth.me() אם אפשר
🔒 בעיות גישה לעריכת טיוטה
תסמינים:
- משתמש לא יכול לערוך את הטיוטה שלו
- משתמש רואה "Access Denied"
פתרון:
- ודא ש-user.email תואם ל-personal_email ב-BusinessRegistration
- בדוק שהמשתמש מחובר (base44.auth.me() מחזיר נתונים)
- אדמינים צריכים גישה לכל הטיוטות
⚠️ אין לוגים מפונקציה מסוימת
משמעות: הפונקציה קרסה לפני ההדפסה הראשונה
פתרון:
- הוסף `console.log` בשורה הראשונה של הפונקציה
- בדוק שהפונקציה מיוצאת נכון: Deno.serve(async (req) => { ... })
- בדוק שאין שגיאות קומפילציה (אם יש - הן יופיעו בלוגים כ-`[ERROR]`)
🔄 הבוט מחזיר תוצאות לא רלוונטיות
סיבות:
- הפרומפטים לא מספיק ספציפיים
- קדם-הסינון חלש מדי
- העסקים ב-DB חסרים מילות מפתח
פתרון:
- חזק את קדם-הסינון ב-`giftAgent` (בדוק התאמת מילות מפתח)
- שפר את הפרומפט ב-`rankBusinessesForIdea` - הוסף דוגמאות
- עדכן תיאורים של עסקים ב-DB (הוסף מילות מפתח רלוונטיות)
💬 הבוט תמיד מחזיר שאלות הבהרה
סיבה: התנאי `hasEnoughInfo` מחמיר מדי
פתרון:
- בדוק בלוגים מה הפרמטרים שזוהו
- רכך את התנאי - אולי אין צורך בכל הפרמטרים
- אפשר ל-Agent לעבוד עם מידע חלקי
Best Practices - עקרונות לשמירה
✅ תמיד לעשות:
- הוסף לוגים מפורטים בכל שלב (במיוחד בתחילת כל פונקציה)
- עטוף כל `case` בסוגריים מסולסלים
- השתמש ב-`try/catch` וב-`console.error` לתפיסת שגיאות
- בדוק תקינות קלט בתחילת כל פונקציה
- תעדכן דף זה כשמוסיפים רכיבים חדשים
❌ לעולם אל תעשה:
- אל תשתמש ב-`const`/`let` בתוך `case` ללא סוגריים
- אל תשכח לסגור backticks בפרומפטים
- אל תקרא ישירות ל-Sub-Router מה-Frontend
- אל תשמור נתונים חשובים רק ב-Monday.com
- אל תשנה לוגיקה בלי לבדוק את כל התלויות
Quick Reference - התייחסות מהירה
🔍 איך מוסיפים סוג בקשה חדש?
- הוסף אופציה ל-`request_type` ב-Main Router
- צור Agent חדש בתיקייה agents/
- הוסף `case` ב-Main Router לניתוב
- עדכן דף זה
🎯 איך משפרים דיוק?
- חזק instructions ב-Agent
- הוסף דוגמאות לפרומפטים
- עדכן תיאורים של עסקים
- הוסף מילות מפתח רלוונטיות
🐛 איך מאתרים באגים?
- בדוק לוגים מהפונקציה האחרונה
- חפש `[ERROR]` בלוגים
- בדוק את Agent Instructions
- ודא שה-Tools מוגדרים נכון
חשוב מאוד: Functions vs. Agents
❌ Backend Functions (לא מומלץ לסוכנים):
- פונקציות Deno ידניות ב-functions/
- צריך לכתוב קוד מלא עם LLM
- קשה לתחזוקה ולשינויים
- אין יכולת "למידה" או שיפור
✅ AI Agents (מומלץ!):
- קבצי JSON פשוטים ב-agents/
- Instructions בשפה טבעית
- גישה אוטומטית ל-Tools (Entities, Functions)
- קל לעדכן וישפר את עצמו
המלצה: השתמש ב-AI Agents (agents/) לכל לוגיקה "חכמה" שצריכה להבין בקשות משתמש ולהחליט מה לעשות. השתמש ב-Functions רק לאינטגרציות טכניות (גרידת אתרים, סנכרון Monday, עיבוד תמונות).