sena_db_api_layer/VOCAB_CONTEXT_IMPORT_GUIDE.md

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

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

node update-vocab-context.js

Các Chế Độ (UPDATE_MODE)

1. Cập nhật 1 từ cụ thể ('single')

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:

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')

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:

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')

const UPDATE_MODE = 'delete';

const DELETE_CONFIG = {
  title: 'test_word',
  grade: 101
};

Chạy:

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')

const UPDATE_MODE = 'list';

// Trong function main(), thay đổi grade number:
result = await listVocabByGrade(101); // Change 101 to your grade

Chạy:

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

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:

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:

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"

# Kiểm tra config database
cat config/database.js
# Kiểm tra MySQL có chạy không

Lỗi: "Cannot find module"

# 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