דלג לתוכן הראשי

מפרטי שדות עבור נכסים וכרטיסים

מסמך זה מפרט את דרישות שדות הסכמה עבור נכסים (Assets), כרטיסי שבר (Breakdown Tickets), כרטיסים מתוכננים (Planned Tickets), ותבניות תחזוקה מתוכננת (Planned Maintenance Templates).

1. שדות נכס (Asset)​

נכסים מייצגים מכונות, ציוד או רכיבים במערכת.

שדות חובה (קלט נדרש בבקשה)​

  • name (מחרוזת): שם/תווית הנכס (מינימום תו אחד).

שדות שאינם חובה​

שדות קלט אופציונליים (ניתנים לעריכה על ידי המשתמש)​

  • type (מחרוזת | אובייקט): קטגוריית סוג הנכס. יכול להיות מזהה (slug) כמחרוזת או אובייקט המכיל מאפיין slug.
  • description (מחרוזת): תיאור מפורט של הנכס.
  • image (מחרוזת/URI): קישור תמונה של הנכס.
  • visualId (או visual_id) (מחרוזת): מזהה חזותי אופציונלי לחיפוש ותצוגה (לדוגמה 'LN3-PMP-004').
  • barcode (מחרוזת): מזהה ברקוד לסריקה.
  • qrCode (מחרוזת): מזהה קוד QR לסריקה.
  • media (או mediaFiles) (מערך אובייקטים): רשימת פריטי מדיה/תמונות המשויכים לנכס.
  • attachments (או attachmentFiles) (מערך אובייקטים): רשימת קבצי תיעוד ונספחים המשויכים לנכס.
  • customFields (אובייקט): זוגות מפתח-ערך עבור שדות מותאמים אישית שהוגדרו על ידי הלקוח (Tenant).

שדות מערכת והקשר (מחושבים אוטומטית)​

  • id (מחרוזת): מזהה מסמך ייחודי.
  • accountId (או account_id) (מחרוזת): מזהה החשבון/חברה.
  • siteId (או site_id) (מחרוזת): מזהה האתר/מפעל.
  • nodeId (או node_id / structureNodeId) (מחרוזת): מזהה הצומת בעץ המבנה הארגוני.
  • created (או createdAt) (מחרוזת / חותמת זמן ISO): זמן יצירה.
  • updated (או updatedAt) (מחרוזת / חותמת זמן ISO): זמן עדכון אחרון.

2. שדות כרטיס שבר (Breakdown Ticket)​

כרטיסי שבר עוקבים אחר אירועי תחזוקה לא מתוכננים או מקרי חירום בנכסים.

שדות חובה (קלט נדרש בבקשה)​

  • type (מחרוזת): חייב להיות בדיוק 'BREAKDOWN'.
  • status (מחרוזת): הסטטוס הנוכחי של הכרטיס ('OPEN', 'IN_PROGRESS', 'COMPLETED', 'CLOSED', 'SKIPPED').
    • הערה: אם הסטטוס נקבע כ-'COMPLETED', השדה breakdown.root_cause הופך לשדה חובה.

שדות שאינם חובה​

שדות קלט אופציונליים (ניתנים לעריכה על ידי המשתמש)​

  • title (מחרוזת): כותרת הכרטיס (אופציונלי עבור כרטיסי שבר).
  • description (מחרוזת): תיאור השבר/תקלה.
  • priority (מספר שלם): עדיפות מספרית (1 עד 5).
  • asset_id (מחרוזת): מזהה הנכס המשויך לשבר (מומלץ מאוד, על אף שמוגדר אופציונלית בסכמת הבסיס).
  • site_id (מחרוזת): מזהה האתר שבו אירע השבר.
  • operator_notes (מחרוזת): הערות שנמסרו על ידי המפעילים בזמן האירוע.
  • timeline (אובייקט):
    • started (מחרוזת / ISO DateTime) - זמן התחלה
    • ended (מחרוזת / ISO DateTime) - זמן סיום
    • duration_min (מספר) - משך זמן בדקות
    • manual_downtime_min (מספר) - זמן השבתה ידני בדקות
    • is_downtime (בולאני) - האם גרם להשבתה
    • downtime_start (מחרוזת / ISO DateTime) - תחילת זמן השבתה
    • labor_entries (מערך אובייקטים המכילים user_id, started, ended, duration_min) - רישומי שעות עבודה
  • breakdown (אובייקט):
    • root_cause (מחרוזת): סיבת שורש (חובה בסטטוס COMPLETED)
    • solution_description (מחרוזת): תיאור הפתרון
    • start_time (מחרוזת / ISO DateTime): זמן התחלת השבר
  • tasks (מערך אובייקטים): משימות ספציפיות הנדרשות לפתרון הכרטיס. כל משימה כוללת:
    • description (מחרוזת): תיאור המשימה
    • status (מחרוזת: 'PENDING', 'DONE', 'SKIPPED', 'FAILED')
    • photos (מערך אובייקטים המכילים url, name, status)
  • notes (מערך אובייקטים): הערות/הערות ביקורת פנימיות. מכיל at (תאריך ושעה), by (מזהה משתמש), ו-note (מחרוזת).
  • owner_user_id (מחרוזת): מזהה משתמש הבעלים/מפקח.
  • reported_by_user_id (מחרוזת): מזהה המפעיל/משתמש המדווח.
  • assignees (מערך אובייקטים): רשימת טכנאים שהוקצו למשימה. מכיל אובייקטים עם user_id.
  • photos (מערך אובייקטים): תמונות לאימות. מכיל { url, caption }.
  • attachments (מערך אובייקטים): מסמכי דיאגנוסטיקה. מכיל { doc_id, title, kind }.
  • files (מערך אובייקטים): קבצים כלליים המשויכים לכרטיס. מכיל { name, url }.
  • estimatedDurationMin (מספר): זמן תיקון מוערך בדקות.
  • customFields (אובייקט): זוגות מפתח-ערך עבור שדות מותאמים אישית.

שדות מערכת והקשר (מחושבים אוטומטית)​

  • id (מחרוזת): מזהה מסמך ייחודי.
  • accountId (או account_id) (מחרוזת): מזהה החשבון/חברה.
  • created_at (מחרוזת / חותמת זמן ISO): זמן יצירה.
  • updated_at (מחרוזת / חותמת זמן ISO): זמן עדכון אחרון.

3. שדות כרטיס מתוכנן (Planned Ticket)​

כרטיסים מתוכננים מייצגים מופעים פעילים של משימות תחזוקה מתוזמנות מראש.

שדות חובה (קלט נדרש בבקשה)​

  • type (מחרוזת): חייב להיות בדיוק 'PLANNED'.
  • title (מחרוזת): כותרת כרטיס התחזוקה המתוכננת.
  • scheduled_date (מחרוזת): התאריך המתוכנן לביצוע התחזוקה.
  • status (מחרוזת): הסטטוס הנוכחי של הכרטיס ('PLANNED', 'OPEN', 'IN_PROGRESS', 'COMPLETED', 'CLOSED', 'SKIPPED').

שדות שאינם חובה​

שדות קלט אופציונליים (ניתנים לעריכה על ידי המשתמש)​

  • description (מחרוזת): תיאור נהלים או פרטים ספציפיים.
  • priority (מספר שלם): עדיפות מספרית (1 עד 5).
  • asset_id (מחרוזת): מזהה הנכס שעובר תחזוקה.
  • site_id (מחרוזת): מזהה האתר שבו ממוקם הנכס.
  • operator_notes (מחרוזת): הערות שנמסרו על ידי המפעילים/טכנאים.
  • timeline (אובייקט):
    • started (מחרוזת / ISO DateTime)
    • ended (מחרוזת / ISO DateTime)
    • duration_min (מספר)
    • manual_downtime_min (מספר)
    • is_downtime (בולאני)
    • downtime_start (מחרוזת / ISO DateTime)
    • labor_entries (מערך אובייקטים המכילים user_id, started, ended, duration_min)
  • tasks (מערך אובייקטים): רשימת משימות לבדיקה (Checklist). כל משימה כוללת:
    • description (מחרוזת)
    • status (מחרוזת: 'PENDING', 'DONE', 'SKIPPED', 'FAILED')
    • photos (מערך אובייקטים המכילים url, name, status)
  • notes (מערך אובייקטים): הערות ביקורת. מכיל at (זמן), by (מזהה משתמש), ו-note (מחרוזת).
  • owner_user_id (מחרוזת): מזהה משתמש הבעלים/מפקח.
  • reported_by_user_id (מחרוזת): מזהה משתמש המפקח/מתזמן.
  • assignees (מערך אובייקטים): רשימת טכנאים שהוקצו. מכיל אובייקטים עם user_id.
  • photos (מערך אובייקטים): תמונות לאימות עבודה שהושלמה. מכיל { url, caption }.
  • attachments (מערך אובייקטים): קישורים לדוחות/רשימות שהושלמו. מכיל { doc_id, title, kind }.
  • files (מערך אובייקטים): קבצים כלליים. מכיל { name, url }.
  • plannedMaintenanceTemplateId (מחרוזת): מזהה תבנית התחזוקה המתוכננת שממנה נוצר הכרטיס.
  • estimatedDurationMin (מספר): זמן ביצוע יעד בדקות.
  • customFields (אובייקט): זוגות מפתח-ערך עבור שדות מותאמים אישית.

שדות מערכת והקשר (מחושבים אוטומטית)​

  • id (מחרוזת): מזהה מסמך ייחודי.
  • accountId (או account_id) (מחרוזת): מזהה החשבון/חברה.
  • created_at (מחרוזת / חותמת זמן ISO): זמן יצירה.
  • updated_at (מחרוזת / חותמת זמן ISO): זמן עדכון אחרון.

4. שדות תבנית תחזוקה מתוכננת (Planned Maintenance Template)​

תבניות תחזוקה מתוכננת מגדירות לוחות זמנים מחזוריים ותבניות משימות (Checklists) ליצירת כרטיסים מתוכננים.

שדות חובה (קלט נדרש בבקשה)​

  • title (מחרוזת): כותרת/שם שגרת התחזוקה המונעת.
  • assetIds (מערך מחרוזות): רשימת מזהי הנכסים המכוסים בשגרה זו.
  • generateTicketPerAsset (בולאני): האם להפיק כרטיס נפרד לכל נכס (true) או כרטיס בודד המאגד את כל הנכסים (false).
  • recurrence (מערך אובייקטים של חזרתיות): הגדרת תדירות החזרה של המשימה. כל אובייקט חזרתיות דורש:
    • frequency (מחרוזת): חייב להיות 'WEEKLY'.
    • dayOfWeek (מערך מספרים שלמים): אינדקס ימי השבוע (0 = ראשון, 1 = שני, ..., 6 = שבת).
    • interval (מספר שלם): תדירות המרווח בשבועות (למשל 1 לכל שבוע, 2 לכל שבועיים).
    • time (מחרוזת): שעת הפעלה בפורמט 24 שעות (HH:mm, למשל '08:00').
  • ticketTemplate (אובייקט): תבנית עבור מופעי הכרטיסים שיווצרו. דורש:
    • title (מחרוזת): כותרת הכרטיסים שיווצרו.
    • tasks (מערך אובייקטים): משימות לביצוע. כל משימה דורשת:
      • description (מחרוזת): תיאור המשימה.
    • ownerUserId (מחרוזת): מזהה משתמש ברירת המחדל של הבעלים.
    • שדות תבנית אופציונליים: priority (מספר שלם, 1-5), estimatedDurationMin (מספר שלם), assignees (מערך אובייקטים המכילים user_id).
  • isActive (בולאני): האם תבנית החזרתיות פעילה ומתוזמנת ליצירת כרטיסים.

שדות שאינם חובה​

שדות קלט אופציונליים (ניתנים לעריכה על ידי המשתמש)​

  • executionWindowDays (מספר שלם): משך זמן מותאם אישית בימים להשלמת המשימה לפני שתהפוך לפיגור (Overdue).
  • firstInstanceDate (מחרוזת / ISO DateTime): תאריך התחלה ראשוני לתזמון מופעים עתידיים או מילוי רטרואקטיבי.
  • isDemo (בולאני): סימון התבנית כתוכן הדגמה/הדרכה.

שדות מערכת והקשר (מחושבים אוטומטית)​

  • id (מחרוזת): מזהה תבנית ייחודי.
  • accountId (מחרוזת): מזהה החשבון המשויך (נגזר מפרמטר הנתיב).
  • siteId (מחרוזת): מזהה האתר המשויך (נגזר מפרמטר הנתיב).
  • createdAt (מחרוזת / חותמת זמן ISO): זמן יצירה.
  • createdByUserId (מחרוזת): מזהה המשתמש היוצר.