Lấy dữ liệu tham chiếu

Lấy ngẫu nhiên các bài làm thật có đúng mã lỗi cần luyện, dùng làm ngữ cảnh cho bước sinh bài tập.

Request

Field	Type	Bắt buộc	Mô tả
writing_task	int	BẮT BUỘC	1 hoặc 2
criterion	string	BẮT BUỘC	task_achievement \| task_response \| coherence_cohesion \| lexical_resource \| grammatical_range_accuracy
error_code	string	BẮT BUỘC	Một trong 28 mã lỗi thuộc criterion đã chọn
topic	string	BẮT BUỘC	environment \| technology \| education
num_references	int	tuỳ chọn	1–5, mặc định 3

Response

Object tương thích với InputMicroExercise, dùng làm input cho create-micro-exercise.

Lưu ý

criterion trong response là display name ("Lexical Resource"), không phải enum — phải map ngược trước khi gọi create-micro-exercise.
Tài liệu ghi criterion enum là "grammatical_range_accuracy", trong khi create-micro-exercise dùng "grammar_range_accuracy" — hai tài liệu chưa thống nhất cách viết.
Không có base URL công khai — đây là endpoint nội bộ, chưa tài liệu hoá cơ chế xác thực.

curl -X POST 'https://test-api-ielts-writing.aihubproduction.com/external/micro-exercise/sample-references' \
  -H 'Content-Type: application/json' \
  -d '{
  "writing_task": 2,
  "criterion": "lexical_resource",
  "error_code": "collocation_error",
  "topic": "environment",
  "num_references": 3
}'

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"
}