完整数据模型：JSON实体、关系与本体

本页描述Omniscol账户的完整数据模型：实体、主要字段及其关系。它是概念性页面 数据组织 的延伸：那一页解释为什么（学校基础数据 ↔ 课表、本地副本）；这里的目标是是什么——一份可直接使用的结构图，尤其适合把模型与外部基础数据对接（管理软件、通讯录、信息系统）。

**技术页面。**本参考面向集成以及与外部系统的匹配。日常使用Omniscol 并不需要它：如果想从业务角度了解数据的组织方式，请参见 数据组织。

学校的所有数据都以树状结构组织。下文描述的实体（用户、学年、课表、缺勤、事件等）对应这棵树的各个分支。规范性的参照是账户的JSON结构（schema），它有两种查看方式：

• 原始源文件（原样的JSON schema），由账户通过https://api.omniscol.com/api/guest/school_schema.json提供；
• 树状查看器，见omniscol.com/fr/datamodel（对应的API参考见omniscol.com/fr/developers）。

该schema精确描述了数据库中以JSON文档形式存储的物理结构。本页给出的是对它有条理且长期稳定的解读。

学校文档：根节点

根文档汇集了学校的长期基础数据和所有排课安排。它的一级子树如下：

以“字典”形式表示的子树是JSON对象，其键是稳定的标识符（任何外部对接的枢纽——参见最后一节）。

通用字段：_extids和wishes

有两个字段会出现在许多实体上。为避免在每个schema中重复，这里统一说明一次。

• _extids（ExternalIds）——该实体在外部系统中的标识符对照表，例如{ "auriga": "12345" }。出现在可同步的实体上（科目、类别、用户、校区、教室、资源、教师、班级、小组等）。它是与外部基础数据匹配的锚点（参见最后一节）。
• wishes——时间限制：可用时间、期望或应避开的时段、最大授课小时数、首选教室等。出现在大多数可排课的实体上：用户、课表中的教师、课程（班级科目）、小组、班级、教室、校区时间范围、监督网格。视范围不同，这些限制是全局的（学校层面），或仅属于某张课表。

第一层——学校基础数据

学校基础数据包含与具体课表无关、对整个学校都成立的内容：科目目录、用户通讯录、学年日历。

科目——SubjectFull / Subject / Family

自定义科目（SubjectFull）在基础科目（Subject：name、short、code、type、_extids）之上增加了parent、family和color。学校层面存在两种来源：该国家的通用科目（只读）和学校的自定义科目。功能细节参见 科目管理。

用户——User（包括教师）

User是通讯录中唯一的实体：身份（姓、名、idnumber、联系方式）、身份验证（login）、roles、基准服务时间（字段servicehours）、全局可用时间（wishes字段）和placements。教师不是单独的实体：他是roles中含teacher的User（同一用户可以兼有多个角色）。placements字段（按学年索引）把学生在某一时期归入某个class和若干groups。详情参见 教师管理。

学年——SchoolYear / Holiday

SchoolYear定义date_start → date_end、holidays列表和altweeks（交替周）。它是一个时间框架，而不是容器：课表在其中展开，但并不嵌套于其中。参见 学年。

第二层——课表

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子树承载，有三种形式：

另见总览 班级、小组、子小组。

第三层——课时

课时（Lesson）是真正安排进课表的教学单元：时长、科目、小组、教师、教室、资源、位置和状态。它由某个班级科目（见第二层）生成，并附属于某个班级（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都派生自基础课时，基础课时仍可辨认。
• _osrev——修订令牌（乐观锁），每次修改都会递增（时间戳 + 修改序号），并且严格按字母顺序排列（因此很容易判断某个修订是否比另一个更新）。协同编辑借此发现并合并并发修改：客户端修订过期即表示有冲突，服务器会裁决或合并，而不是悄悄覆盖。

缺勤

缺勤共用一个基础结构（Absence：date_start、date_end、reason、hours、comment、状态），再按对象分化。

AbsenceTeacher可以限定在某些subjects/classes上，并带有一个代课规则数组（substitutes，每条是一个AbsenceTeacherSubstitute：代课人、期间、时段、涉及的班级和科目）。状态因对象而异（例如班级使用ok/aborted）。参见术语表 代课 / 替课 和 缺勤管理 模块。

员工

这是一个独立模块（也可单独购买），用于监督和值守服务。

StaffingGrid是模板（日期、时段）；assignments描述岗位（req/ideal、priority，以及通过StaffingNeedSpan按时段细化的needs）；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，以及按Omniscol键和标识符建立的对应表（mappings）。在编程访问方面，REST API和令牌见Omniscol API——身份验证令牌；同步连接器见与外部系统同步（ERP）。

每个字段的确切完整形式，仍以账户的参照JSON schema为准（https://api.omniscol.com/api/guest/school_schema.json，可读的查看器见omniscol.com/fr/datamodel）。本页与schema如有出入，以schema为准。