Exercise AI — Do-Test API

Hợp đồng REST của runtime làm bài. Base path: /api/v1/exercise-ai.

Trang này gom quy ước chung + các Common API (dùng cho mọi dạng bài). Phần endpoint riêng theo dạng tách ra từng trang để dễ update độc lập:

Quy ước

• progressId luôn là path variable cho mọi endpoint mutate progress đang tồn tại — không nằm trong body. Pattern: {HTTP} /{progressId}/<action>.
• Verb: POST cho hành động tạo/chuyển trạng thái; PATCH cho cập nhật một phần câu/canvas.
• Lỗi nghiệp vụ ném BusinessLogicException (mã AiExerciseDoTestErrorCode); global handler render envelope.
• Mọi mutation bị chặn khi progress đã COMPLETED (PROGRESS_ALREADY_COMPLETED).
• Auth JWT (học viên/guest); riêng nhóm marking/* là server-to-server (không validator).

Common API — mọi dạng bài

Command (mutate)

Query (read)

GET /turn/{turnId} là query nhưng chỉ dùng cho dạng turn-based → xem Turn-based.

Ví dụ — Common API

POST /dotest/start

// Request
{
  "userResourceId": "665f0a2b3c4d5e6f7a8b9c0d",
  "force": false,
  "teacherLanguageType": "VIETNAMESE"   // optional, default VIETNAMESE
}

// Response 200 — DocumentIdOnly
{ "id": "6700a1b2c3d4e5f60718293a" }

POST /dotest/demo-start

// Request
{
  "resourceId": "665fae11b2c3d4e5f6071827",   // id AiExercise đã publish
  "subClassKey": null,                          // optional — tự sinh "demo-<uuid>"
  "studentRegistrationKey": null,               // optional — tự sinh "demo-<uuid>"
  "teacherLanguageType": "ENGLISH"
}

// Response 200 — DocumentIdOnly
{ "id": "6700a1b2c3d4e5f60718293b" }

PATCH /progress/{progressId}/skip

// Request
{ "questionId": "665fae11b2c3d4e5f6071900" }

// Response 200 — DoTestStateDTO
{
  "progressId": "6700a1b2c3d4e5f60718293a",
  "status": "IN_PROGRESS",
  "teacherLanguageType": "VIETNAMESE",
  "currentIndex": 2,
  "currentQuestionId": "665fae11b2c3d4e5f6071901",
  "totalQuestion": 10,
  "totalAnswered": 0,
  "totalSkipped": 0,
  "totalNotAnswer": 0,
  "averageCorrectPercentage": 0.0,
  "questions": []
}

POST /progress/{progressId}/next

// Request — không có body

// Response 200 — DoTestStateDTO (xem cấu trúc ở skip)
{
  "progressId": "6700a1b2c3d4e5f60718293a",
  "status": "IN_PROGRESS",
  "currentIndex": 3,
  "currentQuestionId": "665fae11b2c3d4e5f6071902",
  "totalQuestion": 10
}

POST /progress/{progressId}/submit

// Request — SubmitQuestionRequestDTO
{ "spendTimeInSeconds": 540 }

// Response 200 — DocumentIdOnly (FE reload state qua GET /{progressId})
{ "id": "6700a1b2c3d4e5f60718293a" }

GET /progress/{progressId}

Trả AiUserExerciseProgressDTO. Khung chung (phần content đa hình theo dạng — xem trang từng type):

{
  "id": "6700a1b2c3d4e5f60718293a",
  "userResourceId": "665f0a2b3c4d5e6f7a8b9c0d",
  "exerciseId": "665fae11b2c3d4e5f6071827",
  "exerciseType": "SPEAK_A_SENTENCE",
  "teacherLanguageType": "VIETNAMESE",
  "startMode": "REAL_TEST",
  "status": "IN_PROGRESS",
  "currentIndex": 0,
  "totalQuestion": 10,
  "content": { /* polymorphic — xem trang từng dạng */ },
  "createdBy": { "id": "u_123", "fullName": "Nguyễn Văn A" },
  "createdAt": "2026-06-30T10:00:00+07:00"
}

Shared shapes — ý nghĩa field

Request DTOs (Common)

StartDoTestRequestDTO

DemoStartAiExerciseRequestDTO

SkipQuestionRequestDTO: questionId (String, ✅) — câu cần bỏ qua. SubmitQuestionRequestDTO: spendTimeInSeconds (long) — thời gian làm bài (từ BaseCommonProgressRequestDTO). DocumentIdOnly: id (String) — id progress vừa tạo/nộp; FE reload state qua GET /{progressId}.

Các request DTO mutate một câu/canvas kế thừa BaseCommonProgressRequestDTO → luôn có thêm spendTimeInSeconds (long, giây tiêu tốn cho hành động đó).

AiUserExerciseProgressDTO (response GET /{progressId}, /canvas, /speech-correction)

DoTestStateDTO (response next / skip)

total* / averageCorrectPercentage hiện chỉ fill đầy đủ cho LINEAR_TOOL (từ LinearProgressContent); dạng khác = 0 cho tới khi có tổng kết riêng.

BaseQuestionProgressDTO (base mọi câu)

Subtype (field riêng theo dạng): Turn-based thêm attemptsLeft, turns[]; Linear thêm snapshots[], currentSnapshotId, totalDoCoachingMenu, totalDoCoachingLive; Guided không thêm gì (scaffolded). Content-DTO: LinearProgressContentDTO thêm totalAnswered/Skipped/NotAnswer/averageCorrectPercentage; Turn/Guided chỉ có questions[].

Enum tham chiếu (shared)

Error codes (AiExerciseDoTestErrorCode)

Đọc tiếp

• Domain Model & State — entity, enum, state machine.
• Turn-based · Linear Tool · Guided.