Tạo bài tập nhỏ

Sinh bài tập cho một mã lỗi đơn lẻ. Dạng bài và số câu suy ra từ mã lỗi.

Request

Field	Type	Bắt buộc	Mô tả
topic	string	BẮT BUỘC	Ví dụ: environment, family, education
writing_task	1 \| 2	BẮT BUỘC	Loại Task IELTS Writing
criterion	string	BẮT BUỘC	Task 1: task_achievement — Task 2: task_response — chung: coherence_cohesion, lexical_resource, grammar_range_accuracy
error_code	string	BẮT BUỘC	Mã lỗi cụ thể
references	array	BẮT BUỘC	Danh sách bài mẫu chứa lỗi của học viên, lấy từ sample-references

Response

Bài tập ứng với dạng bài do error_code quyết định (xem bảng ánh xạ trong tài liệu gốc). Ví dụ dưới đây là dạng multiple_choice_single.

Lưu ý

ai_grading trả về dạng string ("true"/"false"), không phải boolean.
Chỉ có ví dụ response đầy đủ cho 2/7 dạng bài (multiple_choice_single, short_writing) — 5 dạng còn lại chưa được backend cho ví dụ.
Luôn trả 200 kể cả khi AI sinh lỗi định dạng (graceful fallback) — kiểm tra exercise.length thay vì dựa vào status code để biết có sinh thành công hay không.

curl -X POST 'https://test-api-ielts-writing.aihubproduction.com/create-micro-exercise' \
  -H 'Content-Type: application/json' \
  -d '{
  "topic": "environment",
  "writing_task": 2,
  "criterion": "lexical_resource",
  "error_code": "collocation_error",
  "references": [
    {
      "question": {
        "prompt": "The best way to solve the world's environmental problem is to increase the cost of fuel for cars and other vehicles. To what extent do you agree or disagree?",
        "question_type": "agree_disagree"
      },
      "comments": [
        {
          "quote": "Forests do a crucial role in absorbing carbon dioxide...",
          "explanation": "Collocation đúng phải là 'play a crucial role'."
        }
      ]
    }
  ]
}'

Lỗi thường gặp

Áp dụng chung cho các endpoint sinh bài tập trong docs/doc-api-micro.md.

200Graceful fallback

AI sinh lỗi định dạng hoặc vi phạm schema validation. Hệ thống không trả 500 mà trả 200 kèm exercise rỗng.

{
  "success": true,
  "message": "Lỗi parse JSON hoặc validate từ AI. Trả về kết quả mặc định rỗng.",
  "data": {
    "meta": {
      "number_of_questions": 0
    },
    "exercise": []
  }
}

422Sai quy tắc dữ liệu request

Thiếu trường bắt buộc, sai kiểu dữ liệu, hoặc error_code không hợp lệ cho task/criterion.

{
  "detail": [
    {
      "loc": [
        "body",
        "criterion"
      ],
      "msg": "Value error, Invalid criterion for task 1",
      "type": "value_error"
    }
  ]
}

404Không đủ reference (chỉ sample-references)

DB chưa có đủ bài làm thật khớp điều kiện lọc.

{
  "error": "Not enough references found",
  "available": 1,
  "requested": 3
}

500Lỗi server / LLM

Lỗi hệ thống không lường trước, nạp API key LLM thất bại, hoặc mất kết nối mạng.

{
  "detail": "Failed to load LLM"
}