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

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

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

- תפריט הסימניות ב-WebApp (פאנל ימין + לוח הניהול).
- APIs של ``/api/bookmarks/*`` (toggle, list, update, delete).
- מנגנוני סנכרון שמריצים התאמת שורות לאחר שהקובץ נערך.

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

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

.. list-table::
   :header-rows: 1
   :widths: 30 70

   * - שם
     - שימוש
   * - ``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
-------

.. automodule:: database.bookmarks_manager
   :noindex:
   :members:
   :undoc-members:
   :show-inheritance: