Yimaru/Yimaru-BackEnd
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
4adbfbbeaa
Yimaru-BackEnd/docs/LEARNING_TREE_DRAG_DROP_INTEGRATION.md

8.2 KiB
Raw Blame History

Learning Tree + Sequential Access Integration (Admin Panel)

Complete backend-compatible documentation for the changes implemented today:

  • flexible drag-and-drop reorder for learning tree entities
  • sub-course level/sub-level model
  • sub-course entry assessment model
  • learner sequential unlock rules for videos and practices

1) What Changed Today

1.1 Reorder + Route/RBAC hardening

  • Reorder endpoints are active and route-safe (static /reorder routes registered before dynamic /:id routes).
  • Reorder permissions are now seeded in RBAC and included in default ADMIN permissions:
    • course_categories.reorder
    • courses.reorder
    • subcourses.reorder
    • videos.reorder
    • practices.reorder

1.2 Sub-course academic structure

  • Added sub_courses.sub_level with enforced mapping:
    • BEGINNER -> A1, A2, A3
    • INTERMEDIATE -> B1, B2, B3
    • ADVANCED -> C1, C2, C3

1.3 Entry assessment per sub-course

  • Each sub-course has its own INITIAL_ASSESSMENT question set (owner_type=SUB_COURSE).
  • Backfill creates missing sets for existing sub-courses.
  • Trigger auto-creates entry assessment for newly created sub-courses.
  • Existing default standalone initial-assessment questions are cloned into sub-course entry sets when empty.

1.4 Learner sequential unlock (videos + practices)

  • Videos: learner cannot access higher display_order videos before completing earlier ones.
  • Practices: learner cannot access higher display_order practices before completing earlier ones.
  • Completion is tracked per learner using dedicated progress tables.

2) Migrations Added

Apply in order:

  1. 000024_subcourse_entry_assessment_and_sub_levels
  2. 000025_video_sequence_progress
  3. 000026_practice_sequence_progress

2.1 000024_subcourse_entry_assessment_and_sub_levels

  • adds sub_courses.sub_level
  • adds level/sub-level check constraint
  • adds idx_sub_courses_level_sub_level
  • enforces one active sub-course entry assessment set (unique index on question_sets)
  • backfills missing sub-course entry assessment sets
  • adds trigger for automatic entry assessment creation

2.2 000025_video_sequence_progress

  • creates user_sub_course_video_progress
  • tracks learner completion by user_id + video_id

2.3 000026_practice_sequence_progress

  • creates user_practice_progress
  • tracks learner completion by user_id + question_set_id (practice set)

3) Required Permissions

3.1 Admin panel (read + reorder + content management)

  • learning_tree.get
  • course_categories.reorder
  • courses.reorder
  • subcourses.reorder
  • videos.reorder
  • practices.reorder
  • question_sets.list_by_owner (entry-assessment fetch by sub-course)

3.2 Learner runtime (sequential flow)

  • videos.get
  • progress.update (for completion endpoints)
  • question_sets.get
  • question_set_items.list

4) Reorder APIs (Admin)

All reorder APIs expect:

{
  "items": [
    { "id": 12, "position": 0 },
    { "id": 7, "position": 1 }
  ]
}
  • id: entity ID
  • position: target 0-based display_order
  • send the full sibling list in the target order
Method Endpoint Effect
PUT /api/v1/course-management/categories/reorder updates course_categories.display_order
PUT /api/v1/course-management/courses/reorder updates courses.display_order
PUT /api/v1/course-management/sub-courses/reorder updates sub_courses.display_order
PUT /api/v1/course-management/videos/reorder updates sub_course_videos.display_order
PUT /api/v1/course-management/practices/reorder updates question_sets.display_order (practice sets)

Common 400 causes:

  • invalid body shape
  • empty items

5) Data Fetch APIs for Admin UI

Method Endpoint Purpose
GET /api/v1/course-management/learning-tree high-level tree
GET /api/v1/course-management/courses/{courseId}/learning-path detailed nested structure
GET /api/v1/question-sets/by-owner?owner_type=SUB_COURSE&owner_id={subCourseId} sets under a sub-course
GET /api/v1/question-sets/sub-courses/{subCourseId}/entry-assessment entry assessment set for sub-course

6) Sub-course Create/Update Contract (Admin)

6.1 Create sub-course

POST /api/v1/course-management/sub-courses

Required fields now include:

  • course_id
  • title
  • level (BEGINNER|INTERMEDIATE|ADVANCED)
  • sub_level (A1..C3 mapped by level)

Example:

{
  "course_id": 1,
  "title": "Speaking Foundations",
  "level": "BEGINNER",
  "sub_level": "A2",
  "display_order": 1
}

6.2 Update sub-course

PATCH /api/v1/course-management/sub-courses/{id}

If level or sub_level is changed, backend validates the pair.

7) Entry Assessment Model (Sub-course)

Each sub-course has one entry assessment set:

  • set_type = INITIAL_ASSESSMENT
  • owner_type = SUB_COURSE
  • owner_id = {subCourseId}

Behavior

  • created automatically for new sub-courses
  • backfilled for existing sub-courses
  • intended to evaluate learner before joining/starting that sub-course

8) Learner Sequential Unlock Rules (Runtime, Not Admin Panel)

8.1 Videos

Access endpoint:

  • GET /api/v1/course-management/videos/{id}

Completion endpoint:

  • POST /api/v1/progress/videos/{id}/complete

Rule:

  • learner must complete all previous published videos in same sub-course by display_order (and id tie-breaker)

8.2 Practices

Access endpoints:

  • GET /api/v1/question-sets/{id} (for practice set)
  • GET /api/v1/question-sets/{setId}/questions

Completion endpoint:

  • POST /api/v1/progress/practices/{id}/complete

Rule:

  • applies to sets with:
    • set_type = PRACTICE
    • owner_type = SUB_COURSE
    • status = PUBLISHED
  • learner must complete all previous published practices in same sub-course by display_order (and id tie-breaker)

8.3 Role scope

  • Sequence enforcement currently applies to STUDENT role.
  • Admin/instructor/support are not sequence-blocked.
  • Admin panel does not need to call completion endpoints.

9) Mid-Progress Reorder Behavior

Current behavior (by design):

  • Access checks always use the latest display_order in DB.
  • If admin reorders while learner is in progress, next unlock path updates immediately.
  • Completion records are by entity ID, so already completed items remain completed.

Implication:

  • learner may be asked to complete a newly moved earlier item before continuing.

10) Recommended Frontend Integration Flow

10.1 Admin panel

  1. Load learning path/tree.
  2. Render sortable lists per sibling scope.
  3. On drop:
    • optimistic reorder in UI
    • call matching reorder endpoint with full sibling list
  4. Handle 400/401/403/500 and rollback on failure.

11) Quick API Examples

Reorder videos

curl -X PUT "http://localhost:8080/api/v1/course-management/videos/reorder" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"items":[{"id":45,"position":0},{"id":42,"position":1},{"id":50,"position":2}]}'

Reorder practices

curl -X PUT "http://localhost:8080/api/v1/course-management/practices/reorder" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"items":[{"id":88,"position":0},{"id":91,"position":1},{"id":95,"position":2}]}'

Get sub-course entry assessment

curl -X GET "http://localhost:8080/api/v1/question-sets/sub-courses/10/entry-assessment" \
  -H "Authorization: Bearer <TOKEN>"

Runtime-only completion endpoints (learner app, optional reference)

POST /api/v1/progress/videos/{id}/complete
POST /api/v1/progress/practices/{id}/complete

12) Validation and Testing Checklist

  • Run migrations 000024, 000025, 000026
  • Sync RBAC permissions and ensure admin role contains reorder keys
  • Create/update sub-course with valid level + sub_level
  • Verify auto-created entry assessment for new sub-course
  • Reorder categories/courses/sub-courses/videos/practices and confirm persistence
  • Learner cannot access video N+1 before completing N
  • Learner cannot access practice N+1 before completing N
  • Reorder during learner progress and confirm latest-order behavior