broker-core-sdk

v1.0.7

Published

a month ago

0High
0Medium
0Low

Core SDK - Adaptive Learning System

Đây là bộ công cụ lõi (Core SDK) chứa toàn bộ logic nghiệp vụ, thuật toán học tập, hằng số (constants) và các định nghĩa dữ liệu (types) dùng chung cho toàn bộ hệ thống Adaptive Learning. SDK này được thiết kế theo hướng Functional Programming, hỗ trợ Tree-shaking tối đa và đảm bảo tính nhất quán (Type-safety) giữa các nền tảng Web (Admin), Mobile (Learner) và Backend.

🚀 Tính năng chính

Constants Management: Quản lý các biến hằng (như loại phần tử, mức độ tự tin) tập trung.
Learning Engine: Thuật toán Spaced Repetition (Lặp lại ngắt quãng) và tính toán mức độ thành thạo (Mastery).
Game Engine: Logic "trọng tài" kiểm tra kết quả Đúng/Sai thống nhất cho tất cả 12 dạng Game (Quiz, Sorting, Matching, Hotspot, Memory Card, Fill in the Blank, Swipe, Timed Sprint, Word Scramble, Crossword, Branching, Label Image).
Slide Renderer Math: Bộ công thức chuyển đổi tọa độ linh hoạt giữa giá trị % và Pixel.
Discriminated Union Types: Hệ thống Type chặt chẽ, tự động ánh xạ cấu trúc data theo type của phần tử, hỗ trợ Autocomplete tối đa cho IDE.

📦 Cài đặt

Dành cho dự án trong cùng Monorepo (Workspace)

Thêm vào file package.json của project cần dùng:

"dependencies": {
  "@broker/core-sdk": "workspace:*"
}

Dành cho dự án độc lập

npm install ../path-to/core-sdk

🛠 Hướng dẫn sử dụng chi tiết

1. Hệ thống Constants & Type

Bộ SDK cung cấp sẵn các object constants giúp bạn không phải fix cứng chuỗi ("QUIZ", "High",...) ở các dự án khác.

import { ELEMENT_TYPES, CONFIDENCE_LEVELS } from "@broker/core-sdk";
import type { ElementType, ConfidenceLevel } from "@broker/core-sdk";

// Sử dụng thay cho hardcode text
const myType: ElementType = ELEMENT_TYPES.QUIZ;
const conf: ConfidenceLevel = CONFIDENCE_LEVELS.HIGH;

2. SlideElement & Type Safety (Mới)

SlideElement hiện đã được chuyển sang dạng Discriminated Union. Khi bạn sử dụng trong code, IDE sẽ tự động gợi ý các trường trong data dựa trên type.

import type { SlideElement } from "@broker/core-sdk";

const element: SlideElement = {
  id: "e1",
  type: "QUIZ", // Khi type là QUIZ
  position: { x: 0, y: 0, w: 100, h: 100 },
  data: {
    question: "TypeScript là gì?",
    options: [{ id: "1", content: "Ngôn ngữ lập trình" }],
    correctId: "1"
  } // IDE sẽ autocomplete các trường của MultipleChoiceData
};

3. Learning Engine (Tính toán lộ trình học)

import { learningEngine, CONFIDENCE_LEVELS } from "@broker/core-sdk";

const daysToAdd = learningEngine.calculateNextReview(true, CONFIDENCE_LEVELS.HIGH); // Kết quả: 7
const isMastered = learningEngine.checkMastery(3, CONFIDENCE_LEVELS.HIGH); // Kết quả: true

🏗 Cấu trúc SDK (Hệ thống Types mới)

Thư mục src/types/ đã được quy hoạch lại để dễ quản lý:

common.ts: Chứa các kiểu dữ liệu dùng chung cơ bản (như Position).
data.ts: Tập trung toàn bộ Payload của phần tử (TextData, VideoData, MultipleChoiceData,... và ElementDataMap).
elements.ts: Định nghĩa cấu trúc khung của phần tử (SlideElement, ElementStyle, ElementType).
models.ts: Các thực thể lớn của hệ thống (Course, Lesson, Slide, UserProgress, ActionLog).
actions.ts: Định nghĩa các sự kiện kích hoạt (ACTION_TRIGGERS), loại side-effects (ACTION_TYPES) và payload hành động tương ứng (ActionPayloadMap).

Ngoài ra, các thư mục lõi khác bao gồm:

src/engines/: Chứa game-engine.ts (chấm điểm 12 loại game) và learning-engine.ts (lịch ôn tập Spaced Repetition và Mastery).
src/renderer/: Chứa slide-renderer.ts (chuyển đổi tọa độ giữa % và Pixel).
src/sync/: Chứa action-manager.ts (quản lý hàng đợi đồng bộ offline và xử lý xung đột Last Sync Wins).

🧪 Phát triển và Kiểm thử

SDK là "trái tim" của hệ thống nên mọi thay đổi nhỏ đều có thể ảnh hưởng diện rộng.

Test Driven:
```
npm test
```
Build & Verify Types:
```
npm run build
```
(Lệnh này sử dụng tsup để đóng gói và tạo file .d.ts. Luôn chạy lệnh này để đảm bảo không có lỗi Type trước khi commit).

📝 Quy định khi mở rộng (Guidelines)

Không Magic Strings: Luôn định nghĩa hằng số vào elements.ts (cho ELEMENT_TYPES và GAME_TYPES) hoặc models.ts (cho CONFIDENCE_LEVELS).
Consolidate Data: Khi thêm loại phần tử mới, hãy định nghĩa Interface data của nó trong data.ts và cập nhật vào ElementDataMap.
Discriminated Union: Không sử dụng any cho trường data trong SlideElement. Hãy để hệ thống tự ánh xạ thông qua ElementDataMap.
Vanilla TS: SDK không được phụ thuộc vào bất kỳ Framework nào (React/Node-specific).
Import Suffix: Bắt buộc các câu lệnh import tương đối trong nội bộ SDK phải ghi đầy đủ hậu tố .js (ví dụ: import { ... } from "./elements.js") để tuân thủ kiến trúc phân phối ESM (nodenext).