דילוג לתוכן
מרכז התיעוד
לאתר LinkNodes Energy
LinkNodesENERGYתיעוד

טוענים את החיפוש…

    חיפוש גם בתוך המאמרים ↑ ↓ לניווט Esc לסגירה

    לאתר החברה

    ארכיטקטורה וטכנולוגיה

    ספר הארכיטקטורה

    טופולוגיה, גבולות שירות, מסעות, חוזי אירועים, החלטות ותפעול.

    בעמוד הזה

    תכנון, מקור אמת בקוד וראיות ביצוע; אינו אישור מוכנות להפעלה מסחרית.

    תאריך: 2026-11-08. מקור: lib/systems/architecture.json.

    מצבים: deployed = רכיב פרוס עם ראיה מוגדרת; foundation = בסיס בקוד; planned = תכנון; blocked = תלות פתוחה. אף אחד מהם אינו אישור פרודקשן מלא.

    מפת הארכיטקטורה#

    A01 · שלוש כניסות, תחומי אחריות נפרדים#

    מצב: deployed. אחריות: Platform.

    אתר החברה, מוצר הלקוחות ואזור ניהול החברה פרוסים בנפרד ב־Vercel.

    • linknodesenergy.com: תוכן ציבורי ויצירת קשר. product.linknodesenergy.com: מרחבי לקוחות. admin.linknodesenergy.com: כניסה סגורה לצוות החברה.
    • APP_SURFACE נקבע בצד השרת לכל פרויקט. שינוי Host או ניווט לכתובת אחרת אינו מקנה הרשאה.
    • האתר ואזור הניהול חוסמים את נתיבי המוצר, ה־API וקובצי הספריות. אזור הניהול עדיין אינו מערכת תפעול.

    מקורות: lib/surface.ts, proxy.ts, docs/linknodes-release.md.

    A02 · ליבת מוצר מודולרית#

    מצב: foundation. אחריות: Platform.

    Next.js ו־TypeScript מרכזים את ממשקי הלקוחות ואת שכבת ה־API.

    • המודולים: זהות ומרחבים, צי ונהגים, מדיניות, טעינה, כסף, אנליטיקה ושירות.
    • PostgreSQL הוא מקור האמת לעובדות עסקיות. תורים מעבירים עבודה; אינם מקור יתרה או מצב כספי.
    • שלושת הפרויקטים חולקים מקור קוד. הפריסה הנפרדת אינה מחליפה בדיקת הרשאה בכל פעולה.

    מקורות: lib/platform/api.ts, lib/platform/domain.ts.

    A03 · זהות לעומת חברות בארגון#

    מצב: deployed. אחריות: Identity.

    Clerk מאמת אדם; חברות פעילה ב־PostgreSQL קובעת מה מותר לו לעשות.

    • JWT מאומת מול issuer מוגדר. sub הוא מזהה המשתמש; role=authenticated הוא תפקיד מסד הנתונים בלבד.
    • tenant_id שנשלח בנתיב נבדק מול חברות פעילה; הרשאות אינן נלקחות מ־user_metadata.
    • אדם יכול להחזיק מרחב אישי ולהשתייך למספר עסקים. מעבר מרחב מאפס מטמונים פרטיים.
    • סביבת Production פעילה בדומיין המוצר: 30 בדיקות עם JWT אמיתי עברו דרך Clerk, שרת האפליקציה ו־Supabase. הזמנות וביטול חברות מקצה לקצה עדיין נדרשים.

    מקורות: lib/platform/server.ts, supabase/migrations/20261107211048_platform_foundation.sql, docs/architecture-system/verification.md.

    A04 · נתונים תפעוליים ב־Supabase#

    מצב: deployed. אחריות: Data.

    סכימת המוצר נפרסה בפרויקט ev1 שנבחר; 31 טבלאות עם RLS, כולל נתוני ייחוס בחירת ספקים ופרופילי מרחב.

    • הפרויקט בארגון digitalops ובאזור סינגפור, לפי בחירת המשתמש. פרויקט Car Dealers BMS אינו חלק מהמערכת.
    • בדיקת advisor האחרונה מצאה 6 הודעות מידע על טבלאות פרטיות ללא policies — חסימת גישת לקוחות מכוונת. טבלאות בחירת הספקים נבדקו עם RLS וללא הרשאת כתיבה ישירה.
    • חיבור Clerk Production ל־Supabase עבר 18 בדיקות עם JWT אמיתי ושני משתמשים: יצירת מרחב, בידוד קריאה, חסימת כתיבה בין ארגונים וחסימת יצירת חשבונית. בדיקות שרת האפליקציה והזמנות הן שער נפרד.

    מקורות: supabase/migrations/0001_ev1.sql, supabase/migrations/20261107211048_platform_foundation.sql, lib/systems/dictionary.json, docs/provider-preferences.md, supabase/migrations/20261108013050_workspace_profiles.sql.

    A05 · עיבוד רקע ותקשורת עם עמדות#

    מצב: planned. אחריות: Charging.

    RabbitMQ ו־workers נפרדים מיועדים לפקודות, לקליטת אירועים ולהתאמות.

    • OCPP ישיר דורש gateway מתמשך עם WebSocket מחוץ לפונקציות Vercel. חיבור לרשת קיימת עשוי להשתמש ב־OCPI/API.
    • Outbox נשמר באותה טרנזקציה עם השינוי העסקי. relay מסמן פרסום רק אחרי publisher confirm.
    • צרכן מטפל במסירה חוזרת ובאירועים מחוץ לסדר. retry אינו אישור להפעיל פקודה פיזית נוספת.

    מקורות: supabase/migrations/20261107211048_platform_foundation.sql.

    A06 · סליקה ומסמכים#

    מצב: blocked. אחריות: Payments.

    בחירת PSP וגורם גובה נדרשת לפני כל תשלום אמיתי.

    • איסוף אמצעי תשלום באמצעות טופס מאוחסן של הספק; אין PAN/CVV בדפדפן שלנו, במסד או בלוגים.
    • תשלום טעינה ומנוי הם התחייבויות נפרדות; מצב טעינה אינו מוכיח שהכסף נגבה.
    • ספק חשבוניות, מע״מ, עיגול, ביטולים והתאמה לספק טעינה טעונים החלטה מסחרית.
    • הלקוח משלם עמלה באחוזים בנוסף למחיר הטעינה. מנוי חודשי/שנתי והסכם Enterprise נשמרים בגרסה נפרדת; השיעורים עדיין לא נקבעו.

    מקורות: תכנון — טרם מומש.

    שירותים וגבולות אמון#

    A07 · דפדפן הלקוח#

    מצב: foundation. אחריות: Backend.

    בקשה אינה עובדה עסקית.

    • השרת קובע משתמש, מרחב מורשה, תעריף, סכום ומצב טעינה.
    • סכמות strict דוחות שדות עודפים. פעולות כתיבה דורשות מקור בקשה תואם ו־JSON; נדרש להוסיף rate limit לפני לקוחות חיים.

    מקורות: lib/platform/validation.ts, lib/platform/api.ts.

    A08 · גישה למסד ו־service role#

    מצב: foundation. אחריות: Security.

    גישה רגילה עם JWT של המשתמש; חריגים מצומצמים בצד השרת.

    • ה־service role עוקף RLS: משמש לפעולות שרת מצומצמות לקבלת הזמנה ולסנכרון כתובות מאומתות ב־Clerk, ולשמירת פרטי רישוי רכב שאומתו מול משרד התחבורה.
    • פעולות השרת בודקות מחדש חברות פעילה וחשבון פעיל במסד. כתיבת פרטי רישוי ישירה מהדפדפן חסומה; עדכון מטא־נתונים נשאר כפוף ל־RLS.
    • מפתחות ספק, hash הזמנה ו־outbox בסכימה פרטית. אין הרשאות טבלה ל־anon/authenticated.
    • כל פעולה privileged עתידית דורשת הקשר tenant מפורש, אימות והוספה ליומן.

    מקורות: lib/platform/server.ts, lib/platform/vehicle-registration-server.ts, supabase/migrations/20261109190551_invitation_driver_lifecycle.sql, supabase/migrations/20261109191257_enforce_verified_vehicle_writes.sql.

    A09 · צוות החברה#

    מצב: blocked. אחריות: Security.

    הרשאת owner/admin של לקוח אינה הרשאת עובד בחברה.

    • הכניסה הניהולית סגורה. יש לתכנן זהות צוות, MFA והרשאות support/finance/operations.
    • גישה לתמיכה בלקוח תדרוש סיבה, זמן תפוגה וביקורת; אין התחזות שקטה או tenant wildcard.

    מקורות: components/company-site.tsx.

    A10 · אירוע מספק חיצוני#

    מצב: planned. אחריות: Integrations.

    אירוע נכנס טעון אימות ומיפוי לפני שינוי נתונים.

    • בדיקת חתימה על הגוף הגולמי, הגבלת גודל, replay window לפי חוזה הספק וסוד נפרד לכל סביבה.
    • זיהוי tenant דרך מיפוי ספק שמור בשרת; אין אמון ב־tenant_id מגוף webhook.
    • אותו event_id עם hash זהה הוא מסירה חוזרת; תוכן שונה תחת אותו מזהה מועבר לבירור.

    מקורות: תכנון — טרם מומש.

    A28 · מסחר, חיוב וספרי חברה#

    מצב: foundation. אחריות: Product, Payments & Finance.

    מנוי חודשי/שנתי + עמלת אחוזים על חשבון הלקוח + Enterprise B2B מותאם הם המודל המאושר.

    • Pricing ו־Contracts מחזיקים גרסאות מחיר וקבלת תנאים; Enterprise מוגבל למרחב עסקי מורשה.
    • Subscriptions מנהל תקופות וזכאות; Billing יוצר התחייבויות ושורות, Payments גובה ו־Invoicing מפיק מסמכים. אין להחליף מצב אחד בשני.
    • Bookkeeping רושם תנועות מאוזנות בספרי החברה; Accounting מבצע התאמה, סגירת תקופה וייצוא למערכת החשבונאית. גישה לשירותים האלה היא staff בלבד.
    • החישוב וחוזה ההסכם מיושמים ונבדקים בקוד; אין הפעלה של מנוי, סליקה, חשבוניות או ledger. מחירים, מסים וספקים טרם הוגדרו.

    מקורות: lib/commercial-system/spec.json, lib/commercial-system/pricing.ts, docs/commercial-system/architecture.md.

    A29 · זהות אישית ופרופיל מרחב#

    מצב: foundation. אחריות: Identity & Platform.

    Clerk מנהל את הפרופיל האישי וההזדהות; Supabase מנהל את זהות המרחב והלוגו לפי חברות והרשאות.

    • שם, תמונה, אימייל מאומת, סיסמה ואבטחה אישית מנוהלים דרך Clerk. Google ו־Apple תלויים בהקמת חשבונות ופרטי OAuth של העסק.
    • רק owner/admin עורכים פרטי חברה, איש קשר, כתובת ולוגו. סוג חשבון, בעלות, מטבע והרשאות אינם חלק מהעדכון.
    • קבצי לוגו ב־Storage פרטי; API מאמת חברות בכל צפייה. קבצים מתחלפים במפתח חדש ונשמרת גרסת פרופיל נגד דריסת עדכונים.

    מקורות: components/account-profile.tsx, components/platform/organization-profile.tsx, lib/platform/profile-server.ts, supabase/migrations/20261108013050_workspace_profiles.sql.

    מסעות בין שירותים#

    A11 · פתיחת מרחב לקוח#

    מצב: foundation. אחריות: Identity.

    אדם מאומת → יצירה אטומית של מרחב, בעלים ומדיניות.

    • בדיקת JWT → סכמת בקשה → ev1_create_tenant עם request_id → commit → בחירת מרחב.
    • מפתח בקשה חוזר מחזיר את אותו מרחב; אין לקוח שיכול לספק owner_user_id.
    • נדרש להשלים אימות בענן ותנאים מסחריים לפני onboarding תפעולי.

    מקורות: lib/platform/api.ts.

    A12 · התחלת טעינה#

    מצב: planned. אחריות: Charging.

    זכאות → תקציב → אישור תשלום → פקודה → אישור ספק.

    • אמת חברות, נהג, רכב, דלקן, מדיניות, מחבר ומידת עדכניות.
    • שריין תקציב בטרנזקציה נעולה והקפא גרסת תעריף/גורם משלם; צור session ו־outbox אטומית.
    • אישור תשלום חיצוני אינו בתוך טרנזקציית DB: סדר הפעולות ופיצוי בעת כשל חייבים להיקבע עם PSP.
    • timeout לאחר שליחה נשאר במצב בירור. לא משחררים מסגרת או מחבר בלי ראיה; סטטוס charging רק אחרי אישור ספק.

    מקורות: תכנון — טרם מומש.

    A13 · עצירה, חיוב והתאמה#

    מצב: planned. אחריות: Payments.

    סיום מדידה → סכום סופי → capture → מסמך → התאמה.

    • בקשת עצירה עוברת outbox; מציגים stopping עד אישור ולא הצלחה מיידית.
    • מדידה מאוחרת מעובדת לפי סדר/גרסה של הספק; אירוע ישן אינו פותח טעינה סופית.
    • capture משתמש במפתח פעולה יציב; webhook מאומת מעדכן עובדה כספית.
    • השווה session, PSP ומסמך. פער או תשלום לא ידוע נכנסים לתור בירור עם בעל אחריות.
    • בסיום מדידה מחושבים בנפרד מחיר טעינה, עמלת הלקוח והמסים לפי צילום תנאים; ההתחשבנות עם המפעיל נקבעת לפי הסכם הספק.

    מקורות: תכנון — טרם מומש.

    A14 · דוחות גדולים#

    מצב: planned. אחריות: Data.

    שאילתה מורשית → משימת יצוא → קובץ פרטי עם תפוגה.

    • שאילתות כיום מוגבלות ל־1,000 רשומות מלאי ו־500 טעינות; ההגבלה מוצגת.
    • להוסיף cursor מבוסס created_at,id ויצוא אסינכרוני עם סינון tenant לפני aggregation.
    • הרשאה נבדקת גם בתחילת העבודה וגם בהורדה. אין URL ציבורי קבוע לנתוני צי.

    מקורות: lib/platform/api.ts.

    A15 · ביטול חברות וגישה#

    מצב: foundation. אחריות: Identity.

    מצב חברות במסד נאכף בכל קריאה גם מול JWT קיים.

    • השעה membership → הבקשות הבאות נכשלות → נקה מטמון לקוח → בטל jobs פרטיים שטרם נמסרו.
    • מחיקת משתמש ב־Clerk אינה תחליף לשינוי חברות במסד ולבדיקת sessions קיימים.
    • הזמנה חד־פעמית משויכת לאימייל מאומת ופגה אחרי שבעה ימים.

    מקורות: lib/platform/server.ts, scripts/test-tenant-isolation.mjs.

    חוזי API ואירועים#

    A16 · API הלקוחות הקיים#

    מצב: foundation. אחריות: Backend.

    ממשק JSON דרך /api/platform עם context ופעולות tenant.

    • GET /api/platform/context; POST /api/platform/tenants; GET /api/platform/tenants/:id/workspace.
    • POST/PATCH לרכבים, נהגים ומרכזי עלות; PATCH למדיניות ולחברות לפי הרשאה.
    • 401: לא מחובר; 403: אין הרשאה; 404: חסר; 409: כפילות; 422: נתון לא תקין; 503: חיבור לא זמין.
    • Cache-Control private,no-store. אין fallback להדגמה בנתיב המחובר.

    מקורות: lib/platform/api.ts.

    A17 · מעטפת פקודה גרסה 1#

    מצב: foundation. אחריות: Integrations.

    חוזה מאומת בקוד; אינו endpoint פעיל או worker מחובר.

    • tenantId, sessionId, commandId ו־idempotencyKey הם UUID; סוג הפקודה start/stop.
    • הקשר השרת חייב להתאים למרחב ול־session. אותו מפתח עם payload אחר הוא conflict.
    • הסכמות והבדיקות מוכנות; כתיבה אטומית, חתימת ספק ושליחה יתווספו במתאם הספק.

    מקורות: lib/systems/contracts.ts.

    A18 · הפרדת אירועי מוצר ואירועי תפעול#

    מצב: planned. אחריות: Data.

    PostHog מודד שימוש; עובדות טעינה וכסף נשמרות במסד.

    • אירוע תפעולי נושא גרסה, מקור, מזהה יציב וזמן occurrence מול זמן received.
    • נתוני מיקום, לוחית, כתובת אימייל וטוקני סליקה אינם analytics properties או תוויות metrics.
    • אירועי PostHog מוגבלים להסכמה ולחוזה האירועים של Product System.

    מקורות: lib/product-system/event-contract.ts.

    החלטות ארכיטקטורה#

    A19 · ADR-001 · ליבה מודולרית ושירותי רקע#

    מצב: planned. אחריות: Platform.

    החלטת תכנון: ליבה אחת, workers ו־gateway בתהליכים נפרדים.

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

    מקורות: תכנון — טרם מומש.

    A20 · ADR-002 · מקור אמת להרשאות#

    מצב: foundation. אחריות: Identity.

    חברות PostgreSQL קובעת את תפקיד הלקוח.

    • Clerk Organizations יכולים לספק חוויית בחירת ארגון, אך אינם מחליפים את membership המקומי.
    • לא להעביר tenant_role ב־JWT כמקור סמכות בלעדי; השעיה חייבת להשפיע על בקשות קיימות.

    מקורות: lib/platform/server.ts.

    A21 · ADR-003 · מסירה חוזרת היא צפויה#

    מצב: planned. אחריות: Charging.

    Outbox וצרכנים idempotent; אין הבטחת exactly-once בין ספקים.

    • מפתח dedup כולל תחום ספק/חשבון/סביבה. יש לבדוק אם uniqueness(provider,event_id) הקיימת מספיקה לחוזה הספק.
    • נפילה בין שליחה לאישור דורשת בירור לפני ניסיון פעולה פיזית נוסף.

    מקורות: תכנון — טרם מומש.

    A22 · ADR-004 · החלטות פתוחות לספקים#

    מצב: blocked. אחריות: Commercial.

    רשת טעינה, PSP וספק חשבוניות טרם נבחרו.

    • החלטות נדרשות: OCPI/OCPP/API, merchant of record, מדידה, עיגול, מסים וזמני פקודה.
    • יש להגדיר מי משלם: הנהג, המעסיק או מודל אחר, ואת אחריות החזרים ומחלוקות.

    מקורות: תכנון — טרם מומש.

    תפעול והתאוששות#

    A23 · ניטור ואיתור תקלות#

    מצב: planned. אחריות: Operations.

    Grafana: זמינות API, זמני פקודה, גיל תור וחריגות התאמה.

    • correlation ID מקשר API, outbox, worker וספק; אין לוג של גוף webhook או סוד.
    • התראות על טעינה בלי מדידות, פקודה לא ידועה, DLQ ותשלומים ללא התאמה.
    • יעדי SLO וספי התראה טעונים אישור לפי פיילוט; אינם SLA מסחרי.

    מקורות: תכנון — טרם מומש.

    A24 · שחזור ותקרית#

    מצב: planned. אחריות: Operations.

    גיבוי נבחן רק אחרי תרגיל שחזור.

    • להגדיר RPO/RTO מאושרים, זמינות PITR בתוכנית Supabase ומיקום הגיבוי.
    • בשיבוש ספק: חסום התחלות חדשות, המשך קליטת מדידות, שמור מזהי פקודות והפעל reconciliation.
    • בשחזור DB: אמת tenant isolation, יתרות ו־outbox לפני פתיחת כתיבות. replay אינו רשאי לחייב פעמיים.

    מקורות: תכנון — טרם מומש.

    A25 · סודות והגנות API#

    מצב: planned. אחריות: Security.

    Bitwarden כמקור מנוהל; מפתחות נפרדים לפי סביבה.

    • סבב החלפת סודות כולל תקופת חפיפה ואימות rollback; service role לעולם אינו NEXT_PUBLIC.
    • Rate limit לפי משתמש/tenant/פעולה, הגבלת payload ו־timeouts; Origin לבד אינו הגנת abuse.
    • סודות ומידע אישי אינם מועתקים לספריות המערכת או ל־CI artifacts.

    מקורות: תכנון — טרם מומש.

    סביבות ותוכנית מסירה#

    A26 · סביבות וקידום גרסאות#

    מצב: foundation. אחריות: Platform.

    Development → Staging → Production עם נתונים ומפתחות נפרדים.

    • קיימת תצוגת production שמציגה הדגמה; אין לייחס לה readiness תפעולי.
    • סביבות זהות ומסד בדיקה נפרדות עדיין דורשות הקמה. CI בודק types/lint/unit/build; נדרש לחבר repository ו־release gates.
    • שחרור סכימה בתבנית expand/migrate/contract; feature flag חדש מופעל רק אחרי בדיקות ויכולת rollback.

    מקורות: .github/workflows/ci.yml.

    A27 · תוכנית פיילוט וקבלת פרודקשן#

    מצב: planned. אחריות: Product & Engineering.

    התקדמות לפי ראיות, לא לפי מספר המסכים.

    • שלב 1: סכימה, זהות ומשתמשים בשני tenants; ביטול חברות ו־JWT ישן.
    • שלב 2: ספק sandbox, פקודות כפולות, ניתוק, מדידה מאוחרת ושריון תקציב במקביל.
    • שלב 3: PSP sandbox, capture/refund והתאמה למסמכים; חיוב אחד לכל פעולה.
    • שלב 4: טעינה אמיתית בפיילוט מצומצם, תרגיל שחזור ותמיכה מאוישת. תנאי השחרור G01–G08 נשארים חסומים עד ראיות.

    מקורות: lib/product-system/spec.json.