Development Guide

מדריך פיתוח

סביבת עבודה

• ‏Flutter (ערוץ stable; ה־CI משתמש בגרסה נעוצה — ראו קבצי ה־workflow).
• ‏Windows: ‏Visual Studio 2022 Build Tools עם רכיבי C++‏ (כולל ATL).
• שכפול ראשוני:

git clone https://github.com/Otzaria/otzaria.git
cd otzaria
flutter pub get
dart run tool/install_git_hooks.dart   # התקנת pre-commit hook (פורמט + analyze)

• רשתות מסוננות (נטפרי וכדומה): בעיות תעודת SSL בבנייה — ראו הפתרון ב־README (‏CMAKE_TLS_VERIFY=0 או התקנת תעודה).

מחזור עבודה מחייב

1. תכנון לפני ביצוע.
2. flutter analyze אחרי כל שינוי קובץ — אפס שגיאות ואזהרות לפני המשך.
3. בדיקות רלוונטיות בלבד: flutter test test/<feature>/ (לא כל הסוויטה).
4. dart format רק על קבצים ששונו.

כללי קוד מרכזיים (מ־CLAUDE.md)

• BLoC + Repository — כל פיצ'ר במבנה bloc/ + ‏models/ + ‏repository/ + ‏view/.
• RTL — ‏RtlTextField בלבד (לא TextField); אסור textDirection: TextDirection.rtl על Text (ה־locale קובע גלובלית); ‏TextDirection.ltr רק לתוכן LTR מובהק (נתיבים, כתובות דוא"ל, גרסאות, URL).
• אייקונים — רק fluentui_system_icons; אייקונים כיווניים דרך RtlIcon אם הם רשומים ב־lib/widgets/misc/rtl_icon.dart, אחרת Icon רגיל. אסור Transform ידני.
• הודעות — רק UiSnack עם טקסטים מקטלוגי lib/core/messages/ (בלי מחרוזות קשיחות).
• דיאלוגים וכפתורים — רק AppDialog (‏singleAction/twoActions/warning) ו־ActionButton (‏recommended/neutral/ghost/warning).
• צבעים — רק Theme.of(context).colorScheme; אסור hoverColor/splashColor/overlayColor/withValues(alpha:) מחוץ ל־lib/theme/.
• הערות בקוד — מעטות, עד 2 שורות, מסבירות "למה" בלבד; בלי תיעוד היסטוריה.
• תיקון באגים — קודם הסרה/החזרה של קוד, אחר כך שינוי מינימלי, ורק כמוצא אחרון קוד חדש.

בדיקות

• ‏BLoC — עם bloc_test; ‏repositories — עם mockito.
• מפת "פיצ'ר ← קובץ בדיקה" מלאה נמצאת ב־CLAUDE.md בשורש הריפו.
• מלכודות ידועות:
  • בדיקות תלויות מנוע החיפוש נכשלות מקומית בלי RustLib.init (עוברות ב־CI).
  • ‏testWidgets רץ ב־FakeAsync — ‏await על IO אמיתי בגוף בדיקה נתקע.
  • אין להריץ flutter test בכמה תהליכים במקביל.
  • דיאלוגים תלויי־גודל: לעטוף ב־MediaQuery מפורש (‏setSurfaceSize לא משפיע על MediaQuery.size בכל המקרים).

בנייה והפצה

• Windows — ‏flutter build windows; חבילות: מתקין exe (רגיל/מלא), ‏ZIP נייד, ‏MSIX לחנות Microsoft.
• Android — ‏APK / ‏Google Play; iOS — ‏App Store; macOS, Linux — ‏ZIP/tar.gz מ־releases.
• גרסאות "full" כוללות את הספרייה עצמה.
• הספרייה (seforim.db) נבנית בריפו נפרד — SeforimLibrary — שמפרסם גם patches דלתא (עדכון הספרייה).
• מנוע החיפוש — ריפו/חבילה נפרדים: otzaria_search_engine (‏Rust).

ריפואים קשורים

ריפו	תפקיד
Otzaria/otzaria	האפליקציה
Otzaria/SeforimLibrary	בניית seforim.db והפצת עדכונים
otzaria_search_engine (pub)	מנוע tantivy ב־Rust
‏Otzaria Plugin Validator	‏GitHub Action לבדיקת תוספים

דיווח שגיאות ולוגים

מערך הדיווח מפוזר בין כמה רכיבים — מפה מרוכזת:

• Sentry — מאותחל ברצף האתחול (ראו רצף האתחול); lib/core/sentry_event_filter.dart מסנן אירועים לפני שליחה.
• יומן שגיאות מקומי — lib/core/error_log_file.dart; נבדק ב־test/main_error_logging_test.dart.
• דיווח ישיר מהמשתמש — lib/services/direct_error_report_service.dart: שליחת דיווח טעות (למשל שגיאת טקסט בספר) עם תור לא־מקוון — דיווחים שנכשלו נשמרים ונשלחים כשחוזר חיבור. ניהול בהגדרות ← מערכת ← "דיווחי טעויות".
• דיווח טלפוני — lib/services/phone_report_service.dart + ‏data_collection_service.dart שאוסף את פרטי הסביבה (גרסת תוכנה/ספרייה) לדיווח.
• דיאלוג הדיווח בקורא הטקסט: lib/text_book/view/error_report_dialog.dart (נבדק ב־test/text_book/view/error_report_dialog_test.dart).

רישיון ותרומה

הקוד תחת Personal Use License 1.0 (שימוש אישי בלבד). תנאי התרומה המלאים — ב־README. בקצרה: פתיחת PR מהווה הסכמה להעברת זכויות/רישוי־מחדש לפרויקט.

דפים קשורים

• ארכיטקטורה
• רכיבי UI משותפים