Study Plan — Feature Report

sequenceDiagram autonumber participant Browser participant Sanctum as auth:sanctum participant MoodleMW as moodle.active participant Req as ShowStudyPlanRequest participant Ctrl as StudyPlanController participant Svc as StudyPlanService participant Repo as StudyPlanRepository participant DB as MySQL (Moodle DB) participant Res as StudyPlanResource Browser->>Sanctum: GET /api/v1/study-plan (Bearer token) alt Token invalid Sanctum-->>Browser: 401 Unauthenticated end Sanctum->>MoodleMW: Token valid → pass user alt Account suspended / deleted MoodleMW-->>Browser: 403 Forbidden end MoodleMW->>Req: Account active → resolve FormRequest Req->>Req: authorize() — user != null Req->>Ctrl: toDTO() → ShowStudyPlanDTO(studentId) Ctrl->>Svc: getForStudent(dto) Svc->>Repo: findActiveSubscription(studentId) Repo->>DB: SELECT * FROM local_flexiplan_subscription
WHERE userid=? ORDER BY CASE status … DESC timestart DB-->>Repo: subscription row (or null) alt No subscription row Repo-->>Svc: throws ActiveSubscriptionNotFoundException Svc-->>Ctrl: exception caught Ctrl-->>Browser: 404 { code: 5002 } end Repo-->>Svc: MoodleFlexiPlanSubscription Svc->>Repo: getSubscriptionCourses(subscriptionId) Repo->>DB: SELECT subs_lines + course
WHERE subscriptionid=? AND status=1 AND courseid IS NOT NULL DB-->>Repo: rows eager-loaded with courses Repo-->>Svc: Collection[MoodleFlexiPlanSubsLine] Svc->>Svc: resolvePlan(subscription) Svc->>Repo: findStudentPlan(subscriptionId) Repo->>DB: SELECT * FROM local_studyplans WHERE subscriptionid=? DB-->>Repo: plan row or null alt Student plan found Repo-->>Svc: MoodleStudyPlan [isDefault=false] else No student plan Svc->>Svc: adjustTimestamp(timestart)
[Jan 15 rule: month < 6] Svc->>Repo: findDefaultPlan(adjustedTs) Repo->>DB: SELECT * FROM local_studyplans
WHERE subscriptionid=0 AND timestart > ?
ORDER BY timestart LIMIT 1 DB-->>Repo: default plan or null alt No default plan Repo-->>Svc: null Svc-->>Ctrl: throws StudyPlanNotFoundException Ctrl-->>Browser: 404 { code: 5001 } end Repo-->>Svc: MoodleStudyPlan [isDefault=true] end Svc->>Repo: getPlanSemesters(planId) Repo->>DB: SELECT * FROM local_studyplan_semesters
WHERE studyplanid=? ORDER BY semester ASC DB-->>Repo: semester rows Repo-->>Svc: Collection[MoodleStudyPlanSemester] loop For each semester × enrolled course Svc->>Repo: getSectionForSemester(courseId, semesterNum) Repo->>DB: SELECT * FROM course_sections
WHERE course=? AND section=? DB-->>Repo: MoodleCourseSection (or null) Svc->>Repo: getModulesByIds(parsedIds from sequence) Repo->>DB: SELECT cm.* FROM course_modules
WHERE id IN (?)
AND completion != 0
AND deletioninprogress = 0
AND module.name NOT IN ('attendance','label')
WITH moduleType, assign, quiz, page, url DB-->>Repo: Collection[MoodleCourseModule] Repo-->>Svc: modules end Svc->>Repo: getCompletionStates(studentId, allModuleIds[]) Repo->>DB: SELECT * FROM course_modules_completion
WHERE userid=? AND coursemoduleid IN (?) DB-->>Repo: completion rows Repo-->>Svc: Collection keyed by coursemoduleid Svc->>Svc: buildResponse()
separateModules → chunkIntoWeeks → formatWeeks
countCompleted → progressRate → calculateTeacherPct Svc-->>Ctrl: array[id, is_default, semesters[...]] Ctrl->>Res: new StudyPlanResource(planArray) Res->>Res: formatTimestamp — Unix → ISO 8601 (Carbon) Res-->>Browser: 200 { success, message, data: { id, is_default, semesters… } }

flowchart TD A([GET /api/v1/study-plan]) --> B{auth:sanctum} B -- invalid token --> E401([401 Unauthenticated]) B -- valid --> C{moodle.active} C -- suspended/deleted --> E403([403 Forbidden]) C -- active --> D[ShowStudyPlanRequest\nauthorize + toDTO] D --> F[StudyPlanService\ngetForStudent] F --> G[findActiveSubscription\nstudentId] G -- no row --> EN1([404 · code 5002\nNo active subscription]) G -- found --> H[getSubscriptionCourses\nsubscriptionId] H --> I{findStudentPlan\nsubscription.id} I -- student plan exists --> J["resolvePlan → [plan, isDefault=false]"] I -- no student plan --> K[adjustTimestamp\nmonth < 6 → Jan 15 of year\nelse unchanged] K --> L{findDefaultPlan\ntimestart > adjusted} L -- not found --> EN2([404 · code 5001\nNo study plan found]) L -- found --> M["resolvePlan → [plan, isDefault=true]"] J --> N[loadDefaultSemesters\nfor teacher_pct] M --> O[skip defaultSemesters\nteacher_pct = null] N --> P[getPlanSemesters\nORDER BY semester ASC] O --> P P --> Q[collectModules\nfor each semester × course pair] Q --> R[getSectionForSemester\nparse sequence column as IDs] R -- no section or empty sequence --> S1[empty modules for this pair] R -- sequence found --> T[getModulesByIds\nfilter: completion≠0\ndeletioninprogress=0\ntype NOT IN attendance,label] T --> U[getCompletionStates\nbatch query keyed by coursemoduleid] S1 --> V[buildResponse] U --> V V --> W{semester.weeks > 6?\nlong semester} W -- yes --> X[separateModules\nextract Revision + Final Exam] W -- no --> Y[all modules → main chunks\nstudyWeeks = weeks] X --> Z[chunkIntoWeeks\nperWeek = ceil total / studyWeeks\nstudyWeeks = weeks − 2\nappend revision week\nappend exam week] Y --> ZA[chunkIntoWeeks\nperWeek = ceil total / weeks] Z --> AA[formatWeeks\nis_completed per module] ZA --> AA AA --> BB[countCompleted\nexclude modules named Revision] BB --> CC[progressRate\nclamp 0–1.0 time-based rate] CC --> DD{isDefault?} DD -- yes --> EE[teacher_pct = null] DD -- no --> FF[calculateTeacherPct\nusing defaultSemester timing] EE --> GG[StudyPlanResource\nformatTimestamp → ISO 8601] FF --> GG GG --> OK([200 OK\n{ success, message, data }]) style E401 fill:#7f1d1d,stroke:#ef4444,color:#fecaca style E403 fill:#7f1d1d,stroke:#ef4444,color:#fecaca style EN1 fill:#7f1d1d,stroke:#ef4444,color:#fecaca style EN2 fill:#7f1d1d,stroke:#ef4444,color:#fecaca style OK fill:#064e3b,stroke:#10b981,color:#a7f3d0 style A fill:#1e1b4b,stroke:#818cf8,color:#c7d2fe