Полная модель данных: сущности JSON, связи и онтология

На этой странице описана полная модель данных аккаунта Omniscol: сущности, их основные поля и связи. Она продолжает концептуальную страницу Организация данных, которая объясняет, зачем всё устроено так (справочник школы ↔ расписание, локальные копии); здесь речь о том, что именно хранится: это пригодная для работы структурная карта, в частности чтобы связать модель с внешним справочником (ERP-системой, каталогом пользователей, информационной системой).

Техническая страница. Этот справочник предназначен для интеграции и сопоставления с внешней системой. Он не нужен для повседневной работы в Omniscol: чтобы понять, как организованы данные с прикладной точки зрения, см. Организация данных.

Все данные учебного заведения организованы в виде дерева. Описанные ниже сущности (пользователи, учебные годы, расписания, отсутствия, события и т. д.) соответствуют разным ветвям этой структуры. Нормативный источник — JSON-схема аккаунта. Её можно посмотреть в двух видах:

• исходный текст (JSON-схема как есть), который аккаунт отдаёт по адресу https://api.omniscol.com/api/guest/school_schema.json;
• древовидный просмотр, удобный для чтения, на странице omniscol.com/fr/datamodel (а соответствующий справочник API — на странице omniscol.com/fr/developers).

Эта схема точно описывает физическое хранение в базе в виде JSON-документа. На этой странице приведено её упорядоченное изложение, которое не меняется со временем.

Документ школы: корень

Корневой документ объединяет постоянный справочник учебного заведения и всё его планирование. Поддеревья первого уровня:

Поддеревья, названные «словарём», — это JSON-объекты, в которых ключи являются стабильными идентификаторами (основа любого внешнего связывания — см. последний раздел).

Сквозные поля: _extids и wishes

Два поля встречаются во многих сущностях. Чтобы не повторять их в каждой схеме, они описаны один раз здесь.

• _extids (ExternalIds) — таблица идентификаторов сущности во внешних системах, например { "auriga": "12345" }. Есть у сущностей, которые можно синхронизировать (дисциплины, семейства, пользователи, площадки, кабинеты, ресурсы, преподаватели, классы, группы…). Это точка привязки для сопоставления с внешним справочником (см. последний раздел).
• wishes — временные ограничения: доступность, желательные слоты или слоты, которых следует избегать, максимальная нагрузка в часах, предпочитаемый кабинет… Есть у большинства сущностей, которые можно планировать: пользователей, преподавателей расписания, курсов (дисциплин класса), групп, классов, кабинетов, временных диапазонов площадки, сеток надзора. В зависимости от охвата эти ограничения общие (на уровне школы) или относятся к одному расписанию.

Уровень 1 — Справочник школы

Справочник школы содержит то, что верно для учебного заведения независимо от расписания: каталог дисциплин, каталог пользователей, календарь учебных годов.

Дисциплины — SubjectFull / Subject / Family

Собственная дисциплина (SubjectFull) расширяет базовую дисциплину (Subject: name, short, code, type, _extids) полями parent, family и color. На уровне школы сосуществуют два источника: общие дисциплины страны (только для чтения) и собственные дисциплины учебного заведения. Подробное описание функций: Управление дисциплинами.

Пользователи — User (включая преподавателей)

User — это единая сущность каталога: личные данные (фамилия, имя, idnumber, контакты), аутентификация (login), roles, базовая часовая нагрузка (servicehours), общая доступность (поле wishes) и placements. Преподаватель — не отдельная сущность: это User, у которого среди roles есть teacher (один и тот же пользователь может совмещать несколько ролей). Поле placements (индексируется по учебному году) привязывает ученика к class и groups на определённый период. Подробности: Управление преподавателями.

Учебные годы — SchoolYear / Holiday

SchoolYear задаёт date_start → date_end, список holidays и altweeks (чередование недель). Это временные рамки, а не контейнер: расписания разворачиваются внутри них, но не вложены в них. См. Учебный год.

Уровень 2 — Расписание

Timetable — это целостная единица планирования. У него есть собственная локальная копия преподавателей, классов, групп и дисциплин — о принципе локальной копии см. Организация данных.

Конфигурация — 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 расписания и бывают трёх видов:

См. также общий обзор Класс, группа, подгруппа.

Уровень 3 — Занятия

Занятие (Lesson) — это единица обучения, которая реально размещена в расписании: продолжительность, дисциплина, группа, преподаватель (преподаватели), кабинет, ресурсы, позиция и статус. Оно формируется на основе дисциплины класса (см. уровень 2) и относится либо к классу (class.lessons), либо непосредственно к расписанию (timetable.lessons) — последний вариант для групп групп и занятий для нескольких групп, общих для нескольких классов.

Основа занятия

Занятие содержит поля планирования — 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 каждого экземпляра производится от _id базового занятия, так что исходный идентификатор остаётся узнаваемым.
• _osrev — маркер ревизии (оптимистичная блокировка), который увеличивается при каждом изменении (отметка времени + индекс изменения) и строго упорядочен по алфавиту (так легко определить, новее ли одна ревизия другой). Он позволяет совместному редактированию обнаруживать и сливать одновременные изменения: устаревшая клиентская ревизия сигнализирует о конфликте, который сервер разрешает или сливает вместо того, чтобы молча перезаписать данные.

Отсутствия

У отсутствий общая основа (Absence: date_start, date_end, reason, hours, comment, статус), которая уточняется для каждого субъекта.

AbsenceTeacher можно ограничить определёнными subjects/classes; в ней хранится массив правил замещения (substitutes, каждое из которых — это AbsenceTeacherSubstitute: замещающий, период, временные слоты, классы и дисциплины, которые охватывает правило). Статусы различаются для каждого субъекта (например, ok/aborted для класса). См. глоссарий Замещение / Замена и модуль Управление отсутствиями.

Сотрудники

Отдельный модуль (его можно приобрести и самостоятельно) для надзора и дежурств персонала.

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 и токены описаны на странице Токены API; коннекторы синхронизации — на странице Синхронизация с внешними системами.

Точная и исчерпывающая форма каждого поля определяется эталонной JSON-схемой аккаунта (https://api.omniscol.com/api/guest/school_schema.json, удобный для чтения просмотр на omniscol.com/fr/datamodel). Если эта страница и схема расходятся, верна схема.