Omniscol的工作原理——一套API，唯一数据源

在集成Omniscol之前，有几点关于它构建方式的说明值得了解——它们解释了API为何如此完整、界面如何适应每位用户，以及一个需要牢记的隐私问题。

一个应用，一套API

Omniscol在您的浏览器中作为单页Web应用运行。每个界面、按钮和表格，都是通过调用Omniscol的公开API绘制出来的——这和您可以自行调用的是同一套API，文档见Omniscol的交互式API参考，即开发者页面（omniscol.com/fr/developers）。您所集成的API背后并没有隐藏的“真实” API：界面使用什么，您就能得到什么。少数操作则相反——专为集成提供，但应用本身并不使用：例如高级搜索和实体解析接入点（供AI智能体通过 MCP 使用），以及允许外部系统向Omniscol写入数据的接入点（例如让外部数据库保持同步的ETL）。

operationId——一个键，一个数据源

每个操作都是一个方法加URL的组合（例如 GET /api/schedules/lessons/{datesrange}），并带有一个稳定的标识符：它的operationId（此处为 os_schedules_dates_get）。这个名称是有结构的：先是 os（Omniscol），然后是模块（schedules），再是操作所针对的对象（dates——有时由多段以连字符连接而成），最后始终是HTTP方法（get、post、put、delete）。Omniscol在各处都使用这个唯一的键——在开发者页面中命名该操作，构建对应的 MCP 工具，也在API自定义或本帮助中引用该操作。它只定义一次，让所有环节保持同步：文档、工具和界面不会出现分歧，因为它们读取的是同一份定义。

界面随您的权限而变

带有操作的图形元素——按钮、选项卡、菜单项——只有在支撑它的操作对您开放时才会出现。这取决于您的角色和自定义角色（参见 自定义角色和 用户与角色），以及您的套餐和选项（参见 Omniscol的套餐与选项）。修改其中任何一项，界面都会重新组合：相应的元素，甚至整个模块，会随之出现或消失。

同样的原则也适用于个人权限之外。IT部门可以通过API自定义停用某些操作，相应的界面元素随即消失（参见 API自定义）。当某项数据由外部同步维护时也是如此：本地创建和修改可被停用，相应的控件将让位于同步（参见 与外部系统同步）。

因此，Omniscol 没有为学生或教师单独设置的门户。只有一个应用；每个人看到的界面都与自己的权限同步——学生、教师、管理员和自定义角色持有者，得到的恰好是他们有权使用的操作，不多也不少。

界面是便利，而不是锁

由于界面由您的权限驱动，人们容易把隐藏的按钮看作安全边界。其实不是。每次调用都会在服务器上重新验证您的身份和权限；无论界面显示什么，您无权执行的操作都会在服务器上被拒绝。界面是为了清晰和方便而调整的；真正的边界由服务器在每次请求时执行。

令牌和分享链接，同一个模型

一个 API令牌或分享链接，会被限制在一组操作内——也就是您在创建时授权的那些。服务器在每次调用时都会执行这一限制，与已登录的用户完全一样。分享链接、令牌和界面中的用户，是访问同一套受权限控制的API的三种方式——绝不是绕过它的后门。

应对网络中断

由于每个界面都读取API，Omniscol还可以在您的浏览器中保留已收到的响应，让短暂的断网不会中断您的阅读。这个本地副本存放在浏览器的数据库（IndexedDB）中，与浏览器常规的页面缓存并存。它是一个读取缓存：如果网络中断，您仍能看到已经打开过的内容。它不会把您的修改排入队列，也不会重新执行——修改始终要经过服务器。

这个本地副本取决于您的同意。第一次在某个浏览器上使用时，Omniscol会询问您是否信任它；您接受后，才开始创建副本。之后，用户菜单中的 离线缓存 项可以随时启用或清除它——打勾表示已启用。

有两点需要了解：

• **个人数据不在其中。**只保留成功的读取；服务器标记为不可存储的响应（会话和身份验证数据）绝不会被缓存，而对于已缓存的内容，软件会去掉人员的联系方式——电子邮箱、电话、出生日期、登录名、证件号、密码状态——并完全删除管理员账户。本地副本包含普通的工作数据，而不是实名通讯录。
• **在共享电脑上，请优先使用隐私浏览窗口。**退出登录不会清除这个本地副本（也不会清除浏览器的常规缓存）；关闭隐私窗口时，两者都会被删除。对于任何不受您控制的电脑上的Web应用，这都是应有的谨慎。