Architecture he

🇬🇧 English

ארכיטקטורה

NavAid הוא HTML / CSS / JavaScript פשוט מעל Leaflet. ללא שלב בנייה (build), ללא bundler, ללא transpiler. מה שמופץ ב-docs/ הוא בדיוק מה שרץ.

מבנה הקבצים

ראו Directory Structure לעץ docs/ הנוכחי. בקצרה: קוד זמן-ריצה יושב ב-docs/app/, מאגרי נתונים ב-docs/data/, חבילות שפה ב-docs/i18n/, תמונות דפדפן ב-docs/assets/, וקובצי מפה סטטית ישנים ב-docs/legacy/.

סדר טעינת המודולים

תגי <script> ב-index.html נטענים בסדר המדויק הזה — אין importים:

i18n/<lang>/strings.js
  └── מגדיר window.S = { … } ל-i18n
app/core.js
  └── מרחב השמות window.NavAid, map = L.map(...), רישום הכוונון, פונקציות עזר
app/route-graph-shapes.js
  └── גוזר נקודות ניווט / גבהי קטעים / נקודות חילופי תדר מגרף השכבה
app/terrain.js
  └── רשת שטח + עזרי גובה בטוח מינימלי (MSA)
app/draw.js
  └── draw(), scheduleDraw() (מאוחד דרך rAF)
app/interact.js
  └── מטפלי אירועים של שכבת הקנבס, hit-test, גרירה
app/io.js
  └── שמירה/טעינה, exportPNG, תוכנית טיסה, KML
app/alt-pair-directions.js
  └── עזרי כיוון לזוגות גובה
app/gdrive.js
  └── ספריית מסלולים אופציונלית ב-Google Drive
app/gps.js
  └── מיקום חי, הקלטת מסלול, התראות טיסה, נפילה למצפן
app/ui.js
  └── חיווט סרגל הכלים, בורר השכבות, חוגת הסיבוב, כפתורי המפה, אתחול
app/editor.js
  └── עורך נתוני המפה של ‎?editor=1
app/assistant.js
  └── חלונית העוזר החכם (כבויה אלא אם featureAssistant דלוק)
app/offline-tiles.js
  └── חבילות מפה להורדה לשימוש לא־מקוון

כל מודול מצרף את הממשק הציבורי שלו ל-window.NavAid או נשען על פונקציה גלובלית ממודול קודם. אין מערכת מודולים.

מצב (State)

מרחב שמות גלובלי יחיד window.NavAid בתוספת מספר משתנים מקומיים למודול. צורת המצב המרכזית:

{
  waypoints: [{ lat, lng, name }],
  legs:      [{ inboundAltitude, outboundAltitude, flightSpeed,
                inLabel: { a, p }, outLabel: { a, p } }],
  notes:     [{ lat, lng, text, color, shape }]
}

מספר ה-legs תמיד max(0, waypoints.length - 1).

צינור הציור (Draw pipeline)

הרינדור מתבצע על <canvas id="overlay"> הממוקם מעל מפת Leaflet. Leaflet מטפל באריחים + זום/הסחה; NavAid מצייר את כל השאר.

כל קריאת draw():

1. שינוי גודל הקנבס להתאמה לגודל המפה.
2. ניקוי.
3. הקרנת כל המיקומים דרך map.latLngToContainerPoint(...) לקואורדינטות פיקסל נוכחיות.
4. ציור רכיבי המסלול המרכזיים בסדר מפושט זה (מאחור לפנים):
   • נקודות ניווט (אם המתג פעיל).
   • שדות תעופה (אם המתג פעיל).
   • רגליים (קו, חץ, תווית מרחק אמצע-רגל, חץ חזרה אם פעיל, הילה אם highlight-diff).
   • נקודות ציון (עיגול + שם / מספר).
   • הערות (רקע, ואז טקסט).
   • מסגרת עמוד (מלבן מקווקו אם A3/A4 פעיל).
5. שמירת המצב אם לא מייצאים.

הרשימה מקוצרת בכוונה. draw() ב־docs/app/draw.js הוא המקור המוסמך לסדר המלא, לרבות שטח, אזורים, טבעות, שכבות VOR/NOTAM, עפיפונים, עקבות, מיקום עצמי, מידע וכרטיס תוכנית הטיסה.

draw() עטוף ב-scheduleDraw() שמכווץ קריאות מרובות ל-requestAnimationFrame יחיד, ומונע צייר-יתר בזמן הסחה/זום/סיבוב.

בדיקת פגיעה (Hit testing)

interact.js משקף בדרך כלל את עדיפות הציור בסדר הפוך כך שהרכיב העליון מנצח. קואורדינטות הלחיצה מומרות לפיקסלים במכל המפה; לכל סוג רכיב יש פונקציית hit*. הסדר המפושט של רכיבי המסלול המרכזיים הוא:

hitNote -> hitWaypoint -> hitLegLabel -> hitLeg -> hitPageFrame

זה תואם את סדר הציור כך שהערות חופפות נשארות ניתנות לבחירה מעל נקודות ציון. interact.js הוא המקור המוסמך גם לעדיפויות הנוספות של תוויות קשר, סמני שכבה, NOTAM/בועות, עפיפוני מרחק מצטבר ופריטים נבחרים.

סיבוב המפה

דרך תוסף leaflet-rotate. החוגה היא פקד DOM מותאם ליד כפתורי הזום של Leaflet. אירוע ה-rotate מפעיל refreshDial() + scheduleDraw() ושומר את map.getBearing() ל-localStorage (מושתק בזמן ייצוא).

צינור ייצוא PNG

ממומש ב-io.js:

1. צילום גאומטריית מסגרת-העמוד הנוכחית.
2. בחירת זום אריח היעד: הזום המקורי הגבוה ביותר שמשאיר את תיבת התוחם המסובבת ≤ 10,000 × 10,000 פיקסל.
3. בניית רשת אריחים המכסה את המסגרת המסובבת.
4. גזירת בקשות אריחי flight-maps.com לגבולות המפה המפורסמים ומשיכת כל אריח (ישירות ל-OSM / Esri; דרך מראת הייצוא navaid-tiles.supino.org עבור שכבות המפה). אריחי 404 הם ריקים צפויים ומדולגים.
5. הרכבת האריחים על קנבס מחוץ-למסך, תוך כיבוד מחוון Map opacity.
6. הקרנה + ציור השכבה מעל, כולל נקודות ניווט ושדות תעופה כשהם מופעלים.
7. המרה ל-Blob, שחרור אינטראקציית המפה, והפעלת ההורדה.

Service worker

ראו Service Worker.

בינאום (i18n)

ראו Bilingual UI. ברמת ה-DOM: תכונות data-i18n="key" / data-i18n-title="key" / data-i18n-placeholder="key" נקראות מ-window.S. אין MessageFormat / ICU; רק חיפושי מחרוזות.

בנייה / פריסה

ללא בנייה. תיקיית docs/ היא התוצר. תהליך עבודה של GitHub Actions מרכיב main/docs/ ‎-> / ו-dev/docs/ ‎-> /staging/, משכתב את ?v= ואת NavAid.version ל-short SHA של הענף, ומפרסם ל-GitHub Pages. ראו Deployment.