# פיתוח תוספים לאוצריא

מערכת התוספים של אוצריא מאפשרת למפתחי צד-שלישי להרחיב את יכולות האפליקציה באמצעות מבוססות רשת (HTML, CSS, JS). תיקיית ה־SDK מכילה את קבצי התשתית: `otzaria_plugin.js`, `otzaria_plugin.d.ts`, ודוגמה עובדת (לוח שנה עברי).

## מצב פיתוח (Development Mode)

לצורך פיתוח מהיר ונוח של תוספים חדשים, אוצריא מספקת מערכת פיתוח "חיה" המזהה שינויים ומעדכנת את ממשק התוסף בזמן אמת, היישר מהתיקייה המקומית וללא צורך באריזה מחדש.

### איך להתחיל פיתוח?
1. **סביבת הרצה**: וודאו שאתם מריצים את אוצריא במצב הפיתוח (`debug mode`), דרך IDE או באמצעות הרצת `flutter run`.
2. **טעינת התיקייה**:
   - פתחו את פאנל "תוספים" באוצריא.
   - לחצו על אייקון התיקייה בסרגל העליון (יופיע רק במצב פיתוח).
   - בחרו את התיקייה המקומית במחשב שבה ממוקם קובץ ה־`manifest.json` ושאר קבצי התוסף שלכם.
3. **סמל DEV**: התוסף יופיע ברשימה עם תג `DEV`. לחיצה על התוסף תפתח אותו בדיוק כפי שהיה נפתח מגרסה ארוזה.

### היכולות במצב פיתוח
- **Hot Reload**: כל שמירה של קובץ בתוך תיקיית התוסף תזוהה אוטומטית, ואוצריא תרענן מיד את חלון ה־WebView המציג את התוסף. מטמון (Cache) מכובה כברירת מחדל בתוספי פיתוח.
- **מסך שגיאות**: אם ביצעתם שינוי ששבר את תאימות ה־`manifest.json` (לדוגמה, שינוי מבנה JSON פנימי, הסרת קובץ ה-entrypoint, מחסור בהרשאות נדרשות ועוד) יקפוץ מסך שגיאה מיוחד לתוספי פיתוח. ניתן לחזור אל מסך ה"הגדרות" משם ולרענן את המבט לאחר תיקון הקובץ.
- **הגדרות מתקדמות**: בלחיצה על צלמית ההגדרות של התוסף יתגלה מסך ייעודי לסביבת פיתוח ובו אפשרויות לריענון יזום (למקרה ובו רוצים לאפס State), צפייה בנתיב המקור ופעולה בטוחה לניתוק (הסרה מהרישום בלבד ללא מחיקת קבצי המקור שלכם מהמחשב).

### אריזה להפצה
לאחר שסיימתם לפתח את התוסף ווידאתם שהוא תקין – עליכם לארוז אותו על מנת שמשתמשי אוצריא יוכלו להתקינו. קובץ התוסף המוגמר הוא למעשה ארכיון ZIP עם סיומת `.otzplugin`. 

לצורך כך, אוצריא מספקת סקריפט אריזה פשוט משורת הפקודה. יש להריץ משורת הפקודה בתוך ממשק המערכת:

```bash
dart tool/package_plugin.dart <path/to/your/plugin/folder>
```

הסקריפט:
1. יוודא חוקיות בסיסית ושהקובץ `manifest.json` אכן קיים.
2. יארוז את תוכן התיקייה כולה (כבסיס ה-Root ולא כתיקייה מקוננת).
3. יפיק קונטיינר עם סיומת `otzplugin` במיקום של תיקיית האב, המוכן לשיתוף.

---

## עיצוב התוסף

כדי שהתוסף ייראה כחלק טבעי מאוצריא, חשוב להתאים את עיצובו לשפת ה-UI של האפליקציה.

**הנקודה החשובה ביותר:** אין לקודד צבעים ישירות. **כל הצבעים חייבים להגיע מה-API** (מאירוע `plugin.boot` או מ-`app.getTheme`), מפני שהמשתמש יכול לבחור ערכת צבעים שונה ולעבור בין מצב כהה לבהיר.

מדריך מלא — כולל Color Roles, צורות, טיפוגרפיה, כפתורים, כרטיסים ואנימציות — נמצא ב:

👉 **[DESIGN_GUIDE.md](DESIGN_GUIDE.md)**

---

אם אתם מעוניינים בapi נוסף, כתבו לנו בגיטהאב!