I05 — Lesson Logic (Read/Nav)

sequenceDiagram autonumber participant B as Browser participant MW as Middleware
(auth:sanctum
moodle.active) participant C as LessonController participant FR as FormRequest participant SVC as LessonService /
LessonNavService participant REPO as Repositories participant DB as Moodle DB
(shared MySQL) participant EV as Event Bus participant Q as Queue
(ForwardToMoodle) Note over B,Q: GET /courses/{cId}/lessons/{lId} — Show Lesson B->>MW: GET /lessons/{lessonId} MW->>MW: Verify Sanctum token + moodle.active MW->>C: show(ShowLessonRequest, courseId, lessonId) C->>FR: authorize() — user authenticated? FR-->>C: ShowLessonDTO{courseId, lessonId, studentId} C->>SVC: LessonService::show(dto) SVC->>REPO: LessonRepository::findForStudent(dto) REPO->>DB: SELECT lesson JOIN course_modules JOIN user_enrolments WHERE active DB-->>REPO: MoodleLesson | null REPO-->>SVC: MoodleLesson (or throws LessonNotEnrolledException) SVC->>REPO: LessonRepository::findResumePageForStudent(lessonId, userId) REPO->>DB: SELECT MAX(timeseen) from lesson_attempts + lesson_branch for current retry DB-->>REPO: ?resumePageId SVC->>REPO: LessonTimerRepository::startIfNotRunning(lessonId, userId, retry) REPO->>DB: SELECT id FROM lesson_timer WHERE lessonid+userid+retry alt Timer does not exist AND timelimit/completiontimespent > 0 DB-->>REPO: no row REPO->>DB: INSERT lesson_timer (starttime=now, lessontime=0) DB-->>REPO: MoodleLessonTimer (fresh) REPO-->>SVC: timer SVC->>EV: Event::dispatch(LessonStarted{userId, courseId, lessonId, cmId}) EV->>Q: ForwardEventToMoodle (queued async) else Timer already exists DB-->>REPO: existing row REPO-->>SVC: null (no-op) end SVC-->>C: array{lesson, resumePageId, timerStartedAt, currentRetry} C-->>B: 200 JSON — LessonResource with student state Note over B,Q: GET /courses/{cId}/lessons/{lId}/pages — List Pages B->>C: pages(ListLessonPagesRequest, courseId, lessonId) C->>FR: toDTO() → ListLessonPagesDTO C->>SVC: LessonService::listPages(dto) SVC->>REPO: LessonRepository::findForStudent(dto) REPO->>DB: enrollment check DB-->>REPO: MoodleLesson SVC->>REPO: LessonPageRepository::listOrdered(lessonId) REPO->>DB: SELECT * FROM lesson_pages WHERE lessonid ORDER by linked-list walk DB-->>REPO: Collection of MoodleLessonPage (with answers eager-loaded) SVC->>SVC: LessonNavService::buildOrderedPageList(pages) — walk prevpageid=0 chain SVC-->>C: ordered Collection C-->>B: 200 JSON — LessonPageCollectionResource (CLUSTER/END_OF_CLUSTER filtered) Note over B,Q: GET /courses/{cId}/lessons/{lId}/pages/{pId} — Show Page B->>C: page(ShowLessonPageRequest, courseId, lessonId, pageId) C->>SVC: LessonService::showPage(dto) SVC->>REPO: LessonRepository::findForStudent(dto) + LessonPageRepository::findForLesson(pageId, lessonId) REPO->>DB: SELECT lesson_pages WHERE id AND lessonid WITH answers DB-->>REPO: MoodleLessonPage | null SVC->>EV: Event::dispatch(LessonPageViewed{userId, courseId, lessonId, pageId, cmId, pageTypeLabel}) EV->>Q: ForwardEventToMoodle (queued async) SVC-->>C: MoodleLessonPage C-->>B: 200 JSON — LessonPageResource (grade/score/response hidden for question pages) Note over B,Q: POST /courses/{cId}/lessons/{lId}/pages/{pId}/navigate — Navigate B->>C: navigate(NavigateLessonPageRequest, courseId, lessonId, pageId) body={answer_id} C->>FR: rules() — answer_id required, integer, exists lesson_answers WHERE pageid=pageId FR-->>C: NavigateLessonPageDTO{courseId, lessonId, pageId, answerId, studentId} C->>SVC: LessonNavService::navigate(dto) SVC->>REPO: LessonRepository::findForStudent(dto) REPO->>DB: enrollment check SVC->>REPO: LessonPageRepository::findForLesson(pageId, lessonId) DB-->>REPO: MoodleLessonPage SVC->>SVC: resolveJumpto(answer, page) — pure algorithm, no DB Note right of SVC: jumpto=0 → page.nextpageid
jumpto=-1 → end of lesson
jumpto>0 → specific page ID alt Page is BRANCH_TABLE (qtype=20) SVC->>REPO: LessonBranchRepository::track(lessonId, userId, pageId, nextPageId, retry) REPO->>DB: UPSERT lesson_branch (timeseen=now, nextpageid) DB-->>REPO: MoodleLessonBranch SVC->>EV: Event::dispatch(LessonBranchVisited{userId, courseId, lessonId, pageId, cmId, nextPageId}) EV->>Q: ForwardEventToMoodle (queued async) end SVC-->>C: NavigationResult{nextPageId, isEndOfLesson} C-->>B: 200 JSON — NavigationResultResource{next_page_id, is_end_of_lesson, feedback:null} Note over Q: All queued listeners run async — do NOT block HTTP response

flowchart TD A([POST /navigate
answer_id in body]) --> B{auth:sanctum
token valid?} B -- No --> B1[401 Unauthenticated]:::err B -- Yes --> C[NavigateLessonPageRequest
validate answer_id] C --> D{answer_id present
and integer?} D -- No --> D1[422 Validation Error
answer_id required]:::err D -- Yes --> E{answer exists in
lesson_answers WHERE
pageid = pageId?} E -- No --> E1[422 Validation Error
answer does not belong to page]:::err E -- Yes --> F[LessonNavService::navigate] F --> G[LessonRepository
findForStudent] G --> H{Lesson found AND
student enrolled
in course?} H -- No --> H1[404 LessonNotFoundException
code 3005]:::err H -- Yes --> I[LessonPageRepository
findForLesson pageId+lessonId] I --> J{Page belongs
to lesson?} J -- No --> J1[404 LessonPageNotFoundException
code 3007]:::err J -- Yes --> K[resolveJumpto
pure algorithm] K --> L{jumpto value?} L -- "jumpto = 0" --> M[next_page_id =
page.nextpageid] M --> N{nextpageid = 0?} N -- Yes --> O[is_end_of_lesson = true
next_page_id = null]:::eol N -- No --> P[is_end_of_lesson = false
next_page_id = nextpageid]:::ok L -- "jumpto = -1" --> O L -- "jumpto > 0" --> Q2[next_page_id = jumpto
specific page ID]:::ok O --> R{Page type
= BRANCH_TABLE
qtype 20?} P --> R Q2 --> R R -- Yes --> S[LessonBranchRepository
track — UPSERT lesson_branch] S --> T[Event::dispatch
LessonBranchVisited
queued async] T --> U[NavigationResultResource
next_page_id, is_end_of_lesson
feedback=null] R -- No --> U U --> V([200 OK JSON Response]):::success classDef err fill:#3b0f0f,stroke:#ef4444,color:#fca5a5 classDef success fill:#052e16,stroke:#10b981,color:#86efac classDef eol fill:#1c1917,stroke:#f59e0b,color:#fcd34d classDef ok fill:#0c1a3b,stroke:#60a5fa,color:#93c5fd