@thanh01.pmt/interactive-quiz-kit 1.0.8 → 1.0.9

package/HEADLESS.md

@@ -0,0 +1,333 @@
+# Chế độ Headless: Sử dụng Logic của `interactive-quiz-kit` mà không cần Giao diện
+
+**`interactive-quiz-kit`** được thiết kế với kiến trúc module hóa, cho phép bạn sử dụng toàn bộ logic lõi của nó một cách độc lập mà không cần đến các thành phần giao diện người dùng React. Chế độ "headless" này lý tưởng cho các trường hợp sử dụng như sau:
+
+* Xây dựng một backend để quản lý và tạo quiz.
+* Tích hợp logic quiz vào một ứng dụng di động (React Native, Flutter,...).
+* Chạy các script tự động để tạo nội dung hoặc xử lý dữ liệu quiz.
+* Tích hợp vào các framework JavaScript khác ngoài React.
+
+Tài liệu này sẽ hướng dẫn bạn cách import và sử dụng các tính năng headless chính của thư viện.
+
+## I. Tổng quan các Thành phần Headless
+
+Các thành phần non-UI của thư viện được phân bổ trong các thư mục sau:
+
+| Thư mục/File          | Chức năng Chính                                                           |
+| :-------------------- | :------------------------------------------------------------------------ |
+| `types.ts`            | **(Cốt lõi)** Định nghĩa tất cả các cấu trúc dữ liệu (interfaces) cho quiz. |
+| `services/`           | **(Cốt lõi)** Chứa các service để chạy, quản lý, và đóng gói quiz.         |
+| `ai/`                 | Chứa các flow để tạo nội dung quiz bằng Trí tuệ Nhân tạo.                   |
+| `utils/idGenerators.ts` | Các hàm tiện ích, ví dụ như tạo ID duy nhất.                             |
+| `schemas/`            | Các file JSON Schema để xác thực cấu trúc dữ liệu của quiz.                |
+
+### 1. Chế độ Headless là gì và Tại sao nó quan trọng?
+
+Hãy tưởng tượng thư viện của bạn như một chiếc xe hơi hoàn chỉnh. Giao diện người dùng (`react-ui/`) chính là phần thân vỏ, nội thất, vô lăng, bảng điều khiển—tất cả những gì bạn thấy và tương tác. "Chế độ headless" chính là việc bạn có thể lấy toàn bộ **động cơ, khung gầm, hệ thống truyền động và bộ não điều khiển (ECU)** của chiếc xe đó ra và lắp vào một thân vỏ khác—ví dụ như một chiếc xe tải, một chiếc thuyền, hoặc thậm chí một cỗ máy công nghiệp.
+
+Nói cách khác, **chế độ headless cho phép bạn sử dụng tất cả các logic, quy trình nghiệp vụ, và khả năng xử lý dữ liệu của thư viện mà không cần đến giao diện người dùng React đi kèm.**
+
+**Tại sao nó quan trọng?**
+
+* **Linh hoạt tối đa:** Bạn không bị trói buộc vào React. Bạn có thể xây dựng giao diện bằng Vue, Svelte, Angular, hoặc thậm chí là ứng dụng di động native (iOS, Android) và chỉ cần gọi đến logic lõi của thư viện.
+* **Tự động hóa & Tích hợp Backend:** Bạn có thể chạy các quy trình trên server, ví dụ:
+    * Một cron job hàng đêm dùng module AI để tự động tạo ra hàng trăm câu hỏi mới và lưu vào cơ sở dữ liệu.
+    * Xây dựng một API endpoint để quản lý, chỉnh sửa, và xuất bản các bài quiz.
+* **Tái sử dụng Logic:** Đảm bảo logic nghiệp vụ (ví dụ: cách chấm điểm một câu hỏi) là nhất quán ở mọi nơi, từ web, mobile đến các script nội bộ.
+
+---
+
+### 2. Phân tích chi tiết các Thành phần Headless
+
+Dưới đây là từng thành phần, vai trò, và tầm quan trọng của chúng trong chế độ headless.
+
+#### **A. `types.ts` & `schemas/` - Nền tảng & Quy tắc**
+
+* **Vai trò:** Là "Hiến pháp" và "Bộ luật" của thư viện. Chúng định nghĩa cấu trúc dữ liệu và các quy tắc mà mọi thành phần khác phải tuân theo.
+* **Mô tả chi tiết:**
+    * **`types.ts`:** Đây là file quan trọng nhất. Nó chứa các `interface` TypeScript như `QuizConfig`, `QuizQuestion`, `QuizResult`. Đây là "nguồn chân lý duy nhất" (single source of truth) cho hình dạng của dữ liệu. Bất kỳ hàm nào bạn viết để tương tác với quiz đều sẽ nhận và trả về các kiểu dữ liệu được định nghĩa ở đây.
+    * **`schemas/`:** Chứa các file JSON Schema. Trong môi trường headless, chúng cực kỳ hữu ích để **xác thực (validate)** dữ liệu. Ví dụ, khi một hệ thống khác gửi cho bạn một file JSON `quiz.json`, bạn có thể dùng schema này để kiểm tra xem file đó có hợp lệ hay không trước khi xử lý.
+* **Tầm quan trọng:** **Nền tảng (Fundamental)**. Không thể sử dụng thư viện nếu không hiểu các kiểu dữ liệu này.
+
+---
+
+#### **B. `services/QuizEditorService.ts` - Người Thợ Xây**
+
+* **Vai trò:** Công cụ để **tạo, sửa, xóa, và sắp xếp** các câu hỏi bên trong một đối tượng `QuizConfig`. Đây là service dành cho khâu *biên soạn (authoring)*.
+* **Mô tả chi tiết:**
+    * Đây là một lớp (class) bạn khởi tạo với một đối tượng `QuizConfig` ban đầu. Nó sẽ làm việc trên một bản sao sâu (deep copy), đảm bảo không làm thay đổi đối tượng gốc một cách không mong muốn (nguyên tắc immutability).
+    * **`createNewQuestionTemplate(type)` (Static Method):** Tạo ra một "khuôn mẫu" câu hỏi rỗng với các giá trị mặc định. Rất hữu ích khi bạn muốn thêm một câu hỏi mới.
+    * **`addQuestion(question)`:** Thêm một câu hỏi vào danh sách.
+    * **`updateQuestion(updatedQuestion)`:** Cập nhật một câu hỏi đã có dựa trên `id` của nó.
+    * **`deleteQuestionByIndex(index)`:** Xóa một câu hỏi dựa trên vị trí của nó.
+    * **`moveQuestion(fromIndex, toIndex)`:** Thay đổi thứ tự các câu hỏi.
+* **Tầm quan trọng:** **Cốt lõi (Core)** cho bất kỳ tác vụ nào liên quan đến việc quản lý nội dung quiz.
+
+* **Ví dụ sử dụng:**
+
+    ```typescript
+    import { QuizEditorService, emptyQuiz } from 'interactive-quiz-kit/services';
+
+    // Bắt đầu với một quiz rỗng
+    let myQuiz = emptyQuiz;
+    const editor = new QuizEditorService(myQuiz);
+
+    // Thêm một câu hỏi True/False
+    const tfQuestion = QuizEditorService.createNewQuestionTemplate('true_false');
+    tfQuestion.prompt = "Trái Đất có phải là một hình cầu hoàn hảo không?";
+    if (tfQuestion.questionType === 'true_false') tfQuestion.correctAnswer = false;
+    
+    myQuiz = editor.addQuestion(tfQuestion);
+
+    // Cập nhật lại tiêu đề quiz
+    myQuiz.title = "Quiz đã được cập nhật bằng code";
+
+    console.log(myQuiz);
+    ```
+
+---
+
+#### **C. `services/QuizEngine.ts` - Nhạc trưởng Điều hành**
+
+* **Vai trò:** Quản lý toàn bộ vòng đời của một **phiên làm bài quiz thực tế**. Đây là service dành cho khâu *thực thi (runtime)*.
+* **Mô tả chi tiết:**
+    * Khởi tạo với một `QuizConfig` và một bộ `callbacks`. Thiết kế dựa trên callback này làm cho nó cực kỳ linh hoạt để tích hợp vào bất kỳ hệ thống nào.
+    * Nó quản lý trạng thái nội bộ: câu hỏi hiện tại, câu trả lời của người dùng, thời gian còn lại.
+    * Cung cấp các phương thức công khai (public methods) như `nextQuestion()`, `previousQuestion()`, `submitAnswer()`, và `calculateResults()` để điều khiển luồng làm bài.
+    * Logic chấm điểm phức tạp cho 12 loại câu hỏi được đóng gói hoàn toàn bên trong `evaluateQuestion`.
+* **Tầm quan trọng:** **Cốt lõi (Core)** cho bất kỳ ứng dụng nào muốn cho người dùng *làm* bài quiz.
+
+---
+
+#### **D. `ai/flows/` - Bộ não Sáng tạo**
+
+* **Vai trò:** Cung cấp các hàm `async` để giao tiếp với AI và tự động tạo ra nội dung quiz.
+* **Mô tả chi tiết:**
+    * Mỗi file là một "flow" có thể gọi được. Chúng nhận đầu vào có cấu trúc (nhờ `zod`) và trả về kết quả cũng có cấu trúc.
+    * **`generate...Question`:** Các flow tạo câu hỏi đơn lẻ.
+    * **`generateQuizPlan` & `generateQuestionsFromQuizPlan`:** Một quy trình 2 giai đoạn mạnh mẽ cho phép tạo ra một bài quiz hoàn chỉnh, cân bằng về chủ đề và độ khó, thay vì chỉ là một mớ câu hỏi ngẫu nhiên.
+* **Tầm quan trọng:** **Tính năng nâng cao (Advanced Feature)**. Lý tưởng cho các hệ thống muốn tự động hóa việc tạo nội dung.
+
+* **Ví dụ sử dụng (trong một script backend):**
+
+    ```typescript
+    import { generateQuizPlan, generateQuestionsFromQuizPlan } from 'interactive-quiz-kit/ai';
+
+    async function generateFullQuiz() {
+      const planInput = {
+        totalQuestions: 5,
+        topics: [{ topic: 'Lịch sử Việt Nam', ratio: 100 }],
+        bloomLevels: [{ level: 'remembering', ratio: 60 }, { level: 'understanding', ratio: 40 }],
+        selectedQuestionTypes: ['multiple_choice', 'true_false']
+      };
+      
+      const plan = await generateQuizPlan(planInput);
+      
+      const quizResult = await generateQuestionsFromQuizPlan({ quizPlan: plan.quizPlan });
+
+      console.log(`${quizResult.generatedQuestions.length} câu hỏi đã được tạo.`);
+      // => Lưu các câu hỏi này vào DB
+    }
+    ```
+
+---
+
+#### **E. `services/` (các file liên quan đến SCORM) & `utils/` - Hộp Dụng cụ & Giao tiếp**
+
+* **Vai trò:** Cung cấp các công cụ chuyên biệt để hoàn thành các tác vụ cụ thể.
+* **Mô tả chi tiết:**
+    * **`SCORMService.ts`:** Một lớp độc lập để nói chuyện với LMS. Nó không biết gì về quiz, chỉ biết về các lệnh SCORM. `QuizEngine` sẽ sử dụng nó.
+    * **`generateSCORMManifest`, `generateLauncherHTML`:** Các hàm này nhận dữ liệu và trả về các chuỗi văn bản (XML, HTML). Chúng không có tác dụng phụ (side-effect) và hoàn toàn "thuần khiết" (pure), rất phù hợp cho môi trường headless.
+    * **`idGenerators.ts`:** Cung cấp hàm `generateUniqueId`, một tiện ích nhỏ nhưng cần thiết khi bạn tạo dữ liệu mới.
+* **Tầm quan trọng:** **Hỗ trợ (Supporting)**. Cần thiết cho các chức năng cụ thể như SCORM hoặc khi cần tạo dữ liệu mới.
+
+Bằng cách kết hợp các thành phần này, bạn có thể xây dựng một hệ thống hoàn chỉnh ở phía backend để tạo, quản lý quiz, và thậm chí mô phỏng các phiên làm bài để kiểm thử mà không cần viết một dòng code giao diện nào.
+
+---
+
+## II. Các Kiểu Dữ liệu (Types) - Nền tảng của Thư viện
+
+Trước khi bắt đầu, bạn cần làm quen với các kiểu dữ liệu chính. Mọi tương tác với thư viện đều xoay quanh chúng.
+
+```typescript
+import { QuizConfig, QuizQuestion, TrueFalseQuestion } from 'interactive-quiz-kit';
+
+// Tạo một câu hỏi
+const myQuestion: TrueFalseQuestion = {
+  id: 'tf-001',
+  questionType: 'true_false',
+  prompt: 'Mặt trời mọc ở hướng Tây.',
+  correctAnswer: false,
+  points: 10
+};
+
+// Tạo một cấu hình quiz hoàn chỉnh
+const myQuizConfig: QuizConfig = {
+  id: 'my-first-headless-quiz',
+  title: 'Quiz Khoa Học Vui',
+  questions: [myQuestion],
+  settings: {
+    shuffleQuestions: true,
+    timeLimitMinutes: 10
+  }
+};
+```
+
+**Các kiểu dữ liệu quan trọng nhất:**
+
+* `QuizConfig`: Toàn bộ cấu hình quiz.
+* `QuizQuestion`: Union type của tất cả các loại câu hỏi.
+* Các kiểu câu hỏi cụ thể: `MultipleChoiceQuestion`, `FillInTheBlanksQuestion`, `BlocklyProgrammingQuestion`, v.v.
+* `QuizResult`: Cấu trúc dữ liệu kết quả trả về.
+
+---
+
+## III. Sử dụng Dịch vụ Lõi
+
+### 1. `QuizEditorService`: Tạo và Chỉnh sửa Quiz
+
+Service này cho phép bạn thực hiện các thao tác CRUD (Create, Read, Update, Delete) trên một đối tượng `QuizConfig`.
+
+```typescript
+import { QuizEditorService, emptyQuiz } from 'interactive-quiz-kit/services';
+import type { QuestionTypeStrings } from 'interactive-quiz-kit';
+
+// Bắt đầu với một quiz rỗng
+const editor = new QuizEditorService(emptyQuiz);
+
+// Tạo một template câu hỏi trắc nghiệm mới
+const mcqTemplate = QuizEditorService.createNewQuestionTemplate('multiple_choice');
+
+// Cập nhật thông tin cho câu hỏi
+mcqTemplate.prompt = "Hành tinh nào gần mặt trời nhất?";
+if (mcqTemplate.questionType === 'multiple_choice') {
+  mcqTemplate.options = [
+    { id: 'opt1', text: 'Trái Đất' },
+    { id: 'opt2', text: 'Sao Hỏa' },
+    { id: 'opt3', text: 'Sao Thủy' },
+  ];
+  mcqTemplate.correctAnswerId = 'opt3';
+}
+
+// Thêm câu hỏi vào quiz
+editor.addQuestion(mcqTemplate);
+
+// Xóa câu hỏi (nếu cần, ví dụ tại index 0)
+// editor.deleteQuestionByIndex(0);
+
+// Lấy đối tượng QuizConfig cuối cùng
+const finalQuizConfig = editor.getQuiz();
+
+console.log(JSON.stringify(finalQuizConfig, null, 2));
+```
+
+### 2. `QuizEngine`: Chạy một Phiên làm bài Quiz
+
+Service này là bộ não xử lý logic khi một người dùng đang làm bài quiz.
+
+```typescript
+import { QuizEngine } from 'interactive-quiz-kit/services';
+import type { QuizConfig, QuizResult } from 'interactive-quiz-kit';
+
+// Giả sử bạn đã có một đối tượng myQuizConfig
+const myQuizConfig: QuizConfig = /* ... */;
+
+console.log("Bắt đầu quiz...");
+
+const engine = new QuizEngine({
+  config: myQuizConfig,
+  callbacks: {
+    onQuestionChange: (question, qNum, total) => {
+      console.log(`\n--- Câu hỏi ${qNum}/${total} ---`);
+      console.log(question?.prompt);
+    },
+    onQuizFinish: (result: QuizResult) => {
+      console.log("\n--- KẾT QUẢ ---");
+      console.log(`Điểm số: ${result.score}/${result.maxScore}`);
+      console.log(`Phần trăm: ${result.percentage.toFixed(2)}%`);
+      console.log(`Trạng thái: ${result.passed ? 'Đạt' : 'Không đạt'}`);
+    }
+  }
+});
+
+// Mô phỏng quá trình làm bài
+const question1 = engine.getCurrentQuestion();
+if (question1) {
+  // Giả sử câu 1 là True/False
+  engine.submitAnswer(question1.id, false); 
+}
+
+engine.nextQuestion();
+
+const question2 = engine.getCurrentQuestion();
+if (question2) {
+    // Giả sử câu 2 là Multiple Choice
+  engine.submitAnswer(question2.id, 'id_cua_dap_an_dung');
+}
+
+// Kết thúc quiz
+engine.calculateResults();
+```
+
+---
+
+## IV. Tạo Nội dung bằng AI
+
+Bạn có thể sử dụng các flow AI để tự động tạo câu hỏi. Các hàm này là `async`.
+
+*Lưu ý: Để sử dụng, bạn cần có môi trường đã cấu hình Google Genkit và các biến môi trường cần thiết (ví dụ: `GOOGLE_API_KEY`).*
+
+```typescript
+import { generateMCQQuestion, generateQuizPlan } from 'interactive-quiz-kit/ai';
+
+async function createAIQuestion() {
+  try {
+    console.log('Đang tạo câu hỏi trắc nghiệm về Hệ Mặt Trời...');
+    const result = await generateMCQQuestion({
+      topic: 'Hệ Mặt Trời',
+      difficulty: 'easy'
+    });
+
+    if (result.question) {
+      console.log('Câu hỏi đã được tạo:');
+      console.log(JSON.stringify(result.question, null, 2));
+    } else {
+      console.log('AI không thể tạo câu hỏi.');
+    }
+
+  } catch (error) {
+    console.error('Lỗi khi tạo câu hỏi AI:', error);
+  }
+}
+
+// createAIQuestion();
+```
+
+---
+
+## V. Đóng gói và Xuất bản
+
+Các hàm này giúp tạo ra các thành phần của một gói SCORM. Chúng trả về nội dung dạng chuỗi (string) mà bạn có thể ghi ra file.
+
+```typescript
+import { generateSCORMManifest, generateLauncherHTML } from 'interactive-quiz-kit/services';
+import type { QuizConfig } from 'interactive-quiz-kit';
+// import * as fs from 'fs'; // Dùng trong môi trường Node.js
+
+// Giả sử bạn đã có một đối tượng myQuizConfig
+const myQuizConfig: QuizConfig = /* ... */;
+
+// Tạo nội dung manifest
+const manifestXML = generateSCORMManifest(myQuizConfig, "1.2");
+console.log('--- imsmanifest.xml ---');
+console.log(manifestXML);
+// fs.writeFileSync('dist/imsmanifest.xml', manifestXML);
+
+// Tạo nội dung file HTML launcher
+const launcherHTML = generateLauncherHTML(myQuizConfig);
+console.log('\n--- index.html ---');
+console.log(launcherHTML);
+// fs.writeFileSync('dist/index.html', launcherHTML);
+```
+
+**Lưu ý:** Hàm `exportQuizAsSCORMZip` được thiết kế để chạy trên trình duyệt vì nó tương tác với DOM để kích hoạt tải file. Nếu bạn muốn đóng gói ZIP ở phía backend, bạn cần sử dụng một thư viện như `jszip` và tự mình thực hiện các bước tương tự như trong file `services/scormPackaging.ts`.

package/README.md

@@ -104,7 +104,7 @@ const MyAuthoringPage = () => {
 
 Use the library's services, types, and AI flows in any JavaScript/TypeScript environment (e.g., Node.js backend, other frontend frameworks, scripts).
 
-> For detailed examples and a full component list, see [**HEADLESS.md**](./src/HEADLESS.md).
+> For detailed examples and a full component list, see [**HEADLESS.md**](./HEADLESS.md).
 
 #### Example: Creating a Quiz Programmatically with `QuizEditorService`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thanh01.pmt/interactive-quiz-kit",
-  "version": "1.0.8",
+  "version": "1.0.9",
   "description": "A comprehensive library for creating, managing, and playing interactive quizzes, with AI generation and SCORM support.",
   "keywords": [
     "react",