Data Layer

שכבת הנתונים

הבסיס של אוצריא: שלושה מסדי SQLite, שני ספקי ספרייה (providers), ומטמונים בזיכרון.

שלושת מסדי הנתונים

שלושתם חולקים אותה סכמה ואותם DAOs‏ (lib/migration/database/), אך נפרדים פיזית:

DB	קובץ	מצב	תוכן
הספרייה הרשמית	seforim.db	קריאה בלבד	~7000 ספרים: שורות, קישורים, TOC, מהדורות
מטמון תפעולי	cache.db	כתיבה	‏outline של PDF חיצוני, טקסט DOCX מומר
ספרי משתמש	user_books.db	כתיבה	ספרים אישיים, דורות (book_generation), קישורי משתמש (user_link)

ההפרדה מאפשרת ל־seforim.db להיפתח read-only (יציבות ושיתוף), ועדכון הספרייה הרשמית לעולם לא מוחק ספרים אישיים.

סכמת seforim.db (v3)

טבלאות מרכזיות: category (עם category_closure), ‏book, ‏line, ‏TOC (‏tocText/tocEntry/line_toc), קישורים (link + ‏link_anchor/link_range), ‏connection_type, מחברים/נושאים/מקומות־דפוס, ‏book_acronym (ראשי תיבות), דורות (generation/book_generation), מהדורות (book_version/version_line), מבנים חלופיים (alt_toc_structure/alt_toc_entry), מפרשי ברירת מחדל (default_commentator/default_targum), ‏db_meta.

ניהול חיבורים — SqliteDataProvider

• החיבור הרגיל ל־seforim.db הוא read-only‏ (PRAGMA query_only=ON).
• כתיבות נדירות (עיבוד קישורים) עוברות דרך write-session זמני: סגירת ה־RO ← פתיחת RW‏ (WAL) ← ביצוע ← ‏checkpoint וחזרה ל־DELETE ← פתיחה מחדש RO. הכל בשרשרת סריאלית (_writeChain).
• ‏gate לכתיבה חיצונית (closeForExternalWrite/reopenAfterExternalWrite) — קוראים מקבילים ממתינים במקום לקבל null (תיקון לבאג "קורא ריק בעלייה").
• ‏Android: טיפול ב־Scoped Storage‏ (SQLITE_CANTOPEN).

ספקי הספרייה — lib/data/data_providers/

ממשק LibraryProvider עם שני מימושים ש־LibraryProviderManager (singleton) מתזמר לפי עדיפות:

• DatabaseLibraryProvider (עדיפות 1) — קורא מ־seforim.db + ‏user_books.db. הקובץ הגדול בשכבה (~3600 שורות).
• FileSystemLibraryProvider (עדיפות 10) — קורא קבצים מהדיסק (תיקיית אישי, ‏PDF תלמוד בבלי מובנה).

BookCompositeKey — זהות ספר

מפתח אחיד: title|categoryId|fileType|u/o — הסיומת מבדילה ספר משתמש (u) מרשמי (o), כי categoryId יכול להתקיים בשני ה־DBs. כל מסלול טעינה חייב להעביר preferUserBooks: book.isUserBook — אחרת ספר אישי עלול להיפתח כרשמי.

DatabaseLibraryProvider — נקודות עיקריות

• buildLibraryCatalog — טוען ספרים+קטגוריות בטרנזקציה אחת, בונה עץ Category, מוסיף PDF תלמוד בבלי מובנה, ומצרף ספרי משתמש תחת "ספרים אישיים" (או ממוזגים לעץ לפי הגדרה).
• getBookText/getBookToc — ניתוב ל־DB הנכון; ספר מבוסס־קובץ נקרא מהקובץ (DOCX דרך מטמון המרה).
• סריקת ספרים חיצוניים — שלב 1 ב־isolate (סריקה, השוואת גודל+זמן שינוי, פרסור TOC); שלב 2 ב־main isolate (כתיבה בלבד). כל הכתיבות דרך PersonalBooksOperationQueue (תור סריאלי).
• שאילתות כבדות (קישורים, מהדורות, מבנים חלופיים) רצות ב־isolate עם חיבור sqlite3 ישיר.

BookDatabaseResolver

מאתר ספר בין המועמדים עם fallback מדורג: ‏filePath ← ‏title+category+fileType ← ‏title+category ← ‏title.

מטמונים בזיכרון — lib/data/cache/

מטמון	תוכן
BooksCache	טבלת book המשותפת
AcronymsCache	ראשי תיבות מנורמלים מ־book_acronym (נרמול ב־isolate)
GenerationCache	דור הספר (מפות נפרדות ל־seforim ול־user_books)

כולם lazy עם warmUp() (נקרא אחרי חשיפת החלון) ומנגנון generation שמזהה clear() באמצע טעינה.

DataRepository — ‏lib/data/repository/

שכבה מרכזית (singleton) שמאחדת הכל: library (ממוטמם), getBookText/getBookToc, ו־findBooks — חיפוש הספר בספרייה:

1. נרמול השאילתה (הסרת ניקוד/טעמים/גרשיים) ופירוק למילים.
2. בניית BookSearchEntry לכל ספר: כותרת + מחבר + ראשי תיבות + דור. הסינון רץ ב־isolate.
3. התאמה fuzzy פר־מילה: הכלה או מרחק עריכה Damerau-Levenshtein עם סף תלוי־אורך.
4. מיון בשכבות: כותרת מדויקת ← מכילה ← ראשי תיבות ← ‏fuzzy, ואז סדר הדורות (מ־book_generation ב־DB בלבד), ואז ספרי משתמש, ואז ציון ההתאמה.

TantivyDataProvider

עוטף את מנוע החיפוש (Rust‏, חבילת otzaria_search_engine): ניהול האינדקס (רשימת קבצים מאונדקסים, בדיקת תאימות סכמה, טיפול בקריסות דרך sentinel), טעינת מילונים (מורפולוגי, תרגום ארמי, ראשי תיבות), וזרמי חיפוש. פירוט בחיפוש ואינדוקס.

מודלים — lib/models/

• books.dart — ‏Book אבסטרקטי: ‏TextBook, ‏PdfBook, ‏DocxBook, ‏ExternalLibraryBook. שדות מפתח: id, ‏title, ‏categoryId, ‏fileType, ‏isUserBook, ‏externalLibraryId. ‏TocEntry — צומת עץ תוכן העניינים.
• links.dart — ‏Link: קישור בין ספרים (heRef, ‏index1, ‏index2, ‏connectionType, עוגני מילה, קישורי טווח) עם מטמון LRU לתוכן.
• link_types.dart — ‏14 סוגי קישור; dependentTextTypes (מפרש/תרגום) מול הפניות. SOURCE וירטואלי — נבנה בשאילתת inverse.

lib/migration/ — שכבת ה־DAO והגנרטור

• repository/seforim_repository.dart (~3100 שורות) — כל הגישה לסכמה: קטגוריות (closure), ספרים, שורות, TOC רגיל וחלופי, קישורים, מפרשים, מחיקה מלאה.
• generator/ — ‏DatabaseGenerator: בניית ספר ב־DB מקובץ (יצירת שרשרת קטגוריות, פרסור שורות ו־TOC, עיבוד <ספר>_links.json לטבלת link).
• sync/ — סנכרון רקע של ספרים אישיים — ראו ספרים אישיים.

דפים קשורים

• עיון הספרייה
• עדכון הספרייה
• ספרים אישיים
• אינדוקס