@thanh01.pmt/interactive-quiz-kit 1.0.0

package/README.md

@@ -0,0 +1,176 @@
+# Interactive Quiz Kit Library
+
+## Giới thiệu
+
+**Interactive Quiz Kit** là một thư viện JavaScript/TypeScript được xây dựng với React, được thiết kế để dễ dàng tạo, quản lý và chơi các bài quiz tương tác. Thư viện này cung cấp một bộ logic lõi mạnh mẽ (\`QuizEngine\`), các thành phần giao diện người dùng React có thể tái sử dụng, và hỗ trợ cho nhiều loại câu hỏi đa dạng. Nó được xây dựng với mục tiêu dễ dàng mở rộng và tích hợp vào các ứng dụng React hiện có.
+
+Các tính năng nổi bật bao gồm quản lý trạng thái quiz, chấm điểm tự động, tích hợp SCORM, gửi kết quả qua webhook, và các công cụ tạo quiz trực quan với sự hỗ trợ của AI (sử dụng Genkit và Gemini) để tạo câu hỏi đơn lẻ và toàn bộ bài quiz.
+
+## Tính năng cốt lõi
+
+### 1. \`QuizEngine\` (Logic Lõi)
+Thành phần trung tâm xử lý toàn bộ logic của quiz:
+- **Quản lý Câu hỏi:** Theo dõi câu hỏi hiện tại, điều hướng (tiến, lùi, nhảy đến câu bất kỳ), và phục hồi trạng thái.
+- **Xáo trộn:** Hỗ trợ xáo trộn thứ tự câu hỏi và các lựa chọn trong câu hỏi (nếu được cấu hình).
+- **Chấm điểm:** Tự động chấm điểm dựa trên câu trả lời của người dùng và đáp án đúng được định nghĩa cho từng loại câu hỏi.
+- **Tính toán Kết quả:** Tổng hợp điểm số, tính phần trăm, xác định trạng thái đậu/rớt.
+- **Phân tích Thời gian:** Theo dõi thời gian làm bài cho từng câu hỏi và tổng thời gian làm quiz.
+- **Tích hợp SCORM:** Làm việc với \`SCORMService\` để báo cáo điểm, trạng thái hoàn thành và thời gian cho LMS.
+- **Gửi Webhook:** Gửi kết quả quiz chi tiết đến một URL webhook được cấu hình.
+- **Callbacks:** Cung cấp các callback cho các sự kiện quan trọng (bắt đầu quiz, thay đổi câu hỏi, nộp bài, kết thúc quiz) để tùy chỉnh hành vi.
+
+### 2. Thành phần Giao diện Người dùng React
+Thư viện cung cấp các thành phần React sẵn sàng sử dụng:
+- **\`QuizPlayer\`:** Thành phần chính để hiển thị và tương tác với bài quiz.
+- **\`QuizResult\`:** Hiển thị kết quả chi tiết sau khi hoàn thành quiz.
+- **\`QuestionRenderer\`:** Tự động hiển thị câu hỏi dựa trên loại của nó.
+- **Giao diện cho từng Loại Câu hỏi:** Các thành phần UI chuyên biệt cho mỗi loại câu hỏi được hỗ trợ (ví dụ: \`MultipleChoiceQuestionUI\`, \`TrueFalseQuestionUI\`, \`ScratchProgrammingQuestionUI\` v.v.).
+- **\`QuizDataManagement\`:** Cho phép người dùng nhập quiz từ file JSON.
+
+### 3. Công cụ Tạo Quiz (\`QuizAuthoringTool\`)
+Một bộ thành phần mạnh mẽ để tạo và chỉnh sửa quiz một cách trực quan:
+- **Chỉnh sửa Cài đặt Quiz:** Tiêu đề, mô tả, các tùy chọn xáo trộn, giới hạn thời gian, v.v.
+- **Quản lý Câu hỏi:** Thêm, sửa, xóa, sắp xếp lại thứ tự câu hỏi.
+- **\`EditQuestionModal\`:** Một modal đa năng để chỉnh sửa chi tiết của từng câu hỏi, bao gồm cả metadata phong phú.
+- **Hỗ trợ Tạo bằng AI:**
+    - **\`AIQuestionGeneratorModal\`:** Tạo câu hỏi đơn lẻ bằng AI dựa trên chủ đề, ngữ cảnh, loại câu hỏi, và cấp độ Bloom.
+    - **\`AIFullQuizGeneratorModal\`:** Tạo toàn bộ bài quiz bằng AI theo quy trình hai giai đoạn (lập kế hoạch quiz và tạo câu hỏi chi tiết), cho phép người dùng xem xét và điều chỉnh kế hoạch.
+
+### 4. Các Loại Câu hỏi được Hỗ trợ
+Thư viện hỗ trợ một loạt các loại câu hỏi:
+1.  **Multiple Choice (Trắc nghiệm - một đáp án)**
+2.  **Multiple Response (Trắc nghiệm - nhiều đáp án)**
+3.  **Fill In The Blanks (Điền vào chỗ trống)**
+4.  **Drag and Drop (Kéo thả)** - Hiện UI Player dùng Select thay thế
+5.  **True/False (Đúng/Sai)**
+6.  **Short Answer (Trả lời ngắn)**
+7.  **Numeric (Trả lời bằng số)**
+8.  **Sequence (Sắp xếp thứ tự)**
+9.  **Matching (Ghép nối)** - Hiện UI Player dùng Select thay thế cho từng mục
+10. **Hotspot (Điểm nóng trên ảnh)**
+11. **Blockly Programming (Lập trình kéo thả khối Blockly)**
+12. **Scratch Programming (Lập trình Scratch - sử dụng Blockly với renderer Zelos)**
+
+### 5. Quản lý Dữ liệu Quiz
+- **Định nghĩa Kiểu TypeScript:** Cung cấp các interface rõ ràng (\`QuizConfig\`, \`QuizQuestion\`, v.v.) cho cấu trúc dữ liệu quiz.
+- **Nhập/Xuất JSON:** Dễ dàng lưu và tải quiz dưới dạng file JSON.
+- **Đóng gói SCORM:**
+    - \`SCORMManifestGenerator\`: Tạo file \`imsmanifest.xml\`.
+    - \`HTMLLauncherGenerator\`: Tạo file HTML launcher cho SCORM.
+
+### 6. Tích hợp AI (với Genkit & Gemini)
+- Sử dụng các flow Genkit để tương tác với Gemini API.
+- **Tạo Câu hỏi Đơn lẻ:** Các flow như \`generateMCQQuestion\`, \`generateTrueFalseQuestion\`, v.v.
+- **Tạo Toàn bộ Quiz:**
+    - \`generate-quiz-plan-flow.ts\`: Lập kế hoạch cấu trúc quiz.
+    - \`generateQuestionsFromQuizPlanFlow.ts\`: Tạo các câu hỏi chi tiết dựa trên kế hoạch.
+
+## Thành phần và Dịch vụ Chính
+
+- **\`QuizPlayer.tsx\`**: Thành phần chính để người dùng làm quiz.
+- **\`QuizAuthoringTool.tsx\`**: Giao diện chính để tạo và chỉnh sửa quiz.
+- **\`QuizEngine.ts\`**: Lớp logic xử lý trạng thái, chấm điểm, và các hoạt động của quiz.
+- **\`SCORMService.ts\`**: Xử lý giao tiếp với SCORM API của LMS.
+- **\`QuestionRenderer.tsx\`**: Quyết định và hiển thị UI phù hợp cho từng loại câu hỏi.
+- **Các thành phần UI câu hỏi (ví dụ: \`MultipleChoiceQuestionUI.tsx\`)**: Hiển thị và xử lý tương tác cho từng loại câu hỏi cụ thể.
+- **Các form câu hỏi (ví dụ: \`MultipleChoiceQuestionForm.tsx\`)**: Được sử dụng trong \`EditQuestionModal\` để chỉnh sửa từng loại câu hỏi.
+- **Các flow AI (trong \`src/ai/flows/\`)**: Logic Genkit để tạo nội dung quiz bằng AI.
+
+## Cài đặt (Hướng dẫn nếu tách thành thư viện riêng)
+
+Nếu thư viện này được publish lên npm, bạn có thể cài đặt bằng:
+\`\`\`bash
+npm install interactive-quiz-kit
+# hoặc
+yarn add interactive-quiz-kit
+\`\`\`
+Để phát triển local và sử dụng trong project khác, bạn có thể dùng \`npm link\`.
+
+## Sử dụng Cơ bản (trong một ứng dụng React)
+
+### Hiển thị Quiz cho Người dùng:
+\`\`\`tsx
+import React, { useState } from 'react';
+import { QuizPlayer, QuizConfig, QuizResult as QuizResultType } from 'interactive-quiz-kit';
+
+// Ví dụ cấu hình quiz (hoặc tải từ JSON)
+const myQuiz: QuizConfig = {
+  id: "my-example-quiz",
+  title: "My Example Quiz",
+  questions: [ /* ... mảng các đối tượng câu hỏi ... */ ],
+  settings: { /* ... cài đặt quiz ... */ }
+};
+
+const App = () => {
+  const [quizResult, setQuizResult] = useState<QuizResultType | null>(null);
+
+  const handleQuizComplete = (result: QuizResultType) => {
+    console.log("Quiz Complete!", result);
+    setQuizResult(result);
+    // Xử lý kết quả (ví dụ: hiển thị, gửi lên server)
+  };
+
+  const handleExitQuiz = () => {
+    console.log("Exiting quiz");
+    // Điều hướng người dùng hoặc làm mới trạng thái
+  };
+
+  return (
+    <QuizPlayer
+      quizConfig={myQuiz}
+      onQuizComplete={handleQuizComplete}
+      onExitQuiz={handleExitQuiz} // Tùy chọn
+    />
+  );
+};
+
+export default App;
+\`\`\`
+
+### Sử dụng Công cụ Tạo Quiz:
+\`\`\`tsx
+import React, { useState } from 'react';
+import { QuizAuthoringTool, QuizConfig, emptyQuiz } from 'interactive-quiz-kit';
+
+const AuthoringPage = () => {
+  // initialQuiz có thể là null (tạo mới), hoặc một QuizConfig đã có để sửa
+  const [initialQuiz, setInitialQuiz] = useState<QuizConfig | null>(null); 
+
+  const handleSaveAuthoredQuiz = (savedQuiz: QuizConfig) => {
+    console.log("Quiz Saved:", savedQuiz);
+    // Lưu quiz (ví dụ: localStorage, backend)
+  };
+
+  const handleExitAuthoring = () => {
+    console.log("Exiting authoring tool");
+    // Điều hướng người dùng
+  };
+  
+  return (
+    <QuizAuthoringTool
+      initialQuizConfig={initialQuiz || emptyQuiz} // Cung cấp quiz rỗng nếu tạo mới
+      onSaveQuiz={handleSaveAuthoredQuiz}
+      onExitAuthoring={handleExitAuthoring} // Tùy chọn
+    />
+  );
+};
+
+export default AuthoringPage;
+\`\`\`
+
+## Cấu trúc Dữ liệu
+- **\`QuizConfig\`**: Interface chính định nghĩa toàn bộ cấu trúc của một bài quiz, bao gồm ID, tiêu đề, mô tả, danh sách câu hỏi (\`QuizQuestion[]\`), và các cài đặt (\`QuizSettings\`).
+- **\`QuizQuestion\`**: Một union type bao gồm tất cả các loại câu hỏi cụ thể (ví dụ: \`MultipleChoiceQuestion\`, \`TrueFalseQuestion\`). Mỗi loại câu hỏi kế thừa từ \`BaseQuestion\` và có các thuộc tính riêng.
+- **JSON Schemas**: Các schema JSON cho \`QuizConfig\` và từng loại câu hỏi được cung cấp trong thư vực \`schemas/\` để tham khảo và xác thực.
+
+## Đóng góp
+Mọi đóng góp đều được chào đón! Vui lòng gửi pull request hoặc mở issue nếu bạn có ý tưởng cải thiện hoặc tìm thấy lỗi.
+
+## Giấy phép
+MIT
+        
+## Các Vấn đề đã Biết (Known Issues - Library Specific)
+*   **Tích hợp Blockly/Scratch:** Cần đảm bảo các tài nguyên Blockly (CSS, media) được tải đúng cách khi thư viện được sử dụng độc lập. \`ScratchProgrammingQuestionUI\` hiện sử dụng renderer 'zelos' của Blockly để có giao diện giống Scratch.
+*   **Đóng gói SCORM:** Các hàm tạo manifest và launcher có sẵn, nhưng việc đóng gói tự động thành file ZIP hoàn chỉnh cần được người dùng thực hiện thủ công hoặc tích hợp thêm.
+*   **Tạo Câu hỏi AI cho Drag & Drop và Hotspot:** Các flow AI chuyên biệt để tạo câu hỏi Drag & Drop và Hotspot từ đầu chưa được triển khai. AI cũng chưa hỗ trợ tạo ảnh cho câu hỏi Hotspot.
+*   **Hoàn thiện UI cho Scratch Programming:** Giao diện người dùng (\`ScratchProgrammingQuestionUI.tsx\`) và form tương ứng trong công cụ tạo quiz (\`ScratchProgrammingQuestionForm.tsx\`) đã được tạo nhưng có thể cần tinh chỉnh thêm về mặt thẩm mỹ và toolbox mặc định để hoàn toàn giống với môi trường Scratch tiêu chuẩn.