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 לבדיקת תוספים

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

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

דפים קשורים

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