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

```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