Omniscol vận hành thế nào — một API duy nhất, một nguồn sự thật duy nhất

Có vài điểm về cách Omniscol được xây dựng rất đáng biết trước khi bạn tích hợp với nó — chúng giải thích vì sao API lại đầy đủ đến vậy, cách giao diện thích ứng với từng người dùng, và một điểm về quyền riêng tư cần lưu ý.

Một ứng dụng duy nhất trên một API duy nhất

Omniscol chạy như một ứng dụng web duy nhất trong trình duyệt của bạn. Mỗi màn hình, mỗi nút và mỗi bảng đều được vẽ ra bằng cách gọi API công khai của Omniscol — cũng chính là API mà bạn có thể tự gọi, được mô tả trong tài liệu tham chiếu API tương tác của Omniscol, trang Nhà phát triển (omniscol.com/vi/developers). Không hề có một API ẩn, “thật sự”, nằm sau API mà bạn tích hợp: những gì giao diện dùng chính là những gì bạn nhận được. Một vài thao tác lại đi theo chiều ngược lại — được cung cấp cho việc tích hợp nhưng bản thân ứng dụng không dùng đến: chẳng hạn các điểm truy cập tìm kiếm nâng cao và phân giải thực thể (dành cho một tác nhân AI qua MCP), hoặc những điểm truy cập cho phép một hệ thống bên ngoài cấp dữ liệu vào Omniscol (một ETL giữ cho một cơ sở dữ liệu bên ngoài luôn đồng bộ).

operationId — một khóa, một nguồn sự thật duy nhất

Mỗi thao tác là một cặp phương thức + URL (ví dụ GET /api/schedules/lessons/{datesrange}), và mỗi thao tác đều mang một mã định danh ổn định: operationId của nó (ở đây là os_schedules_dates_get). Tên này có cấu trúc rõ ràng: os (Omniscol), rồi đến mô-đun (schedules), rồi đến đối tượng mà thao tác tác động lên (dates — đôi khi gồm nhiều đoạn nối với nhau bằng dấu gạch ngang), và luôn luôn là phương thức HTTP ở cuối (get, post, put, delete). Chính khóa duy nhất ấy được Omniscol dùng ở khắp nơi — để gọi tên thao tác trên trang Nhà phát triển, để dựng công cụ MCP tương ứng, và để chỉ tới nó từ một lần ghi đè hay từ trang trợ giúp này. Chỉ được định nghĩa một lần, khóa ấy giữ cho mọi nơi nó xuất hiện luôn khớp nhau: tài liệu, công cụ và giao diện không thể lệch khỏi nhau, vì tất cả đều đọc cùng một định nghĩa.

Giao diện đi theo quyền của bạn

Một thành phần giao diện có gắn hành động — một nút, một thẻ, một mục menu — chỉ hiện ra khi thao tác đứng sau nó có sẵn với bạn. Điều đó tùy thuộc vào vai trò của bạn và vào vai trò tùy chỉnh (xem Người dùng và vai trò), vào gói dịch vụ và các tùy chọn của bạn (xem Các gói và tùy chọn của Omniscol). Thay đổi một trong những yếu tố ấy và giao diện tự dựng lại: các thành phần, thậm chí cả những mô-đun trọn vẹn, sẽ hiện ra hoặc biến mất theo.

Nguyên tắc ấy còn áp dụng ra ngoài phạm vi quyền cá nhân của bạn. Bộ phận công nghệ thông tin có thể tắt một số thao tác bằng một lần ghi đè API, và các thành phần tương ứng sẽ biến mất khỏi giao diện (xem Tùy chỉnh API). Điều tương tự cũng xảy ra khi một dữ liệu được giữ cập nhật bởi một cơ chế đồng bộ bên ngoài: việc tạo và sửa dữ liệu ấy ngay tại chỗ có thể bị tắt đi, và các nút lệnh tương ứng nhường chỗ cho cơ chế đồng bộ (xem Đồng bộ hóa với các hệ thống bên ngoài).

Vì vậy Omniscol không có cổng thông tin riêng cho học sinh hay giáo viên. Chỉ có một ứng dụng duy nhất; mỗi người nhìn thấy giao diện khớp với quyền của chính mình — một học sinh, một giáo viên, một quản trị viên và người mang một vai trò tùy chỉnh, mỗi người nhận đúng những thao tác mà mình được phép, không hơn.

Giao diện là sự tiện lợi, không phải ổ khóa

Vì giao diện được điều khiển bởi quyền của bạn, người ta dễ nghĩ rằng một nút bị ẩn đi là một ranh giới bảo mật. Không phải vậy. Mọi lệnh gọi đều được kiểm tra lại trên máy chủ dựa trên danh tính và quyền của bạn; một thao tác mà bạn không được phép sẽ bị từ chối ngay tại đó, bất kể giao diện đang hiển thị gì. Giao diện thích ứng để mọi thứ rõ ràng và dễ dùng; ranh giới thật sự được áp dụng ở phía máy chủ, với từng yêu cầu.

Mã thông báo và liên kết chia sẻ, cùng một mô hình

Một mã thông báo API hay một liên kết chia sẻ đều bị giới hạn trong một tập thao tác — những thao tác mà bạn cho phép khi tạo ra nó. Máy chủ áp dụng giới hạn ấy cho từng lệnh gọi, y hệt như với một người dùng đã đăng nhập. Một liên kết chia sẻ, một mã thông báo và một người dùng trên giao diện là ba cách để tới cùng một API được kiểm soát bằng quyền — chứ không bao giờ là một cửa sau đi vòng qua nó.

Vượt qua một lần mất kết nối

Vì mọi màn hình đều đọc dữ liệu từ API, Omniscol còn có thể giữ lại trong trình duyệt của bạn những phản hồi đã nhận, để một lần mất mạng ngắn không cắt ngang việc bạn đang xem. Bản sao cục bộ ấy nằm trong cơ sở dữ liệu riêng của nó (IndexedDB), bên cạnh bộ nhớ đệm trang thông thường của trình duyệt. Đây là một bộ nhớ đệm để đọc: nếu kết nối rớt, bạn vẫn tiếp tục thấy những gì mình đã mở. Nó không xếp hàng các thay đổi của bạn và cũng không phát lại chúng — một thay đổi thì luôn đi qua máy chủ.

Bản sao cục bộ này dựa trên sự đồng ý của bạn. Lần đầu tiên trên một trình duyệt, Omniscol hỏi bạn có tin tưởng trình duyệt ấy hay không; bản sao chỉ bắt đầu sau khi bạn đã chấp nhận. Về sau, mục Bộ nhớ đệm ngoại tuyến trong menu người dùng bật nó lên hoặc xóa nó đi bất cứ lúc nào — một dấu kiểm cho biết nó đang hoạt động.

Hai điều cần biết:

• Dữ liệu cá nhân bị loại ra. Chỉ những lần đọc thành công mới được giữ lại; những phản hồi mà máy chủ đánh dấu là không được lưu (dữ liệu phiên làm việc và dữ liệu xác thực) không bao giờ vào bộ nhớ đệm, và từ những gì có vào bộ nhớ đệm, phần mềm gỡ bỏ những thông tin nhận dạng của từng người — e-mail, điện thoại, ngày sinh, tên đăng nhập, số định danh, trạng thái mật khẩu — rồi xóa hẳn các tài khoản quản trị viên. Bản sao cục bộ chứa dữ liệu làm việc thông thường, chứ không phải danh bạ thông tin cá nhân.
• Trên một máy dùng chung, hãy ưu tiên cửa sổ duyệt web riêng tư (ẩn danh). Việc đăng xuất không xóa bản sao cục bộ này (cũng không xóa bộ nhớ đệm thông thường của trình duyệt); một cửa sổ riêng tư sẽ xóa cả hai khi nó đóng lại. Đó là mức cẩn trọng nên dành cho mọi ứng dụng web trên một máy mà bạn không kiểm soát.