Architecture

ארכיטקטורת האפליקציה

דף זה מתאר את הארכיטקטורה הכללית של אוצריא — אפליקציית Flutter רב־פלטפורמית (Windows, Linux, Android, iOS, macOS) לספרייה תורנית.

עקרונות יסוד

תבנית BLoC

ניהול המצב (State Management) מבוסס על חבילת flutter_bloc. כל פיצ'ר בנוי מ־שלושה חלקים:

• Events — פעולות משתמש או אירועי מערכת (מחלקות sealed היורשות מ־Equatable).
• States — מצבי UI (Initial / Loading / Loaded / Error).
• Bloc — הלוגיקה העסקית שממירה אירועים למצבים.

ה־BLoCs הראשיים נרשמים ב־AppBootstrap (ראו רצף האתחול): SettingsBloc, LibraryBloc, TabsBloc, NavigationBloc, IndexingBloc, HistoryBloc, BookmarkBloc, WorkspaceBloc, FindRefBloc, PersonalNotesBloc, PluginSystemBloc, LibraryUpdateBloc ועוד. Observer גלובלי (AppBlocObserver ב־lib/app_bloc_observer.dart) מדפיס שגיאות במצב debug.

תבנית Repository

כל גישה לנתונים (מסד נתונים, קבצים, רשת) עוברת דרך שכבת Repository שמפרידה בין הלוגיקה העסקית לשכבת הנתונים. פירוט בשכבת הנתונים.

מבנה פיצ'ר סטנדרטי

lib/feature_name/
├── bloc/          # feature_bloc.dart, feature_event.dart, feature_state.dart
├── models/        # מודלים
├── repository/    # שכבת נתונים
└── view/          # מסכים ו-widgets

מבנה התיקיות ב־lib/

תיקייה	תפקיד
main.dart, app.dart	נקודת כניסה, אתחול, MaterialApp
navigation/	ניווט ראשי, המסך הראשי, שערי startup
tabs/	מערכת הטאבים (טקסט, PDF, חיפוש, משולב)
workspaces/	שולחנות עבודה
library/	מסך עיון הספרייה
text_book/	קורא ספרי הטקסט (הפיצ'ר הגדול ביותר)
pdf_book/	קורא PDF
search/	חיפוש מלא־טקסט (מנוע Tantivy ב־Rust)
indexing/	בניית אינדקס החיפוש
find_ref/	איתור מקורות (קפיצה למראה מקום)
data/	ספקי נתונים ו־repositories מרכזיים
models/	מודלים גלובליים (Book, Links, TOC)
settings/	הגדרות, גיבוי, מיקום ספרייה
bookmarks/, history/, personal_notes/	תוכן אישי
plugins/	מערכת התוספים
tools/	כלים מובנים (מילון, לוח שנה, גימטריה ועוד)
library_update/	עדכון הספרייה (דלתא/מלא)
update/	עדכון האפליקציה עצמה
migration/	מיגרציות DB וסנכרון רקע
user_content_import/	ייבוא תוכן משתמש (CSV קישורים ודורות)
external_catalog/	קטלוג ספרים חיצוני
theme/	מערכת העיצוב ([[פירוט
widgets/	רכיבי UI משותפים ([[פירוט
shortcuts/	קיצורי מקלדת ([[פירוט
core/	תשתיות ליבה: UiSnack, הודעות, לוגים, חלון
services/	שירותים כלליים (דיווח שגיאות, פרטי ספר וכו')
printing/	הדפסה
work_status/	סטטוס עבודות רקע
tour/	סיור היכרות למשתמש חדש
empty_library/	מסך ספרייה ריקה והורדה ראשונית
utils/	כלי עזר (פתיחת ספר, פרסור TOC ועוד)

עיקרון "מקור אמת יחיד"

עיקרון חוזר בקוד — לכל סוג החלטה יש מקום אחד בלבד:

נושא	מקור האמת
מידות, ריווח, רדיוסים	AppTokens (lib/theme/app_tokens.dart)
בניית ColorScheme	AppThemeData.createColorScheme — משותף לאפליקציה ולתוספים
קיצורי מקלדת	ShortcutValidator.defaultShortcuts
מיפוי מקשים	KeyMap (lib/shortcuts/key_map.dart)
טקסטים של הודעות למשתמש	קטלוגי lib/core/messages/
קיבוץ מפרשים	buildCommentatorGroups

התמדה (Persistence)

• Hive — boxes: tabs, workspaces, history, bookmarks, error_reports_queue.
• flutter_settings_screens (Settings) עם HiveCache (נפילה ל־SharePreferenceCache) — הגדרות האפליקציה.
• SQLite — seforim.db (ספריית הספרים, לקריאה בלבד), cache.db (נתוני ריצה), user_books.db (ספרים אישיים). פירוט בשכבת הנתונים.

תקשורת בין רכיבים מנותקים

דוגמה בולטת: WorkspaceBloc אינו מחזיק הפניה ל־TabsBloc. החיבור נעשה דרך callback‏ onWorkspaceTabsChanged שנקבע ב־AppBootstrap וממופה ל־TabsBloc.ReplaceAllTabs. כל העתקת טאב עוברת דרך OpenedTab.from (שיבוט אמיתי) כדי למנוע שיתוף controllers בין שולחנות עבודה.

Deep Links — ציר מרכזי

כתובות otzaria:// הן מנגנון אחיד לפתיחת מסכים, ספרים, כלים ותוספים. הן מגיעות מארבעה מקורות:

1. ארגומנטים של שורת הפקודה (הפעלה חיצונית)
2. ‏MethodChannel נייטיבי (ExternalActivationChannel)
3. תור מבוסס־קבצים (ExternalActivationQueue) — למופע יחיד (single instance)
4. מתוך האפליקציה עצמה (handleInternalDeepLink) — גם קיצורי מקלדת לכלים/תוספים משתמשים בזה

כולם עוברים פרסור ב־ExternalUriRouter למחלקות ExternalUriAction (sealed), ומטופלים ב־_dispatchExternalUriAction שב־MainWindowScreen.

תמיכת RTL

האפליקציה קובעת locale: Locale("he", "IL") גלובלית — כל העץ RTL כברירת מחדל:

• RtlTextField — שדה טקסט עם תיקוני RTL לדסקטופ (חיצים, סמן, בחירה). אין להשתמש ב־TextField רגיל.
• RtlIcon — אייקונים כיווניים מתהפכים אוטומטית ב־RTL (מפות מראה ב־lib/widgets/misc/rtl_icon.dart).
• קיצורי מקלדת נבדקים לפי physicalKey — עובדים גם בפריסת מקלדת עברית.

דפים קשורים

• רצף האתחול והפעלת האפליקציה
• שכבת הנתונים
• טאבים ושולחנות עבודה
• מערכת העיצוב
• רכיבי UI משותפים
• מדריך פיתוח