sena_db_api_layer/workers/README_LESSON_DATA_FILL.md

Lesson Data Fill Worker

Worker này tự động xử lý các lesson trong database và tạo task lên BullMQ để xử lý dữ liệu.

Chức năng

Worker sẽ:

1. Lấy các lesson từ database (chỉ lesson đã publish và có content_json)
2. Phân tích content_json để trích xuất:
   • Danh sách vocabulary IDs
   • Danh sách grammar IDs
3. Tạo task lên BullMQ queue process-data với label process_data

Cài đặt

Worker sử dụng BullMQ và Redis đã được cấu hình sẵn trong project.

Chạy Worker

1. Chạy worker trực tiếp:

node workers/lessonDataFillWorker.js

Worker sẽ chạy và lắng nghe jobs từ queue lesson-data-fill.

2. Trigger worker xử lý tất cả lessons:

# Xử lý tất cả lessons (mặc định batch size = 50)
node scripts/triggerLessonDataFill.js

# Xử lý với batch size tùy chỉnh
node scripts/triggerLessonDataFill.js --batch-size 100

# Xử lý giới hạn số lượng lessons
node scripts/triggerLessonDataFill.js --total 200

# Chỉ xử lý lessons có content_type cụ thể
node scripts/triggerLessonDataFill.js --type vocabulary

# Chỉ xử lý lessons trong một chapter
node scripts/triggerLessonDataFill.js --chapter <chapter-id>

# Kết hợp các options
node scripts/triggerLessonDataFill.js --batch-size 100 --total 500 --type grammar

Cấu trúc dữ liệu

Input (Lesson content_json)

{
  "type": "vocabulary",
  "vocabulary_ids": ["uuid1", "uuid2", "uuid3"],
  "exercises": [...]
}

hoặc

{
  "type": "grammar",
  "grammar_ids": ["uuid1", "uuid2"],
  "examples": [...],
  "exercises": [...]
}

hoặc review lesson:

{
  "type": "review",
  "sections": [
    {
      "type": "vocabulary",
      "vocabulary_ids": ["uuid1", "uuid2"]
    },
    {
      "type": "grammar",
      "grammar_ids": ["uuid3"]
    }
  ]
}

Output (Task data gửi lên BullMQ)

{
  "type": "lesson_data",
  "lesson": {
    "lesson_id": "uuid",
    "lesson_title": "Lesson Title",
    "lesson_number": 1,
    "lesson_content_type": "vocabulary",
    "chapter_id": "uuid",
    "chapter_title": "Chapter Title",
    "vocabularies": ["vocab-uuid-1", "vocab-uuid-2"],
    "grammars": ["grammar-uuid-1"]
  },
  "timestamp": "2026-01-27T10:30:00.000Z"
}

Queue và Worker Configuration

• Input Queue: lesson-data-fill
• Output Queue: process-data
• Job Label: process_data
• Concurrency: 3 jobs đồng thời
• Rate Limit: 10 jobs/second
• Retry: 3 lần với exponential backoff

Monitoring

Worker sẽ log các thông tin sau:

[LessonDataFillWorker] Starting job <job-id>
[LessonDataFillWorker] Found 50 lessons
[LessonDataFillWorker] Lesson <lesson-id>: 10 vocabularies
[LessonDataFillWorker] Lesson <lesson-id>: 5 grammars
[LessonDataFillWorker] ✅ Created task: <task-id> for lesson <lesson-id>
[LessonDataFillWorker] ✅ Created 45 process_data tasks
[LessonDataFillWorker] ✅ Job <job-id> completed

Filters

Worker hỗ trợ các filter sau:

• lesson_content_type: Lọc theo loại nội dung (vocabulary, grammar, phonics, review, mixed)
• chapter_id: Lọc theo chapter cụ thể
• Luôn chỉ lấy lesson đã publish (is_published = true)
• Luôn chỉ lấy lesson có content_json (lesson_type = 'json_content')

Error Handling

• Worker sẽ tự động retry 3 lần khi gặp lỗi
• Failed jobs sẽ được giữ lại 7 ngày để review
• Completed jobs sẽ được giữ lại 24 giờ

Integration

Để xử lý các task process_data được tạo ra, bạn cần tạo một worker khác để consume queue process-data:

const { Worker } = require('bullmq');
const { connectionOptions } = require('../config/bullmq');

const processDataWorker = new Worker(
  'process-data',
  async (job) => {
    const { lesson } = job.data;
    
    // Xử lý dữ liệu lesson ở đây
    console.log('Processing lesson:', lesson.lesson_id);
    console.log('Vocabularies:', lesson.vocabularies);
    console.log('Grammars:', lesson.grammars);
    
    // TODO: Implement your processing logic
  },
  {
    connection: connectionOptions,
    prefix: process.env.BULLMQ_PREFIX || 'vcb',
  }
);

Graceful Shutdown

Worker hỗ trợ graceful shutdown khi nhận signal SIGTERM hoặc SIGINT:

# Dừng worker an toàn
Ctrl + C

Worker sẽ:

1. Dừng nhận job mới
2. Hoàn thành các job đang xử lý
3. Đóng kết nối Redis
4. Thoát process