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

> תיעוד מקור. מקור: docs/architecture-system/handbook.md · 6a466bf.

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

תאריך: 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.
