מנהל אוספים – CollectionsManager
================================

פיצ'ר "הקולקציות שלי" נשען על ``database.collections_manager.CollectionsManager`` –
שכבת שירות שמספקת CRUD מלא, חוקים חכמים, שיתוף ציבורי, ניהול פריטים
ופעילות שיתופים. העמוד מסכם את המבנה כדי שיהיה קל לחבר פיצ'רים חדשים.

רכיבי בסיס
-----------

- ``user_collections`` – אחסון מטא-דאטה של האוסף (שם, תיאור, סמל, חוקים).
- ``collection_items`` – רשימת פריטים ידניים שנבחרו על-ידי המשתמש (כולל ``tags`` ברמת הפריט).
- ``code_snippets`` / ``large_files`` – מקורות לפריטים "חכמים" (smart/mixed).
- ``collection_share_activity`` – לוגים של צפיות/הורדות בקישורי שיתוף.

אינדקסים
--------

- ``user_slug_unique`` – מונע שני אוספים עם אותו slug לאותו משתמש.
- ``user_active_updated`` – מיון יעיל לרשימת האוספים (מועדפים + זמן עדכון).
- ``unique_item`` – מבטיח שאין כפילות של אותו פריט באוסף.
- ``order_pin`` – מאפשר סדר מותאם אישית (``custom_order``) עם פריטים מוצמדים.
- ``collection_tags`` – חיפוש מהיר לפי תגיות פריטים בתוך אוסף.

סוגי אוספים
-----------

``mode`` קובע את לוגיקת ההרכבה:

- ``manual`` – המשתמש מוסיף פריטים ידנית (drag & drop, הצמדה, הערות).
- ``smart`` – מוגדרים חוקים (חיפוש, שפה, תגים, תג ריפו). הפריטים נשלפים
  מהאוסף ``code_snippets`` בהתאם לחוקים ונשמרים רק בזיכרון.
- ``mixed`` – שילוב השניים: פריטים ידניים + "חכמים" ללא כפילויות (set).

תרחישי שימוש נפוצים
-------------------

1. **ensure_default_collections** – מוודא שיוצר "שולחן עבודה" בעת הצטרפות
   משתמש חדש, כולל פינוי Cache כדי שיקבל את האוסף מיד.
2. **reorder_items** – מפעיל סדר דטרמיניסטי: pinned בראש, אחריו
   ``custom_order`` ואז ``updated_at``.
3. **compute_smart_items** – ריצה מבוקרת (limit 200) שמחזירה רק ``file_name`` +
   מקור. משמשת גם ללינקים ציבוריים.
4. **get_share_context / get_shared_file_details** – אוספים את כל המטא-נתונים
   לקישור share יחיד, כולל טעינת קבצים גדולים והסרת שדות רגישים.

חוקים ושמירה על איכות
---------------------

- מגבלה של עד 100 אוספים למשתמש ועד 5000 פריטים ידניים.
- Slug נוצר אוטומטית דרך ``_slugify`` ונשמר lowercase.
- state של workspace item חייב להיות אחד מ-``todo | in_progress | done``.
- תגיות פריטים מאומתות מול whitelist ומוגבלות ל-10 תגיות לפריט.
- Cache מנוקה בכתיבה (``_invalidate_collection_items_cache``) כדי ש-WebApp
  יראה שינויים מיד.
- שיתופים מייצרים token ייחודי ולא חושפים את מזהי ה-ObjectId של הבעלים.

שיתוף ציבורי
------------

``set_share`` מפעיל/מכבה קישור לצפייה בלבד:

1. מסמן ``share.enabled`` + token (URL-safe).
2. ``get_share_context`` מאחזר את האוסף, מטפל בפריטים חכמים ומרכיב
   ``doc_refs`` לשימוש עתידי.
3. ``collect_shared_documents`` משמש את ה-Push Worker כדי להוריד את כל
   המסמכים לתיקייה זמנית לפני שיתוף/ייצוא.

Autodoc
-------

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