מנהל סימניות – BookmarksManager

database.bookmarks_manager.BookmarksManager הוא שכבת ה-DB הראשית שמאחורי פיצ’ר הסימניות. הוא דואג לולידציה, לאכיפת מגבלות, ליצירת אינדקסים ולסנכרון הסימניות מול שינויים בקבצי הקוד.

מתי משתמשים בו?

  • תפריט הסימניות ב-WebApp (פאנל ימין + לוח הניהול).

  • APIs של /api/bookmarks/* (toggle, list, update, delete).

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

מבנה ואינדקסים

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

שם

שימוש

unique_user_file_line

מונע כפילות באותה שורה (user_id + file_id + line_number).

unique_user_file_anchor

partial index לעוגנים בלבד, פעיל רק כאשר anchor_id הוא מחרוזת לא-ריקה – פתרון אחיד לרגרסיות מהעבר.

user_recent_bookmarks

מאפשר טעינה מהירה של היסטוריית הסימניות לממשק המשתמש.

note_text_search

אינדקס טקסטואלי לחיפוש בתוך הערות.

בנוסף מתבצע ניקוי שדות anchor_id ישנים (None / "") כדי שה-partial index לא יישבר גם כאשר יש מסמכים היסטוריים.

מגבלות שימוש

  • MAX_BOOKMARKS_PER_FILE (כיום 50) – כדי לא להציף את ה-UI.

  • MAX_BOOKMARKS_PER_USER (כיום 500) – מגביל צריכה לא אחראית.

  • צבעים מותרים מוגדרים ב-database.bookmark.VALID_COLORS.

  • אורך הערה מקסימלי MAX_NOTE_LENGTH; הערה ארוכה נחתכת אוטומטית.

תהליך Toggle

  1. נוודא שהשורה/עוגן תקינים ונמצאים בטווח המותר.

  2. נבדוק אם קיימת כבר סימנייה – במידה וכן, נמחק ונחזיר action=removed.

  3. כשאין סימנייה קיימת:

    • נבדוק מגבלות (לקובץ ולמשתמש).

    • נחשב file_hash כדי לאפשר בדיקות Drift עתידיות.

    • אם מדובר בעוגן, נייצר מספר שורה סינתטי יציב בעזרת _anchor_line_from_id (מיליארד + hash).

    • נשמור את הסימנייה ונרשום אירוע ב-bookmark_events.

סנכרון עם שינויים בקובץ

check_file_sync משווה בין גרסאות ישנות וחדשות של הקובץ (או Markdown) ומסווג את ההשפעה על כל סימנייה:

  • modified – השורה קיימת אך הטקסט השתנה.

  • moved – אותן מילים נמצאו במקום אחר בקובץ.

  • deleted – לא נמצאה התאמה, הסימנייה תסומן כלא תקפה.

הניתוח משתמש ב-difflib.SequenceMatcher עם ספים שונים למעבר ולשינוי. כל תוצאה מתועדת ב-sync_status ומאפשרת חוויית ”סימון סימניות פגומות“ ב-WebApp.

אירועים (Analytics)

כל פעולה (הוספה, מחיקה, עדכון צבע/הערה) נרשמת ב-bookmark_events עם שדה metadata. הנתונים האלו מניעים את ההודעות push ואת תרשימי השימוש.

Autodoc