ממשקי משתמשים (Web)

היכן זה נמצא?

  • בבוט: תפריט ראשי > ”ממשקי משתמשים (web 🌐)“ – פתיחת דפי ה‑WebApp הרלוונטיים בדפדפן.

  • ב‑WebApp: פריטי תפריט ייעודיים יוצגו בהתאם להרשאות ולזמינות פיצ’רים.

מסכים בולטים

  • Code Execution Playground: /tools/code (פתוח לכל משתמש מחובר; הרצת קוד Premium/Admin בלבד + FEATURE_CODE_EXECUTION=true). לפרטים מלאים (אבטחה, API, מגבלות, ותפעול) ראו הרצת קוד (Code Execution Playground).

גרסאות: צפייה והשוואה

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

  • פתיחת גרסה: בתפריט ”עוד“ ← ”🕐 היסטוריה“. כל שורה ברשימה מקשרת אל /file/<id> של אותה גרסה. העמוד שנפתח הוא אותו עמוד קובץ רגיל, עם אותה הדגשת תחביר ואותה בדיקת בעלות — לא מסלול תצוגה נפרד. אותו דבר ב-/md/<id> לקובצי Markdown.

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

  • קובץ בסל המיחזור: העברה לסל מסמנת את כל הגרסאות של אותו שם קובץ יחד, ולכן אין לקובץ כזה ”גרסה אחרונה פעילה“. במקום באנר הגרסאות מוצגת הפניה אל סל המיחזור (/trash) — הפעולה הנכונה היא שחזור הקובץ, לא הוספת גרסה חדשה לקובץ מחוק.

  • קבצים גדולים: large_files הוא אוסף דריסה ואין בו מספור גרסאות, ולכן אין שם באנר.

  • שתי שמירות עם אותו מספר גרסה: אין אינדקס ייחודי על מספר הגרסה, ושתי שמירות מקבילות יכולות לקבל אותו מספר. הגרסה הנוכחית היא אחת מהן — _LATEST_VERSION_SORT מכריע לפי updated_at ואז _id — והשאלה ”האם זו הנוכחית“ נענית לפי _id של המסמך שנבחר, ולא לפי המספר: בעמוד של העותק האחר מוצג באנר ”זה עותק נוסף של גרסה N“ (המצב duplicate ב-_file_version_context) עם מעבר לנוכחית בלבד, כי השוואה ושחזור עובדים לפי מספר גרסה; ובהיסטוריה רק המסמך שנבחר מסומן is_current.

השוואה בין שתי גרסאות

/compare/<file_id> מקבל ?left= ו-?right= ומשווה כל שתי גרסאות. ברירת המחדל היא הקודמת מול הנוכחית.

  • ברשימת ההיסטוריה אפשר לסמן שתי גרסאות ולפתוח את הדיף ביניהן. סימון שלישי מחליף את הוותיקה מבין השתיים.

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

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

  • ”הגרסה הנוכחית“ נגזרת מהקובץ ולא מהמסמך שבכתובת, כך שפתיחת השוואה מתוך עמוד של גרסה ישנה מתנהגת אותו דבר.

סל המיחזור: שורה לכל קובץ

‏``/trash`` (ובבוט: תפריט הקבצים ← סל מיחזור) מציג שורה אחת לכל קובץ, גם כשכמה מגרסאותיו נמצאות בסל. השורה נושאת את מספר הגרסאות שבסל, ושני הכפתורים שעליה — שחזור ומחיקה סופית — חלים על הקובץ כולו. זו אותה הבחנה שהמחיקה כבר עושה: הקובץ הוא (user_id, file_name), וגרסה היא מסמך.

  • שחזור מחזיר את כל גרסאות הקובץ שבסל, ולא את הגרסה שהשורה הצביעה עליה. שחזור של אחת היה מחזיר קובץ עם היסטוריה קטועה. בקובץ גדול זה אחרת: לשם יש מסמך פעיל אחד בלבד, ולכן חוזרת הרוויזיה שנמחקה אחרונה, והשורה אינה מציגה מספר גרסאות. אם כבר קיים קובץ גדול פעיל באותו שם, השחזור נדחה — אחרת היו שני עותקים. ראו file_deletion.SINGLE_ACTIVE_COLLECTIONS. הבדיקה הזו נעשית בקוד, ולכן שמירה מקבילה של אותו שם עדיין יכולה לחמוק ממנה; הסגירה במסד — אינדקס ייחודי חלקי על large_files שמתיר מסמך פעיל אחד לכל שם — מתוכננת ל-PR המשך, והתנאים לה כתובים ב-docstring של file_deletion._restore_latest_revision.

  • מחיקה סופית מוחקת את אותן גרסאות. גרסאות פעילות של אותו שם אינן נמחקות — המסנן מתוחם ל“בסל“.

  • התאריכים בשורה הם המוקדמים מבין גרסאותיה. אינדקס התפוגה של הסל מוחק מסמך-מסמך ואין בו מושג של קובץ, ולכן כשגרסאות נמחקו בזמנים שונים התאריך המוקדם הוא הרגע שבו הקובץ מפסיק להיות שלם. ראו MongoDB Indexing Cookbook.

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

  • אותו שם קובץ שקיים גם ב-code_snippets וגם ב-large_files הוא שתי ישויות נפרדות, ולכן שתי שורות.

הצ’קליסט ”צעדים ראשונים“ בדשבורד

כרטיס בדשבורד, רק למשתמש מחובר, שמלמד את המערכת דרך עשייה ולא דרך חוברת הוראות: כל צעד נפתח בלחיצה, בנגיעה או במקלדת (<details>), ומציג הסבר וכפתור שמוביל ישר למקום, והוי מסתמן לבד כשהצעד בוצע באמת. הכרטיס הוא חלק מהדף ולא שכבה מעליו. כשהוא מוצג, הגריד של הדשבורד עובר לזרימה והכרטיס פורש על שתי עמודות, כי בשורות שלו טקסט ארוך: במסך של שלוש עמודות לידו נכנס עוד כרטיס אחד, ובמסך של שתיים הוא תופס את כל השורה. הצעדים, הסדר והטקסטים מוגדרים ב-STEPS ב-webapp/first_steps.py, והמונה ”X מתוך N“ נגזר מאותם מצבים שמציגים את הצעדים.

  • הסימון נגזר מהנתונים, ואין דגל לכל צעד. ערכת נושא: ui_prefs.theme במסמך המשתמש, או ערכה שנבחרה ”רק במכשיר הזה“ (הסעיף הבא). אוסף: לפחות אוסף פעיל אחד שאינו שולחן העבודה — user_has_own_collection ב-database/collections_manager.py, ושולחן העבודה מזוהה לפי WORKSPACE_COLLECTION_NAME; אוסף בארכיון נספר, ואוסף שנמחק לא. פתק: לפחות פתק אחד על לוח כלשהו (any_board_note_filter ב-sticky_notes_target.py), ופתק על קובץ לא נספר. חיבור AI: טוקן אישי או טוקן OAuth שהשרת עדיין מקבל, כלומר שלא בוטל ולא פג — user_has_live_token ב-mcp_server/token_store.py ו-subject_has_live_token ב-mcp_server/oauth_store.py, באותו כלל של verify ושל get_token. כל בדיקה מבקשת מהשרת מסמך אחד בלבד (find_one), והשרת עוצר במסמך הראשון שעונה לה — הוא לא סופר ולא ממלא מנה שלמה. בחיבור OAuth, שבו כל רענון משאיר שורה מבוטלת עד שתוקפה נגמר, המסמך הזה הוא הטוקן שתוקפו נגמר אחרון, ו-_expired מכריע עליו: אם הוא פג, פגו כולם.

  • ערכה ”רק במכשיר הזה“ נחשבת בכל המכשירים. ערכה כזו נשמרת רק ב-cookie של המכשיר, ולכן ברגע הבחירה נרשם במסמך המשתמש ui_prefs.device_theme_chosen: שנבחרה ערכה, ולא איזו (record_device_theme_choice). כל מסלול שמחיל ערכה במצב device קורא לו — /api/ui_prefs, /api/themes/shared/<id>/apply ו-/api/themes/<id>/activate — ו-test_every_writer_of_the_theme_cookie_records_a_device_choice מוצא כותב חדש שלא קורא. בחירה שנעשתה לפני שהרישום נוסף מסומנת במכשיר שלה, לפי ה-cookie.

  • נעילה. כשכל הצעדים מסומנים נשמר ui_prefs.first_steps_done, והכרטיס נעלם. הנעילה לא תלויה בנתונים: מחיקה של האוספים אחר כך לא מחזירה אותו, אבל ”הצג שוב“ מוחק אותה. היא נכתבת רק למי שלא לחץ ”הצג שוב“ (asked_to_see_again ב-webapp/first_steps.py), והתנאי יושב בכתיבה עצמה (_write_lock), כך ש“הצג שוב“ שנוחת באמצע טעינה של הדשבורד לא נדרס.

  • הסתרה ידנית ו“הצג שוב“. ”הבנתי, להסתיר“ שולח first_steps_hidden: true ל-/api/ui_prefs, וההסתרה נשמרת במסמך המשתמש, כלומר בכל המכשירים. הכרטיס יורד רק אחרי שהשרת אישר את השמירה; בכשל הוא נשאר, ומוצגת הודעה. מתחת לכפתור כתוב ”אפשר להחזיר את הכרטיס מתחתית עמוד ההגדרות“ (#firstStepsHideHint ב-webapp/templates/dashboard.html): שם, אחרי כל הכרטיסים ולפני קישור העזרה, מופיע ”הצג שוב את הצעדים הראשונים“ (#firstStepsShowAgain ב-webapp/templates/settings.html) כשהכרטיס מוסתר או נעול. את המיקום הזה מקבע test_show_again_sits_at_the_bottom_of_settings, כדי שהשורה בכרטיס לא תשקר. ”הצג שוב“ שולח first_steps_hidden: false, שנשמר כמו שנשלח, ומוחק את הנעילה. מאותו רגע הכרטיס מוצג עד שמסתירים אותו שוב, גם אחרי ריענון והחלפת ערכה. כשכל הצעדים בוצעו הוא מוצג מלא, וכל צעד נפתח בלחיצה.

  • קודם הדגלים, ורק אחריהם השאילתות. הדגלים נקראים ממסמך המשתמש שכבר נשלף בבקשה — _request_user_doc ב-webapp/app.py שולף אותו פעם אחת לבקשה, ו-inject_globals קורא מאותה שליפה. כשאחד הדגלים הוא true (is_dismissed), אף שאילתה של הצ’קליסט לא רצה.

  • כשהמסד נכשל. צעד שהבדיקה שלו נכשלה כי המסד לא ענה מוצג ”לא ידוע כרגע“, לא נספר, והנעילה לא נכתבת. בבדיקות נתפסות רק חריגות של ”המסד לא ענה“ (DB_UNAVAILABLE_ERRORS); שגיאה אחרת, כמו הרשאה שגויה, עולה, והדשבורד מציג את דף השגיאה שלו. מסמך המשתמש (_request_user_doc) ושתי הכתיבות, הנעילה (_write_lock) והרישום של ערכה במכשיר (record_device_theme_choice), הם עזר, ולכן שם כל כשל של המסד (PyMongoError) נרשם כ-WARNING והדף ממשיך: כשמסמך המשתמש לא נטען, אין כרטיס בדשבורד ואין קישור ”הצג שוב“ בהגדרות, כדי שמשתמש שהסתיר את הכרטיס לא יראה אותו חוזר בגלל תקלה; כשהנעילה לא נשמרה, הבדיקות ירוצו שוב בטעינה הבאה; וכשהרישום של ערכה במכשיר נכשל, הערכה עדיין מוחלת. באג, כלומר חריגה שאינה של המסד, עולה בכל המקרים.

  • הכפתורים. ”לבחירת ערכה“ מוביל ל-/settings#appearance, כרטיס ערכת הנושא בהגדרות. ”לעמוד האוספים“ ל-/collections. ”לוח העבודה“ ל-/boards/default, שיוצר את לוח ברירת המחדל אם עוד אין (ensure_default_board) ומפנה אליו — כי ללוח הזה אין מזהה עד שהוא נוצר. ”אני רוצה להתחבר“ ל-/settings#ai-connect.

זרימת עבודה דרך הבוט

הבוט פועל כ‑Launcher ל‑WebApp ומספק קישורים ישירים למסכים. הזרימה הטיפוסית לסוכן AI:

  1. פתיחה מהירה: בתפריט הראשי לחצו ”ממשקי משתמשים (web 🌐)“.

  2. מעבר למסך היעד: בחרו תהליך/טופס נדרש.

  3. מילוי שדות חובה ושליחה.

  4. מעקב אחר חיווי מצב (התקדמות/הצלחה/כשל) והנחיות המשך.

שדות חובה ולוגיקת ולידציה

  • שדות חובה מסומנים בכוכבית (*) ומאומתים בצד הלקוח לפני שליחה.

  • ערכים לא חוקיים יציגו הודעת שגיאה צמודה לשדה. שליחה נחסמת עד לתיקון.

  • הודעות שגיאה אינן מכילות מידע רגיש; ערכים רגישים מושחרים בלוגים.

חיווי מצב תהליך

  • In‑Progress: מחווני טעינה/התקדמות.

  • Success: חיווי ”בוצע“ וקישור להמשך פעולה (לדוגמה: צפייה בפריט/חזרה לרשימה).

  • Failure: הודעת כשל עם קוד שגיאה קצר וטיפים לפתרון.

ממשק אדמין

  • הרשאות: גישה מותנית ב‑ADMIN_USER_IDS או מדיניות הרשאות ארגונית.

  • ניהול: צפייה/אישור/דחייה של בקשות, עדכון תצורה נקודתית.

  • תצפיות: מומלץ להצליב עם דפי Observability (אובזרווביליות (Observability), Rate Limiting, מדדים (Metrics)) בעת תחקור תקלות.

דוגמאות שימוש לסוכני AI

  • פתיחת זרימה: ”פתח/י את »ממשקי משתמשים (web 🌐)« ובחר/י בתהליך הרלוונטי“.

  • מילוי טופס: ”מלא/י את כל השדות המסומנים ב‑*; עצור/י על שגיאה, הצג/י טקסט שגיאה קצר והצע/י ערך תקין“.

  • מעקב הצלחה: ”וודא/י שהתקבל חיווי Success; אם לא – הבטח/י פעולה מתקנת בהתאם לטיפים על המסך“.

אבטחה ופרטיות

  • אין לרשום סודות/PII בטפסים שאינם מיועדים לכך; שימוש במנהל הסודות בלבד.

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

הערות תאימות

  • זמינות מסכים עשויה להשתנות בין סביבות; ייתכנו דפים ניסיוניים בהדרגה.

  • קישורי הבוט יפתחו בדפדפן ברירת המחדל של המשתמש.