זרימת הטיפול במסמכים (Document Flow)

מפה ותפקידים

CodeKeeperBot משמש כ‑Facade ומפנה ל‑handlers/documents.py (DocumentHandler).
פונקציות עיקריות: - _handle_github_restore_zip_to_repo – שחזור ZIP לריפו קיים - _handle_github_create_repo_from_zip – יצירת ריפו חדש מקובץ ZIP - _handle_zip_import – יבוא ZIP פנימי ושחזור קבצים - _handle_zip_create – יצירת ZIP מרשימת קבצים שנאספת - _handle_textual_file – נרמול, זיהוי קידוד, ושמירת קובץ טקסט

זרימת טיפול בקובץ

        sequenceDiagram
    participant U as User
    participant B as Bot
    participant H as DocumentHandler
    participant GH as GitHub
    participant DB as MongoDB

    U->>B: שולח קובץ
    B->>H: handle_document()
    H->>H: בדיקת upload_mode
    alt github_restore_zip_to_repo
      H->>GH: Restore ZIP to repo (commit)
    else github_create_repo_from_zip
      H->>GH: Create repo + upload tree
    else zip_import
      H->>DB: Restore from internal ZIP backup
    else zip_create
      H->>H: צבירת קבצים ל‑bundle
    else textual file
      H->>DB: save_snippet/save_large_file
    end

מצבי upload_mode

github_restore_zip_to_repo
github_create_repo_from_zip
zip_import
zip_create
github או waiting_for_github_upload – העלאה ישירה דרך Handler ה‑GitHub

תלויות והזרקות

נדרשות להזנת הבנאי של DocumentHandler: - notify_admins – הודעות ניהוליות - log_user_activity – רישום פעילות משתמש - emit_event – אירועי Observability - errors_total – מונה שגיאות Prometheus - encodings_to_try – רשימת קידודים לניסיון

Best Practices

לשמור state ב‑context.user_data היכן שנדרש.
להכיל הודעות HTML בטוחות בלבד.
להקפיד על מגבלות: גודל קבצים, קצב GitHub API.
בכל הוספת מסלול חדש: לעדכן תיעוד וטסטים רלוונטיים (למשל tests/test_main_file_events.py).

שכבת אחסון (FilesFacade מול DB הישן)

כברירת מחדל DocumentHandler מנסה לשמור דרך src.infrastructure.composition.FilesFacade כדי להרוויח את כל מנגנוני ה‑DI החדשים.
אם ה‑Facade אינו זמין או מחזיר כישלון, מתקיים fallback אוטומטי לאובייקט db הגלובלי (כפי שמשתמשים בו טסטים וזרימות Legacy).
החלפה של handlers.documents.db ב‑Stub בטסטים גורמת ל‑DocumentHandler להעדיף אותו אוטומטית, ולכן אין צורך לעדכן את רוב הטסטים הישנים.
בכל שינוי ל־backend של הקבצים, יש להוסיף טסט שמכסה גם את נתיב ה‑Facade וגם את ה־fallback כדי לשמור על תאימות.