update new API

VOCAB_CONTEXT_IMPORT_GUIDE.md

@@ -0,0 +1,300 @@
+# Hướng Dẫn Sử Dụng Script Vocab Context
+
+## 📋 Tổng Quan
+
+Có 2 script để quản lý vocabulary trong bảng Context:
+
+1. **`import-vocab-to-context.js`** - Nhập vocabulary từ file JSON vào database
+2. **`update-vocab-context.js`** - Cập nhật/thay đổi thông tin vocabulary đã nhập
+
+---
+
+## 🚀 Script 1: Import Vocabulary
+
+### Mô tả
+Script này đọc tất cả file JSON trong thư mục `data/moveup/` (g1, g2, g3, g4, g5) và tạo record trong bảng Context cho mỗi từ vựng.
+
+### Chạy Script
+
+```bash
+node import-vocab-to-context.js
+```
+
+### Dữ liệu được tạo
+
+Mỗi vocabulary word sẽ tạo một record với:
+- **title**: từ vựng (vd: "dad", "mom", "hello")
+- **grade**: mã grade (vd: 101, 102, 103)
+- **type**: "vocabulary"
+- **context**: "Vocabulary word for grade {grade}"
+
+### Ví dụ Output
+
+```
+🔄 Starting vocab import to Context table...
+✅ Database connection OK
+
+📂 Processing G1 (1 files)...
+  📄 Reading M1S.json...
+    📚 Grade 101: 4 vocab words
+    📚 Grade 102: 7 vocab words
+    📚 Grade 103: 4 vocab words
+
+✅ Import complete!
+📊 Total imported: 150
+⏭️  Total skipped (duplicates): 25
+```
+
+### Tính năng
+- ✅ Tự động bỏ qua duplicates (cùng title + grade)
+- ✅ Xử lý nhiều file JSON trong mỗi grade folder
+- ✅ Hiển thị progress chi tiết
+- ✅ Error handling cho từng record
+
+---
+
+## 🔧 Script 2: Update Vocabulary Context
+
+### Mô tả
+Script này cho phép cập nhật, xóa hoặc xem danh sách vocabulary đã nhập.
+
+### Chạy Script
+
+```bash
+node update-vocab-context.js
+```
+
+### Các Chế Độ (UPDATE_MODE)
+
+#### 1. Cập nhật 1 từ cụ thể (`'single'`)
+
+```javascript
+const UPDATE_MODE = 'single';
+
+const SINGLE_UPDATE = {
+  oldTitle: 'dad',
+  grade: 101,
+  updates: {
+    title: 'dad',
+    context: 'Family member - father',
+    knowledge: 'Common family vocabulary for beginners',
+    desc: 'Từ chỉ bố/cha trong tiếng Anh'
+  }
+};
+```
+
+**Chạy:**
+```bash
+node update-vocab-context.js
+```
+
+**Output:**
+```
+🔍 Looking for vocab: "dad" in grade 101...
+✅ Found vocab: dad
+📝 Updating...
+✅ Updated successfully!
+```
+
+---
+
+#### 2. Cập nhật hàng loạt theo grade (`'bulk_by_grade'`)
+
+```javascript
+const UPDATE_MODE = 'bulk_by_grade';
+
+const BULK_UPDATE = {
+  grade: 101,
+  updates: {
+    context: 'Grade 1 Unit 1 Lesson 1 vocabulary',
+    knowledge: 'Basic greeting and family vocabulary'
+  }
+};
+```
+
+**Chạy:**
+```bash
+node update-vocab-context.js
+```
+
+**Output:**
+```
+🔍 Looking for all vocab in grade 101...
+✅ Found 15 vocab words
+📝 Updating...
+✅ Updated 15 vocab words successfully!
+```
+
+---
+
+#### 3. Xóa vocabulary (`'delete'`)
+
+```javascript
+const UPDATE_MODE = 'delete';
+
+const DELETE_CONFIG = {
+  title: 'test_word',
+  grade: 101
+};
+```
+
+**Chạy:**
+```bash
+node update-vocab-context.js
+```
+
+**Output:**
+```
+🔍 Looking for vocab: "test_word" in grade 101...
+✅ Deleted 1 vocab entry!
+```
+
+---
+
+#### 4. Xem danh sách vocabulary (`'list'`)
+
+```javascript
+const UPDATE_MODE = 'list';
+
+// Trong function main(), thay đổi grade number:
+result = await listVocabByGrade(101); // Change 101 to your grade
+```
+
+**Chạy:**
+```bash
+node update-vocab-context.js
+```
+
+**Output:**
+```
+📚 Listing all vocab in grade 101...
+
+✅ Found 15 vocab words:
+
+1. dad
+   Context: Family member - father
+   Knowledge: Common family vocabulary
+   
+2. mom
+   Context: Family member - mother
+   Knowledge: Common family vocabulary
+   
+...
+```
+
+---
+
+## 📝 Các Trường Có Thể Cập Nhật
+
+Trong phần `updates`, bạn có thể thay đổi:
+
+- **title**: Tên từ vựng
+- **context**: Mô tả ngữ cảnh sử dụng
+- **knowledge**: Kiến thức bổ sung
+- **desc**: Mô tả chi tiết (có thể dùng tiếng Việt)
+- **grade**: Mã grade (không khuyến khích thay đổi)
+- **type**: Loại (mặc định là 'vocabulary')
+
+---
+
+## 💡 Ví Dụ Sử Dụng Thực Tế
+
+### Ví dụ 1: Import tất cả vocab từ file JSON
+
+```bash
+node import-vocab-to-context.js
+```
+
+### Ví dụ 2: Thêm mô tả tiếng Việt cho các từ ở grade 101
+
+1. Mở `update-vocab-context.js`
+2. Đổi thành mode `'bulk_by_grade'`
+3. Cấu hình:
+
+```javascript
+const UPDATE_MODE = 'bulk_by_grade';
+
+const BULK_UPDATE = {
+  grade: 101,
+  updates: {
+    context: 'Từ vựng Unit 1 - Gia đình và chào hỏi',
+    knowledge: 'Các từ cơ bản về gia đình và cách chào hỏi lần đầu gặp mặt'
+  }
+};
+```
+
+4. Chạy: `node update-vocab-context.js`
+
+### Ví dụ 3: Cập nhật thông tin chi tiết cho 1 từ
+
+1. Mở `update-vocab-context.js`
+2. Đổi thành mode `'single'`
+3. Cấu hình:
+
+```javascript
+const UPDATE_MODE = 'single';
+
+const SINGLE_UPDATE = {
+  oldTitle: 'Hello',
+  grade: 101,
+  updates: {
+    title: 'Hello',
+    context: 'Greeting word used when meeting someone',
+    knowledge: 'Most common English greeting. Used in formal and informal contexts.',
+    desc: 'Lời chào phổ biến nhất trong tiếng Anh. "Hello" là cách chào hỏi trang trọng và lịch sự.'
+  }
+};
+```
+
+4. Chạy: `node update-vocab-context.js`
+
+### Ví dụ 4: Xem tất cả vocab trong grade 102
+
+1. Mở `update-vocab-context.js`
+2. Đổi thành mode `'list'`
+3. Tìm dòng `result = await listVocabByGrade(101);` và đổi thành `102`
+4. Chạy: `node update-vocab-context.js`
+
+---
+
+## ⚠️ Lưu Ý
+
+1. **Backup Database**: Luôn backup database trước khi chạy script
+2. **Kiểm tra kết nối**: Đảm bảo `config/database.js` được cấu hình đúng
+3. **Duplicate handling**: Script import tự động bỏ qua duplicates
+4. **Grade format**: Grade phải là số nguyên (vd: 101, 201, 305)
+5. **Type field**: Luôn giữ `type: 'vocabulary'` để phân biệt với các loại context khác
+
+---
+
+## 🔍 Troubleshooting
+
+### Lỗi: "Database connection failed"
+```bash
+# Kiểm tra config database
+cat config/database.js
+# Kiểm tra MySQL có chạy không
+```
+
+### Lỗi: "Cannot find module"
+```bash
+# Cài đặt dependencies
+npm install
+```
+
+### Không import được từ nào
+- Kiểm tra format file JSON
+- Đảm bảo field `vocab` là một array
+- Kiểm tra đường dẫn file JSON
+
+### Xem log chi tiết
+Script sẽ tự động hiển thị progress và errors trong console.
+
+---
+
+## 📞 Hỗ Trợ
+
+Nếu gặp vấn đề, kiểm tra:
+1. Console output để xem lỗi chi tiết
+2. Database logs
+3. Format của file JSON input