מודל נתונים מלא: ישויות JSON, קשרים ואונטולוגיה

דף זה מתאר את מודל הנתונים המלא של חשבון Omniscol: הישויות, השדות העיקריים שלהן והקשרים ביניהן. הוא ממשיך את הדף המושגי ארגון הנתונים, שמסביר את המדוע (מאגר הנתונים של בית הספר ↔ מערכת השעות, עותקים מקומיים); כאן המטרה היא המה — מפה מבנית שאפשר לעבוד איתה, בעיקר כדי לקשר את המודל למאגר נתונים חיצוני (מערכת ניהול, ספריית משתמשים, מערכת מידע).

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

כל נתוני המוסד מאורגנים כעץ. הישויות המתוארות להלן (משתמשים, שנות לימודים, מערכות שעות, היעדרויות, אירועים וכו׳) מתאימות לענפים השונים של מבנה זה. ההפניה המחייבת היא סכמת ה-JSON של החשבון. אפשר לעיין בה בשתי צורות:

  • המקור הגולמי (סכמת ה-JSON כפי שהיא), שהחשבון מגיש בכתובת https://api.omniscol.com/api/guest/school_schema.json;
  • מציג העץ הקריא בכתובת omniscol.com/fr/datamodel (ואת מסמך העיון של ה-API בכתובת omniscol.com/fr/developers).

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

מסמך בית הספר: השורש

מסמך השורש מרכז את המאגר הקבוע של המוסד ואת כל התכנונים שלו. תתי-העצים ברמה הראשונה:

מפתח שורש ישות תפקיד
config SchoolConfig הגדרות החשבון (מדינה, אפשרויות, אזור זמן, סנכרון חיצוני)
subjects_custom מילון של SubjectFull מקצועות מותאמים אישית של בית הספר
families_custom מילון של Family משפחות מקצועות מותאמות אישית
users מילון של User ספריית המשתמשים (כל התפקידים)
school_years מערך של SchoolYear שנות לימודים וחופשות
timetables מילון של Timetable מערכות שעות
absences אוסף של Absence* היעדרויות (מורים, כיתות, צוות, תלמידים)
staffing Staffing מודול אנשי הצוות והפיקוח
panels מילון של Panel לוחות תצוגה
events מילון של Event אירועים מסוג יומן
api, snapshots, jobs, translations, logo שונות הגדרות טכניות והיסטוריה

תתי-העצים המתוארים כ"מילון" הם אובייקטי JSON שמפתחותיהם הם מזהים יציבים (הציר של כל קישור חיצוני — ראו את הסעיף האחרון).

config

subjects_custom

families_custom

users

school_years

timetables

staffing

absences

panels

events

SCHOOL

string

_id

דומיין המוסד

string

name

שם החשבון

string

country

מדינת החשבון

string

current_school_year

שנת הלימודים הנוכחית

CONFIG

SUBJECT

FAMILY

USER

SCHOOL_YEAR

TIMETABLE

STAFFING

ABSENCE

PANEL

EVENT

שדות רוחביים: _extids ו-wishes

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

  • _extids (ExternalIds) — טבלת המזהים של הישות במערכות חיצוניות, לדוגמה { "auriga": "12345" }. קיים בישויות הניתנות לסנכרון (מקצועות, משפחות, משתמשים, אתרים, כיתות לימוד, משאבים, מורים, כיתות, קבוצות…). זהו עוגן ההתאמה למאגר חיצוני (ראו את הסעיף האחרון).
  • wishes — אילוצי זמן: זמינות, משבצות רצויות או כאלה שיש להימנע מהן, מכסת שעות מרבית, כיתת לימוד מועדפת… קיים ברוב הישויות הניתנות לתכנון: משתמשים, מורי מערכת שעות, קורסים (מקצועות הכיתה), קבוצות, כיתות, כיתות לימוד, טווחי זמן של אתר, רשתות פיקוח. בהתאם להיקף, אילוצים אלה הם כלליים (ברמת בית הספר) או ייחודיים למערכת שעות.

רמה 1 — מאגר בית הספר

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

family

parent

שיבוצים לפי שנה

groups

holidays

FAMILY

string

name

string

code

SUBJECT

string

name

string

short

תווית קצרה (תצוגה)

string

code

string

parent

מקצוע אב

string

family

משפחה

string

color

object

_extids

מזהים חיצוניים

USER

string

login

string

first_name

string

middle_name

(אם רלוונטי למדינה)

string

last_name

string

idnumber

מזהה רשמי

array

roles

admin teacher staff student

string

customrole

תפקיד מותאם אישית

int

servicehours

היקף הוראה בסיסי

bool

external

מורה חיצוני

object

subjects

מקצועות הוראה

object

wishes

זמינות כללית

object

_extids

PLACEMENT

string

class

כיתה משובצת

string

date_start

string

date_end

array

groups

קבוצות משובצות

PLACEMENT_GROUP

string

group

קבוצת קבוצות או קבוצה וירטואלית

array

weeks

טווחי שבועות

SCHOOL_YEAR

string

name

string

date_start

string

date_end

array

altweeks

שבועות מתחלפים

HOLIDAY

string

name

string

begin

string

end

מקצועות — SubjectFull / Subject / Family

מקצוע מותאם אישית (SubjectFull) מרחיב את מקצוע הבסיס (Subject: name, short, code, type, _extids) בשדות parent, family ו-color. ברמת בית הספר יש שני מקורות: המקצועות המשותפים למדינה (לקריאה בלבד) והמקצועות המותאמים אישית של המוסד. פירוט תפעולי: ניהול מקצועות.

משתמשים — User (כולל מורים)

User הוא הישות היחידה בספרייה: זהות (שם משפחה, שם פרטי, idnumber, פרטי קשר), אימות (login), roles, היקף ההוראה הבסיסי (servicehours), הזמינות הכללית (השדה wishes) ו-placements. מורה אינו ישות נפרדת: זהו User שיש לו teacher בין ה-roles שלו (אותו משתמש יכול לצבור כמה תפקידים). השדה placements (מסודר לפי שנת לימודים) משייך תלמיד ל-class ול-groups לתקופה מסוימת. פירוט: ניהול מורים.

שנות לימודים — SchoolYear / Holiday

SchoolYear מגדירה date_start → date_end, את רשימת ה-holidays ואת ה-altweeks (שבועות מתחלפים). זוהי מסגרת זמן, לא מכל: מערכות השעות נפרשות בתוכה מבלי להיות מקוננות בה. ראו שנת לימודים.

רמה 2 — מערכת השעות

Timetable היא יחידת תכנון קוהרנטית. היא נושאת עותק מקומי משלה של המורים, הכיתות, הקבוצות והמקצועות — ראו את עיקרון העותק המקומי בדף ארגון הנתונים.

config

sites

teachers

classes

lessons (קבוצות של קבוצות, רב-קבוצתיים)

classrooms

resources

subjects

groups

lessons

parent (היררכיה)

מקור (עותק מקומי חלקי)

teachers ברירת מחדל

עותק מקומי חלקי וקישור משתמע לפי מזהה

קבוצות מרכיבות

TIMETABLE

bool

active

פורסמה?

array

lessons

שיעורים רוחביים

TIMETABLE_CONFIG

string

type

week cycle calendar

int

time_period

משך משבצת הזמן

int

time_unit

חלוקת משבצת הזמן

array

weekdays

ימי עבודה

string

displaymode

hours periods agenda

int

cycle

אורך המחזור

array

dates

גבולות אם calendar

object

date_windows

חלונות היצירה האוטומטית

TIMETABLE_SITE

string

name

object

distances

מרחקים בין אתרים

object

hours

רשתות שעות

TIMETABLE_TEACHER

string

first_name

string

last_name

string

virtual_name

משרה פנויה

array

subjects

מקצועות של המשרה הווירטואלית

string

idnumber

int

servicehours

ניתן לדריסה לפי מערכת שעות

string

classroom

כיתת לימוד מועדפת

TIMETABLE_CLASS

string

name

string

level

string

campus

array

sites

אתר אחד בלבד נלקח בחשבון

int

studentsnb

מספר תלמידים תאורטי (לחישוב כיתת לימוד מתאימה)

string

classroom

כיתת לימוד ברירת מחדל

bool

offgrid

מחוץ לגריד (calendar)

string

videolink

קישור ברירת מחדל לשיחת וידאו בכל השיעורים

string

resourcelink

קישור ברירת מחדל לחומרי לימוד (LMS) בכל השיעורים

LESSON

TIMETABLE_CLASSROOM

string

name

int

capacity

string

specialisation

התמחות חופשית

int

maxclasses

כיתות בו-זמניות

string

building

string

description

תיאור חופשי

array

tags

תוויות של מאפיינים או ציוד

TIMETABLE_RESOURCE

string

name

int

number

כמות זמינה

TIMETABLE_CLASS_SUBJECT

string

code

בירושה מ-Subject

array

incompatibilities

אי-התאמות

number

pweight

משקל פדגוגי

array

teachers

מורי ברירת מחדל

number

minutes

היקף שעות מבוקש

string

specialisation

כיתת לימוד נדרשת

TIMETABLE_CLASS_GROUP

string

name

string

code

bool

free

קבוצה חופשית

string

parent

קבוצת אב

int

studentsnb

מספר תלמידים תאורטי (לחישוב כיתת לימוד מתאימה)

SUBJECT

USER

GROUPSET_ITEM

string

name

string

code

array

groups

מזהי קבוצות

הגדרות — TimetableConfig

השדה המכריע הוא type: week (שבועית חוזרת), cycle (מחזור של כמה ימים, ראו cycle) או calendar (תאריכים אמיתיים, ראו dates). time_period ו-time_unit מגדירים את מסגרת הרשת; weekdays את ימי העבודה; date_windows את חלונות האילוצים ליצירה האוטומטית.

אתרים, כיתות לימוד, משאבים

TimetableSite (אתר) מכיל את ה-classrooms שלו (TimetableClassroom: capacity, specialisation, maxclasses, building) ואת ה-resources שלו (TimetableResource: number = הכמות הזמינה, שהמערכת מבטיחה שלא תוזמן ביתר). distances מייצג את זמני הנסיעה בין אתרים. ראו קמפוס, אתרים, כיתות לימוד, משאבים, ריבוי כיתות לימוד ואת התמחויות של כיתות לימוד.

מורי מערכת השעות — TimetableTeacher

עותק חלקי ומועשר של User: רק מעט שדות מזהים מועתקים (first_name, last_name, idnumber), ואליהם מתווספים שדות ייחודיים לתכנון (servicehours הניתן לדריסה, classroom מועדפת, wishes לפי מערכת שעות). virtual_name שאינו ריק מציין מורה וירטואלי (משרה פנויה, ללא User אמיתי מאחוריה).

כיתות, מקצועות הכיתה, קבוצות

  • TimetableClass: name, level, campus/sites, studentsnb, ושלושה תתי-עצים מרכזיים — subjects, groups, lessons.
  • TimetableClassSubject: עותק מקומי של מקצוע (מרחיב את Subject) המועשר לצורכי תכנון — minutes (ההיקף המבוקש), pweight (משקל פדגוגי), incompatibilities, teachers ברירת מחדל, specialisation של כיתת לימוד. שיוך מקצוע עם סוג שיעור יוצר רשומה נפרדת לכל סוג. ראו קורסים, שיעורים, סוגי שיעור.
  • TimetableClassGroup: תת-קבוצה של כיתה. free=true מבטל את ההתנגשויות עם שאר הכיתה (קבוצות חופשיות); parent קובע את היררכיית קבוצות.

כללים בין קבוצות — חלוקות, יישורים, קבוצות של קבוצות

הקשרים בין קבוצות נשמרים בתת-העץ groups של מערכת השעות, בשלוש צורות:

סכמה ישות משמעות דף
TimetableGroupTimeset חלוקה קבוצות של אותה כיתה השוללות זו את זו, המשובצות במקביל (חצאי כיתה, מקצועות בחירה) חלוקות כיתה
TimetableGroupSpaceset יישור קבוצות של כיתות שונות הלומדות יחד במשבצות מקבילות יישורי קבוצות
TimetableGroupGroupset קבוצת קבוצות קבוצת-על (GroupsetItem: name, code, groups[]) המאגדת כמה קבוצות קבוצות של קבוצות

ראו גם את הסקירה הכללית כיתה, קבוצה, תת-קבוצה.

רמה 3 — שיעורי הקורסים

שיעור (Lesson) הוא יחידת ההוראה שמשובצת בפועל במערכת השעות: משך, מקצוע, קבוצה, מורים, כיתת לימוד, משאבים, מיקום וסטטוס. הוא נוצר ממקצוע כיתה (ראו רמה 2) ומשויך לכיתה (class.lessons) או ישירות למערכת השעות (timetable.lessons) — המקרה האחרון מיועד לקבוצות של קבוצות ולשיעורים רב-קבוצתיים, הרוחביים לכמה כיתות.

lessons (שיעורי כיתה)

lessons (קבוצות של קבוצות, רב-קבוצתיים)

assoc · concat · weekalt (שיעורים מורכבים)

group

teachers

classroom

resources

memos

position

TIMETABLE_CLASS

LESSON

int

duration

במספר משבצות

int

duration_actual

דקות בפועל

int

duration_accounted

דקות לחיוב

string

modality

in_person remote hybrid self_study

string

subject

מזהה מקצוע

string

group

מזהה קבוצה

array

teachers

null מכריח היעדר מורה

string

classroom

null מכריח היעדר כיתת לימוד

string

status

planned draft canceled done

string

_id

זהות יציבה של השיעור

string

_osrev

גרסה (נעילה אופטימית)

TIMETABLE

TIMETABLE_CLASS_GROUP

TIMETABLE_TEACHER

TIMETABLE_CLASSROOM

TIMETABLE_RESOURCE

MEMO

string

comment

string

pub

נראות ההערה

string

owner

int

tstp

חותמת זמן

POSITION

string

day

תאריך, יום בשבוע או מספר יום במחזור

int

period

אינדקס המשבצת ברשת

string

start

שעת התחלה מדויקת HH:MM (למחוץ לגריד בלבד)

string

end

שעת סיום מדויקת HH:MM (למחוץ לגריד בלבד)

bool

fixed

שיעור מוצמד (קבוע בעת היצירה האוטומטית)

ליבת השיעור

שיעור נושא את שדות התכנון — duration (במשבצות), duration_actual / duration_accounted (דקות בפועל / לחיוב), modality, subject, group, teachers, classroom, resources — ואליהם מתווספים ה-position שלו, ה-status, ה-memos וזהות (_id, _osrev). הצבת teachers או classroom על null מכריחה במפורש היעדר מורה או כיתת לימוד.

שיעורים מורכבים

שיעור יכול לכלול שיעורים אחרים:

  • assoc — שיעורים משויכים: הקבוצות מתחלפות יחד.
  • concat — שיעורים רצופים: רצופים בהחלט.
  • weekalt — שבועות מתחלפים: גרסה אחת של השיעור לכל שבוע.

מנגנונים אלה מכסים את השיעורים המורכבים — ראו שיעורים מורכבים: מתחלפים, רצופים, משויכים, בהוראה משותפת.

מיקום השיעור

ה-position הוא אובייקט המציב את השיעור בזמן. הוא כולל את השדות הבאים:

  • position.day — יום השיעור, פולימורפי בהתאם למצב של מערכת השעות: שם יום (monday…sunday) במצב שבועי, מספר יום במחזור ("1", "2"…) במצב מחזורי, או תאריך YYYY-MM-DD במצב לוח שנה. זהו שדה אחד ויחיד שמשנה צורה לפי המצב; הוא תמיד קיים.
  • position.period — אינדקס המשבצת ברשת השעות. שיעור ללא period וללא start/end מתאים ליום חג.
  • position.start / position.end — שעות התחלה וסיום מדויקות (HH:MM), לשיעורים מחוץ לגריד או במצב לוח שנה שאינם מתיישרים עם משבצת רגילה.
  • position.fixed — ערך בוליאני (ברירת מחדל: שקר): שיעור מוצמד, שהיצירה האוטומטית לא תזיז.

שיעורי הכיתה נמצאים ב-class.lessons; המערך timetable.lessons נושא את השיעורים הרוחביים הקשורים לקבוצות של קבוצות.

זהות השיעור

כל שיעור נושא שני שדות זהות טכניים, הקיימים בחשבונות Premium:

  • _id — מזהה יציב, שניתן ביצירת השיעור ואינו משתנה אחר כך (הוא משלב חותמת זמן וטביעת אצבע של התוכן). זהו המפתח של שיעור לעריכה שיתופית ולכלי חיצוני שעוקב אחר השיעורים לאורך זמן. עבור המופעים החוזרים של מערכת שעות מסוג לוח שנה (שבועות מתחלפים, שיעורים רצופים, שיעורים משויכים), ה-_id של כל מופע נגזר מזה של שיעור הבסיס, שנשאר ניתן לזיהוי.
  • _osrev — טוקן גרסה (נעילה אופטימית), שגדל בכל שינוי (חותמת זמן + מספר שינוי), בסדר אלפביתי קפדני (כך שקל לדעת אם גרסה חדשה מגרסה אחרת). הוא מאפשר לעריכה השיתופית לזהות ולמזג שינויים מקבילים: גרסת לקוח מיושנת מסמנת התנגשות, שהשרת מכריע או ממזג במקום לדרוס בשקט.

היעדרויות

ההיעדרויות חולקות בסיס משותף (Absence: date_start, date_end, reason, hours, comment, סטטוס) המתפצל לפי סוג הנעדר.

teachers

classes

staff

students

substitutes

ABSENCE

ABSENCE_TEACHER

string

date_start

string

date_end

string

reason

מפתח תרגום או תווית

array

subjects

מקצועות מושפעים

array

classes

כיתות מושפעות

string

status

ABSENCE_CLASS

ABSENCE_STAFF

ABSENCE_STUDENT

string

date_start

string

reason

array

subjects

מקצועות מוחרגים

string

status

SUBSTITUTE

string

substitute

שם המחליף

string

date_start

תחילת הכלל (תאריך)

string

date_end

סוף הכלל (תאריך)

array

hours

משבצות מושפעות (begin/end בדקות, day)

array

classes

כיתות מושפעות

array

subjects

מקצועות מושפעים

string

comment

הערה

אפשר להגביל AbsenceTeacher ל-subjects/classes מסוימים, והיא נושאת מערך של כללי החלפה (substitutes, כל אחד AbsenceTeacherSubstitute: מחליף, תקופה, משבצות זמן, כיתות ומקצועות מכוסים). הסטטוסים שונים לפי סוג הנעדר (לדוגמה ok/aborted עבור כיתה). ראו את המילון החלפה / מילוי מקום ואת המודול ניהול היעדרויות.

אנשי הצוות

מודול נפרד (הנמכר גם כמוצר עצמאי) לפיקוח ולשירותי השגחה.

grids

assignments

staff

schedule

needs

STAFFING

STAFFING_GRID

array

dates

טווחי פעילות

array

days

array

periods

משבצות

STAFFING_ASSIGNMENT

string

name

int

req

מינימום משגיחים

int

ideal

מספר רצוי

string

site

string

priority

high normal low

array

allowed_staff

STAFFING_STAFF_MEMBER

string

first_name

string

last_name

string

virtual_name

משרה פנויה

string

color

STAFFING_SCHEDULE

object

dates

משמרות לפי תאריך

STAFFING_NEED_SPAN

string

day

יום או תאריך

string

begin

HH:MM

string

end

HH:MM

int

headcount

מספר נדרש

StaffingGrid היא התבנית (ימים, משבצות); ה-assignments מתארים את העמדות (req/ideal, priority, needs מפורטים לפי משבצת באמצעות StaffingNeedSpan); ה-schedule מממש את המשמרות בפועל לפי תאריך. ראו את המודול ניהול צוות.

אירועים

Event הוא רשומת יומן המונחת מעל הרשת: משהו שקורה במוסד ואינו שיעור רגיל — ישיבת מורים, אסיפת הורים, בחינה ליום שלם, טיול, יום פתוח. האירועים נשמרים במילון events (מפתחות event-<n>) והם חלק מהיכולות של Premium.

שדות של Event (חובה: title, start, end):

  • title — הכותרת המוצגת.
  • start / end — התחלה וסיום, בפורמט YYYYMMDDTHHmmSS.
  • rrule — כלל חזרתיות אפשרי.
  • attendees — משתתפים: משתמש, כיתה, קבוצה, תווית חופשית (custom), או כל המוסד (everybody) / כל מי שמתנדב (anyone).
  • location — מקום או מקומות: כיתת לימוד של מערכת השעות או תווית חופשית.
  • resources — משאבים שהוזמנו לאירוע.
  • videolink — קישור לשיחת וידאו להשתתפות מרחוק.
  • memos — הערות; color — צבע (הקסדצימלי).

אופן השימוש (יצירה, הצבה ברשת, שדות הממשק) מתואר בדף אירועים חד-פעמיים.

לוחות תצוגה

Panel הוא לוח תצוגה של שיעורי היום (לובי, כיתת לימוד, מסך קבלה…). הוא מגדיר את בחירת ה-columns, את ה-topline, את ה-filters/exclusions ואת הגדרות המראה. ראו את המילון לוח תצוגה.

מזהים, עותקים מקומיים וקישור ל-ERP

כדי לקשר את מודל Omniscol למאגר חיצוני, שלושה עקרונות מכריעים:

  1. מפתחות המילון הם המזהים היציבים. מקצועות, משתמשים, מורים, כיתות, קבוצות, כיתות לימוד, משאבים מסודרים לפי מזהה בלתי משתנה (מפתח ה-JSON), ולא לפי התווית שלהם. זהו הציר הזה — לעולם לא ה-name — שיש להשתמש בו לכל התאמה.

  2. השדה _extids (ExternalIds) נושא את המזהים החיצוניים. הוא קיים בישויות הניתנות לסנכרון (Subject, Family, TimetableSite, TimetableClassroom, TimetableResource, TimetableTeacher, TimetableClass, TimetableClassGroup, User…), ומשייך לכל ישות את מזהיה במערכות צד שלישי, לדוגמה { "auriga": "12345", "aimaira": "67890" }. זהו עוגן ההתאמה הקנוני להתאמה דו-כיוונית.

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

הגדרות הסנכרון נמצאות ב-config.extsync (SchoolConfigExtsync): systems (מחברים שהוגדרו), sync (כיוון וישויות), export ו-schedules, וכן טבלאות התאמה (mappings) לפי מפתח ומזהה של Omniscol. בכל הנוגע לגישה תוכנתית, ממשק ה-REST API והטוקנים מתוארים בדף Omniscol API — טוקני אימות; מחברי הסנכרון מתוארים בדף סנכרון עם מערכות חיצוניות (ERP).

הצורה המדויקת והממצה של כל שדה נשארת מוגדרת בסכמת ה-JSON של החשבון (https://api.omniscol.com/api/guest/school_schema.json, מציג קריא בכתובת omniscol.com/fr/datamodel). אם יש סתירה בין דף זה לסכמה, הסכמה גוברת.

ראו גם