DraftDT-4662Exercise AISRDIntegrationcourse-supporterstudy-hubLMS

Exercise AI — Resource Integration (Course Supporter)

Cách một bài Exercise AI được gắn vào khóa học (LMS) và cách tiến độ làm bài nổi lên phía course. Cầu nối giữa runtime do-test (features/exercise_ai) và lib course-supporter, đi qua điểm dispatch chung StudyHubResourceCommonHelper (features/shared).

Mô hình provider

course-supporter inject một bean cho mỗi provider interface trong mỗi app — không phải registry theo type. Vì study-hub phục vụ nhiều loại tài nguyên nên mỗi provider tự dispatch nội bộ theo StudyHubResourceType. Đây là điểm khác biệt với K12/G12 (mỗi app một loại, provider hardcode mainResourceType).

StudyHubResourceType: KID_EXERCISE, KID_VOCAB, AI_EXERCISE.

Provider (`course-supporter`)	Impl (`study-hub/providers`)	Vai trò	AI_EXERCISE
`ResourceInfoProvider`	`ResourceInfoProviderImpl`	Metadata bài khi gắn vào syllabus	✅ hỗ trợ
`CourseSupporterProvider`	`CourseSupporterProviderImpl`	Vòng đời resource cho template SYLLABUS (tracking progress…)	✅ hỗ trợ
`RoadmapCourseSupporterProvider`	`RoadmapCourseSupporterProviderImpl`	Resource cá nhân hóa ROADMAP	Stub — study-hub chỉ chạy SYLLABUS
`ExtraCourseSupporterProvider`	(không có)	Resource extra / ad-hoc	Vắng chủ đích → `GenerateExtraResourceImpl` tắt qua `@ConditionalOnBean`

mainResourceType() = "STUDY_HUB"; isSupportResourceType(type) = type thuộc StudyHubResourceType.

Resource info (gắn bài vào khóa học)

ResourceInfoProvider.findTestInformation(resourceIds, "AI_EXERCISE") trả về Map<resourceId, ResourceInfo>. Nguồn dữ liệu: AiExerciseVersionHelper.fetchLatestByExerciseIds (bản published mới nhất) rồi AiExerciseMapper.toResourceInfo.

ResourceInfo: name, displayId, level, skill, program, resourceType, totalQuestion, mainResourceType.

Tracking progress

CourseSupporterProvider.trackingProgress(userResourceId, "AI_EXERCISE") trả ResourceProgressDto, ủy quyền về StudyHubResourceCommonHelper.trackingProgress.

Logic nhánh AI_EXERCISE:

Lấy AiUserExerciseProgress mới nhất theo userResourceId (sort createdAt desc) — predicate AiUserExerciseProgressPredicateBuilder.byUserResourceId.
Không có progress → null.
COMPLETED → ResourceProgressDto chỉ set latestProgressId. Scoring chưa implement — numberCorrectQuestion / currentScore bỏ trống, khớp isNeedTrackingCorrectAnswer() == false của study-hub.
IN_PROGRESS → numberInProgressQuestion = số câu có state == ANSWERED (đếm trên getQuestions()).

ResourceProgressDto: numberCorrectQuestion, numberInCorrectQuestion, numberInProgressQuestion, currentScore, latestProgressId. State machine của status / QuestionState: xem Domain Model & State.

Learning management API (course student / teacher)

Query endpoints course-facing cho AI_EXERCISE, mirror kid/exercise. Đọc qua *ServiceQuery interface; DTO tái dùng của course-supporter (CourseUserAiExerciseDTO extends CourseUserResourceResponseDto). Base path /api/v1 (ProjectConst.BASE_URL).

Student — base `/exercise-ai/learning-management`

Method + path	Query params	Trả về
`GET /course/{subClassKey}/student/{studentRegistrationKey}/paged`	`search?`, `status?` (`DoTestStatus`), `resourceType?`, `pageable` (mặc định sort `courseResourceKey.syllabusOrder` ASC)	`Page<CourseUserAiExerciseDTO>`
`GET /course/{subClassKey}/student/{studentRegistrationKey}/statistic`	`studyTemplate` (mặc định `SYLLABUS`)	`StudentCourseResourceStatisticDTO`
`GET /student/{studentRegistrationKey}/statistic`	`studyTemplate` (mặc định `SYLLABUS`)	`StudentCourseResourceStatisticDTO`
`GET /course/{subClassKey}/student/{studentRegistrationKey}/resource`	`studyTemplate` (mặc định `SYLLABUS`)	`List<CourseUserAiExerciseDTO>`

Teacher — base `/exercise-ai/course`

Method + path	Query params	Trả về
`GET /{subClassKey}/statistic`	`search?`, `week?`, `subWeek?`, `resourceType?`, `studyTemplate` (mặc định `SYLLABUS`), `pageable`	`Page<CourseResourceResponseDto>`
`GET /{courseResourceId}/overview`	—	`CourseResourceOverviewResponseDto`

StudentCourseResourceStatisticDTO, CourseResourceResponseDto, CourseResourceOverviewResponseDto đều thuộc course-supporter — thống kê/tổng quan tài nguyên khóa học dùng chung với kid/exercise.

Giới hạn hiện tại

Scoring khi COMPLETED chưa có — bổ sung numberCorrectQuestion / currentScore khi AI marking tổng bài hoàn thiện.
ROADMAP / Extra chỉ bật khi Exercise AI phát dạng roadmap/extra resource (hiện SYLLABUS-only).
KID_VOCAB vẫn TODO trong cùng dispatcher StudyHubResourceCommonHelper.

Guided Practice Linear Tool