DraftDT-4662Exercise AISRDSpeakingAIEngineeringstudy-hub

Exercise AI — SRD (Overview)

SRD kỹ thuật cho runtime làm bài (do-test) của nhóm Exercise AI, hiện thực trong app study-hub (features/exercise_ai). Phần ý đồ sản phẩm nằm ở các PRD: Type 1 — Speak a Sentence, Linear Note — Student, Linear Tool — Technical Proposal.

Phạm vi

Tài liệu này mô tả luồng học viên làm bài (do-test): khởi tạo progress, làm từng câu, chấm phát âm, nộp bài; cùng API soạn nội dung (data-entry) ở mức hợp đồng REST + aggregate AiExercise. Chi tiết shape nội dung theo từng dạng bài (authoring content) là phần TBD — tham chiếu PRD Type 1 và Linear Note.

Các dạng bài (`AiExerciseType`)

Enum	Tên	Mô tả ngắn
`SPEAK_A_SENTENCE`	Nói một câu	Học viên nói từng câu rời, AI chấm theo lượt (turn-based).
`IMPROVE_A_SENTENCE`	Cải thiện câu nói	Biến thể turn-based: cải thiện câu đã nói.
`LINEAR_TOOL`	Công cụ tuyến tính	Dựng sơ đồ ý phân nhánh trên canvas, AI sinh câu, luyện nói cả bài.
`GUIDED_PRACTICE`	Luyện tập có hướng dẫn	Placeholder — shape chưa chốt (TBD).

exerciseType là discriminator ở mức progress/content: một progress chỉ chứa một dạng bài, quyết định subtype của content và questions.

Kiến trúc hệ thống

App: study-hub (Java 25 + Spring Boot, MongoDB, không Spring Security — JWT).
CQRS-lite: controller → *ServiceCommand / *ServiceQuery (interface) → handler. Command tách khỏi query.
Persistence: MongoDB schema-on-write (không migration tool). Progress là một document AiUserExerciseProgress (@Document), content và questions lưu đa hình (polymorphic embedded).
Đa hình: content và question đều theo cây kế thừa, dispatch qua MapperFactory + CanHandleMapping (reflection theo runtime type) — không dùng switch. Mỗi subtype có entity + DTO + mapper riêng.
Chấm AI (Restate): chấm phát âm/turn chạy bất đồng bộ; kết quả trả về qua webhook callback server-to-server (POST /exercise-ai/dotest/marking/callback), cập nhật turn theo turnId.

Glossary

Progress — một phiên làm bài của học viên (AiUserExerciseProgress). Trạng thái IN_PROGRESS → COMPLETED.
Content — payload theo dạng bài, gắn trong progress (BaseAiExerciseProgressContent).
Question (progress) — tiến độ của một câu trong bài (BaseAIExerciseQuestionProgress).
Turn — một lượt nói/được-chấm trong dạng turn-based (AnswerTurn).
Canvas / Card — sơ đồ ý của LINEAR_TOOL (LinearCanvas / LinearCard).
Verdict — kết quả chấm phát âm (SpeechVerdict: GOOD / NEED_IMPROVE).

Đọc tiếp

Domain Model & State — entity, enum, state machine.
Data Entry API — hợp đồng REST soạn nội dung + aggregate AiExercise.
Do-Test API — hợp đồng REST runtime làm bài.
Resource Integration — gắn bài vào khóa học qua course-supporter (ResourceInfo, tracking progress).
Linear Tool — canvas, luật sơ đồ, chấm điểm, tổng kết submit.

Overview Domain Model & State