EduTrack API Changelog

Last Updated: August 12, 2026

This document tracks all changes made to the API, organized by feature area.

Verified-Student Gating + Enrollment Block/Unblock + Reopen Fix + Quiz Caps (Aug 12, 2026)

1. Non-verified students can no longer enroll, buy, or be approved

• POST /courses/enrollments/enroll/ → 403 "Your account is pending approval. You cannot enroll until an administrator verifies your account." when the student's status ≠ verified.
• POST /courses/purchases/buy/ → 403 "Your account must be verified before purchasing lectures." when not verified.
• POST /courses/enrollments/approve/ (and reject→approve re-approval) skips enrollments whose student isn't verified: the row is reported in errors[] with "Student account is not verified yet." and stays pending.

2. Block / unblock approved students per course (with audit trail)

New Enrollment fields: is_blocked, block_reason, blocked_by, blocked_at, unblocked_by, unblocked_at (migration courses/0021).

Access gating while blocked (403 with {error, blocked: true, reason}):

• GET /courses/videos/<id>/play/ (student branch)
• POST /courses/purchases/buy/
• GET /courses/<id>/lectures/ (student enrolled-course view)
• GET /courses/my-lectures/ — blocked-course lectures are excluded from the list

EnrollmentSerializer now returns is_blocked, block_reason, blocked_by_name, blocked_at, unblocked_by_name, unblocked_at.

3. Re-approve rejected enrollments

POST /courses/enrollments/approve/ now accepts enrollments with status pending OR rejected (previously pending-only). reject/ still only touches pending requests. This lets teachers approve a student who was previously rejected (e.g. after fixing a data issue).

4. Reopen semantics fixed (expired lectures)

PATCH /courses/purchases/<pk>/reopen/ previously added extra_days += 1 to the frozen original expiry — reopening a lecture expired 10 days ago still left it expired. Now:

• expires_at = max(effective_expiry, now) + 1 day, and extra_days = 0.
• Reopening an expired lecture restores access for ~1 day from now; reopening an active purchase extends it by 1 day from the current expiry.
• LectureReopenLog audit entry still written; still max 2 reopens; still resets sessions_used + deletes viewing sessions.

5. Quiz questions capped at 300

QuizCreateUpdateSerializer rejects questions payloads with more than 300 items (400, "Maximum of 300 questions allowed per quiz.") on create AND update. (Homeworks already had a 300-question cap.)

6. Small fixes

• Quiz/exam submission score now capped at 9999.99 in calculate_submission_score() — prevents a 500 when many high-point questions overflow the Decimal field.
• exams/views.py missing get_object_or_404 import fixed.
• Cut overview now allows teachers/assistants (scoped to their own teacher's data) — see below.

7. Cut overview accessible to teachers/assistants (scoped)

GET /payments/cuts/overview/ permission changed from SiteOwner-only to IsSiteOwnerOrTeacherOrAssistant. Teachers/assistants are always forced to their own teacher's data — the ?teacher= param and ?search= are ignored for them (their own row is returned regardless of the params). lectures/, invoices/, and invoice detail remain SiteOwner-only; cuts/my/ remains Teacher-only.

Files changed: courses/models.py (+0021 migration), courses/views.py, courses/serializers.py, courses/urls.py, courses/tests.py, balance/views.py, balance/tests.py, quizzes/serializers.py, exams/views.py, learning/base.py, docs.

Bunny Stream — Migration to Library 725542 (Aug 2026)

The app was built against the old Bunny status scheme, old webhook signature, and the old library (712312). This commit migrates everything to the current official scheme, verified live against the real API and the current Bunny docs.

New credentials (.env — gitignored, not committed)

backend/settings.py defaults updated to 725542 / vz-2fe271ec-aba.b-cdn.net (a missing env var can no longer silently fall back to the old library) + BUNNY_STREAM_TOKEN_AUTH_KEY added (empty default). Also added Postgres CONN_MAX_AGE=300 + CONN_HEALTH_CHECKS.

New official status scheme (0–10)

Per the current Bunny webhook/API docs: 0 Queued, 1 Processing, 2 Encoding, 3 Finished, 4 Resolution finished, 5 Failed, 6 PresignedUploadStarted, 7 PresignedUploadFinished, 8 PresignedUploadFailed, 9 CaptionsGenerated, 10 TitleOrDescriptionGenerated.

• courses/bunny.py: new constants + READY_STATUSES {3,4,9,10}, IN_PROGRESS_STATUSES {0,1,2,6,7}, FAILED_STATUSES {5,8}.
• courses/serializers.py: BUNNY_STATUS_MAP rewritten to the new display labels (Queued/Processing/Encoding/Finished/Ready/Failed/Uploading/Uploaded/UploadFailed/…).
• courses/models.py: Video.bunny_status help_text updated (cosmetic).
• Status-0 ambiguity guard: 0 now means both "created, no file" and "queued for encoding after upload". The poller and webhook never downgrade a local uploaded state (6/7) back to 0, so a just-uploaded video can't flicker to "upload needed".

Behavior changes

• _sync_bunny_status (status polling): skips terminal states; activates on 3/4/9/10, deactivates on 5/8 (was: hardcoded status == 4).
• VideoListCreateView.list: "pending to poll" filter uses IN_PROGRESS_STATUSES (no longer polls already-failed videos).
• VideoCreateUploadView: finalization/in-progress conflict checks use READY_STATUSES/IN_PROGRESS_STATUSES.
• VideoUploadCompleteView: writes 7 (PresignedUploadFinished) instead of old 1.
• Webhook (BunnyWebhookView) — rewritten to the v1 spec:
  • New: verifies X-BunnyStream-Signature-Version: v1 + X-BunnyStream-Signature-Algorithm: hmac-sha256 + X-BunnyStream-Signature = lowercase hex HMAC-SHA256 over the exact raw body using the Read-Only API key (constant-time hmac.compare_digest). This matches the current official procedure exactly.
  • Legacy X-Bunny-Signature (full API key) kept as a fallback for an old-configured library.
  • Status handling: same activate/deactivate + no-downgrade-to-0 guard.
  • Verified live: valid v1 → 200, tampered body → 403, unsigned → 403.

Embed player (playback model)

Library 725542 uses MediaCage Basic DRM → embed-only playback (direct HLS / third-party players disabled by Bunny). The student player is Bunny's embed iframe: https://player.mediadelivery.net/embed/725542/{video_id}.

• New helper courses.bunny.generate_embed_url(guid, expires_in=7200) → unsigned embed URL, or signed with ?token=SHA256_HEX(BUNNY_STREAM_TOKEN_AUTH_KEY + guid + expires)&expires= when the token key is configured (inert until the library's Embed view token authentication is enabled).
• generate_tus_credentials() unchanged — already matches the current spec.

Docs: BUNNY_STREAM_FRONTEND.md fully synced (status table, poll switch, embed playback, webhook v1, lifecycle). docs/CHANGELOG.md updated. docs/API_STUDENT.md play response note clarified.

Files changed: backend/settings.py, courses/bunny.py, courses/views.py, courses/serializers.py, courses/models.py, docs/BUNNY_STREAM_FRONTEND.md, docs/CHANGELOG.md, .env.example (token key documented).

Video Play Endpoint — Signed Embed URL (Aug 2026)

GET /courses/videos/<id>/play/ now returns the embed iframe URL in addition to the raw playlist URL:

{
  "playback_url": "…/playlist.m3u8",
  "embed_url": "https://player.mediadelivery.net/embed/725542/{guid}?token=…&expires=…",
  "token": "… | null",
  "expires_at": 1721400000,
  "expires_in": 7200
}

• embed_url is signed (SHA256_HEX(BUNNY_STREAM_TOKEN_AUTH_KEY + guid + expires)) when the token key is configured; otherwise token/expires_at are null and the embed URL is unsigned.
• Student tokens are tied to the active viewing session: expires_in = max(active_session.remaining_seconds + 600, 3600) — a shared embed URL dies with the student's 6-hour session window (15-min buffer so a viewer mid-video isn't cut off at the window end).
• Teachers/assistants/siteowner previews get the flat 2-hour default (expires_in = 7200).

Files changed: courses/views.py (VideoPlayView), docs/API_STUDENT.md, docs/BUNNY_STREAM_FRONTEND.md, docs/CHANGELOG.md.

Students Progress — Video Meta + Per-Student Watch Details (Aug 2026)

GET /courses/lectures/<pk>/students-progress/ now exposes per-video watch details (purely additive — nothing renamed/removed):

• Top-level videos meta (same pattern as homeworks/quizzes): [{id, name, order}] — all videos in the lecture, ordered by order.
• Per-student watch.videos: one entry per lecture video, aligned to the meta order, for every row — never-watched videos use defaults:

{
  "video_id": 30,
  "progress_seconds": 540,
  "cumulative_watch_seconds": 520,
  "duration_seconds": 600,
  "is_completed": true,
  "last_watched_at": "2026-08-11T09:00:00Z",
  "progress_percentage": 86.7
}

• progress_percentage = cumulative_watch_seconds / duration_seconds × 100, capped at 100, rounded to 1 decimal, 0 when duration is null (null-safe).
• Fields map 1:1 to VideoWatchProgress; the per-video map is built in one query, so there's no N+1.

Files changed: courses/views.py (LectureStudentsProgressView), courses/serializers.py (LectureVideoSerializer, StudentVideoProgressSerializer, StudentWatchInfoSerializer.videos, LectureStudentsProgressSerializer.videos), courses/tests.py (7 new tests), docs/API_TEACHER.md.

Course Eligibility Gating + Public SEO Catalog + Public Stats (Aug 2026)

1. GET /courses/ is now auth-only in ALL cases (?teacher= included)

• CourseListCreateView.get_permissions → IsAuthenticated for every GET (previously ?teacher= was public). Anonymous browsing moved to the new public endpoints below.
• Student eligibility filter: when the requester is a student, the list is filtered to courses they may enroll in (grade, and subject's school_type/division — mirroring Enrollment.clean() via the new course_eligibility() helper in courses/serializers.py).
• GET /courses/topics/, GET /courses/videos/, GET /courses/videos/<id>/ now require authentication (locks anonymous topic/video leaks; writes still teacher-only).

2. eligibility field in course responses

CourseListSerializer, CourseSerializer, and GET /courses/<id>/preview/ now return eligibility: {eligible: bool, reason: 'grade'|'division'|'school_type'|null} only for authenticated students (null otherwise). The frontend can hide "Enroll" and show the reason pre-submit.

3. Public SEO endpoints (no auth, no prices/videos, no student data)

4. Public teacher list gains courses_count

GET /accounts/public/teachers/ now annotates and returns courses_count (number of active courses per teacher, 0 default).

Tests: courses/tests.py + accounts/tests.py — replaced the old "public with teacher filter" test with auth-required + eligibility tests, added public list/detail (no prices), public stats, and courses_count tests.

Files changed: courses/views.py, courses/serializers.py, courses/urls.py, accounts/views.py, accounts/serializers.py, accounts/urls.py, courses/tests.py, accounts/tests.py, docs/API_PUBLIC.md, docs/API_OVERVIEW.md, docs/API_STUDENT.md, docs/CHANGELOG.md.

Question Points Capped at 20 (Aug 2026)

Per-question points are now capped at 20 for all three assessment types:

• Enforced at the model level (MaxValueValidator(20), message "Points per question cannot exceed 20.") — applies to Django admin and all serializer flows automatically.
• Enforced at the API level for inline question payloads (QuizQuestionInlineSerializer/ExamQuestionInlineSerializer.points_override now max_value=20) — POST/PUT/PATCH of a question with points_override > 20 returns 400.
• Homeworks: the ModelSerializer picks up the model validator, so points > 20 in homework create/update also returns 400.
• effective_points/total_points math unchanged (min 1 when unset).

Tests: 13 new (5 quiz + 4 exam + 4 homework): model-level reject/accept (20 OK, 21 rejected), default 1, API inline reject at 21 / accept at 20.

Files changed: learning/base_app/models.py, homeworks/models.py, quizzes/serializers.py, exams/serializers.py, migrations (quizzes/0010, exams/0005, homeworks/0009), quizzes/tests.py, exams/tests.py, homeworks/tests.py, docs/API_TEACHER.md, docs/FRONTEND_BUILD_ORDER.md, docs/CHANGELOG.md.

Cut Invoice System (SiteOwner-Facing, Aug 2026)

A manual, invoice-based platform-cut system. No rule engine — the siteowner decides the cut per lecture on every invoice.

Concept

1. Siteowner opens a Cuts page → sees per-teacher total lectures, lectures purchased, and per-course breakdown (course, grade, lectures, purchases, purchase revenue), filterable by date range.
2. Siteowner creates an invoice: teacher + date range + cut per lecture (their choice).
3. Backend snapshots lectures_count = purchases in the range at creation; total_owed = cut_per_lecture × lectures_count.
4. Invoice shows what the teacher owes. Siteowner can mark paid / cancel (soft). Teachers see their own invoices.

New model: CutInvoice (balance/models.py)

Key behaviors:

• compute_totals() counts purchases and sets totals — CREATE time only.
• recompute_total() recomputes total_owed from the existing snapshot — editing the cut never re-counts (purchases made after the invoice snapshot are NOT pulled in).
• Overlap prevention: an unpaid/paid invoice blocks any other invoice for the same teacher whose period intersects it (start ≤ new_end AND end ≥ new_start). Cancelled invoices don't block (a period can be re-invoiced after cancellation). Adjacent periods are allowed.
• Paid lock: cut_per_lecture is frozen once status='paid' (PATCH → 400; revert to unpaid first).
• Teacher and period are immutable after creation (PATCH → 400; cancel and recreate instead).
• DELETE is a soft cancel (status → cancelled, paid_at cleared, row kept).

New endpoints (all under /payments/cuts/)

Overview response shape (per teacher):

{
  "teacher_id": 5,
  "teacher_name": "Dr Hany",
  "total_lectures": 42,
  "purchased_count": 320,
  "outstanding_total": "6400.00",
  "paid_total": "1200.00",
  "courses": [
    {
      "course_id": 28,
      "course_name": "Chemistry 3rd Secondary",
      "grade_name": "3rd Secondary",
      "total_lectures": 24,
      "purchased_count": 210,
      "purchased_revenue": "8400.00"
    }
  ]
}

Invoice create body: {teacher, start_date, end_date, cut_per_lecture, note?} → 201 with computed lectures_count / total_owed.

Invoice PATCH rules: cut_per_lecture (recompute, blocked when paid) | note | status (paid → sets paid_at; unpaid/cancelled → clears it). teacher/start_date/end_date are locked.

Teacher dashboard

GET /courses/teacher/dashboard/ summary now includes outstanding_cut (string decimal — sum of the teacher's unpaid invoices).

Admin

CutInvoiceAdmin registered in balance/admin.py — fully read-only (add/delete disabled).

Tests

47 new tests in balance/tests.py: model math + snapshot semantics, overview correctness + per-course breakdown, range/both-required/invalid-date/404 cases, full role-permission matrix (anonymous/teacher/assistant/student/siteowner × every endpoint), invoice lifecycle (create math, zero purchases, start>end, negative cut, overlap/contained/adjacent/redo-after-cancel, patch cut vs frozen count, note-only patch, mark paid + paid_at, revert + clear, cut-edit-when-paid blocked, teacher/period change blocked, soft delete, list filters).

Files changed: balance/models.py, balance/serializers.py, balance/views.py, balance/urls.py, balance/admin.py, balance/tests.py, balance/migrations/0013_cutinvoice.py, courses/views.py (TeacherDashboardView), docs.

Cut Endpoints — Search Support (Aug 2026)

All cut-invoice list endpoints now support a ?search= parameter (case-insensitive, partial):

?search= combines with all existing filters (teacher, status, start/end, course). The overview remains unpaginated by design (one row per teacher — the frontend computes the summary cards from the full response); lectures/invoices/my stay paginated.

17 new tests cover: search by each field, case-insensitivity, partial match, no-match → empty, and search combined with range/status/course filters.

Files changed: balance/views.py, balance/tests.py, docs.

Cut Invoices — Discount, Paid Note, Gross Total, Overview Detail Mode (Aug 2026)

New invoice fields

New math: total_owed = max(0, (cut_per_lecture × lectures_count) − discount). gross_total is always exposed; lectures_count remains a frozen snapshot.

Validation: discount cannot be negative and cannot exceed the gross total — enforced at create AND on every cut/discount edit (400 otherwise). Editing discount while status='paid' is blocked (same lock as the cut).

Paid lifecycle: status: 'paid' sets paid_at (and saves paid_note from the same PATCH); reverting to unpaid/cancelled (or DELETE) clears paid_at and paid_note.

Overview consolidation (kills 2 API calls)

GET /payments/cuts/overview/:

• Every row now includes profile_picture (absolute URL or null) — the frontend no longer needs a separate teachers fetch for avatars.
• With ?teacher=<id> the single row additionally embeds lectures_count and lectures[] — per-lecture rows (lecture_id, lecture_name, topic_id/topic_name, course_id/course_name, grade_name, price, final_price, purchased_count, purchased_revenue). Purchase counts respect the start/end range. The frontend's teacher-detail page reads this directly.

Invoice response now: ... , cut_per_lecture, discount, gross_total, total_owed, status, note, paid_note, paid_at, ...

Files changed: balance/models.py (+migration 0014), balance/serializers.py, balance/views.py, balance/admin.py, balance/tests.py (20 new tests), docs.

Multi-Attempt Quizzes Restored (Aug 2026)

Supersedes the older "attempt_number Removed" and "Single-Attempt + Submission Deletion" sections below. Those sections describe behavior that was reverted and are kept only for history.

Current attempt policy (authoritative)

Model changes

• QuizSubmission.attempt_number (PositiveInteger, default 1) restored.
• unique_together = ['quiz', 'student', 'attempt_number'] restored on QuizSubmission.
• ExamSubmission remains unique_together = ['exam', 'student'] (no attempt_number).

POST /learning/quizzes/<id>/start/ behavior (new)

settings.max_attempts is active again (quizzes only)

• max_attempts in QuizSettings is read by the backend again to gate quiz starts (default 1, any positive integer).
• max_attempts in exam settings is ignored — exams are always single-attempt.
• The "deprecated" note from previous changelog entries no longer applies to quizzes.

Teacher retake flows

• Quiz retake: delete ONE submitted attempt (DELETE /learning/quiz-submissions/<pk>/delete/) to free one attempt slot, or delete all to reset to attempt #1. An in-progress attempt must be deleted to start fresh.
• Exam retake: delete the single submission (DELETE /learning/exam-submissions/<pk>/delete/).
• QuizResultsView shows one row per student (all purchasers); for multi-attempt quizzes the attempt shown follows the submission ordering (-submitted_at, -started_at).

Files changed: quizzes/models.py, quizzes/views.py (QuizStartView), quizzes/migrations/0008/0009

Course Creation Now Requires subject

• POST /courses/ now requires a subject field (Subject ID). Previously the subject was auto-derived from the teacher.
• Validation: the teacher must teach the selected grade and subject; the subject must be available for the grade.
• subject is returned in all course serializers (subject_name too).
• Teacher and grade remain immutable on update; name is editable (still unique per teacher+grade).

Files changed: courses/serializers.py (CourseCreateUpdateSerializer), courses/views.py

Course List & Detail — Auth Required (Expired-Session Leak Fix)

⚠️ PARTIALLY SUPERSEDED (Aug 2026): A later commit made GET /courses/ auth-only in ALL cases — the ?teacher= public path no longer exists. Anonymous browsing now uses GET /courses/public/ + GET /courses/public/<pk>/. See Course Eligibility Gating + Public SEO Catalog + Public Stats.

• GET /courses/ (no ?teacher= param) now requires authentication. With an expired token this returns 401 instead of silently returning all teachers' active courses. Public listings still work via ?teacher=<id> (used by public teacher pages) and GET /courses/by-subject/<id>/.
• GET /courses/<id>/ now requires authentication (was fully public). The public course preview uses the separate GET /courses/<id>/preview/ endpoint.

Files changed: courses/views.py (CourseListCreateView, CourseDetailView)

student_name_ar Added to Teacher-Facing Responses

Added the Arabic student name to:

• GET /learning/quizzes/<id>/results/ rows (student_name_ar)
• GET /learning/quizzes/<id>/results/ submission detail serializer (QuizSubmissionSerializer)
• GET /learning/exams/<id>/results/ (ExamSubmissionSerializer)
• GET /learning/homeworks/<id>/submissions/ rows (student_name_ar)
• GET /learning/homework-submissions/<id>/ (HomeworkSubmissionDetailSerializer)

Files changed: quizzes/views.py, quizzes/serializers.py, exams/serializers.py, homeworks/views.py, homeworks/serializers.py

Code Analytics — Teacher/SiteOwner Cuts Removed

GET /payments/codes/analytics/ now returns exactly 8 fields — the revenue-split calculation was removed:

{
  "total_batches": 45,
  "total_codes": 5000,
  "valid_count": 3000,
  "valid_value": "150000.00",
  "used_count": 1800,
  "used_value": "90000.00",
  "blacklisted_count": 200,
  "blacklisted_value": "10000.00"
}

No teachers_cut / siteowner_cut / revenue fields. The frontend should remove those analytics cards.

Files changed: balance/views.py (CodeAnalyticsView)

Other Fixes (July–Aug 2026)

• UnboundLocalError in the lecture reopen endpoint fixed.
• CORS restricted to http://localhost:3000, http://127.0.0.1:3000, and https://online.edutrackeg.com (plus matching CSRF_TRUSTED_ORIGINS).
• openpyxl pinned to 3.1.5 (stable with Python 3.10 + codes export).
• Multi-subject teachers: TeacherProfile.subjects ManyToMany replaces the single-subject FK. Teacher create/update use subjects: [ids]. Public/owner serializers expose subjects_detail / subject_names.
• Curriculum seed overhaul: grades ordered (prep before secondary), Azhar merged into عام subjects, English split by school type, FL2 split into FR/DE/IT, Baccalaureate tracks added, seed_curriculum command is idempotent.

Teacher Dashboard — Expanded with Actions Needed

GET /courses/teacher/dashboard/ — New expanded endpoint

New consolidated dashboard endpoint that returns summary stats, action items, recent activity, and per-course breakdown in a single response.

The old URL GET /courses/dashboard/teacher/ was removed — use GET /courses/teacher/dashboard/.

Response structure (new):

New actions_needed section:

{
  "actions_needed": {
    "pending_enrollments": [
      {
        "enrollment_id": 1,
        "student_id": 10,
        "student_name": "Ahmed Ali / أحمد",
        "student_code": "1234567",
        "course_id": 28,
        "course_name": "Chemistry 3rd Secondary 2027",
        "enrolled_at": "2026-07-30T10:00:00Z"
      }
    ],
    "ungraded_written": {
      "total_pending": 5,
      "quizzes": [
        { "quiz_id": 94, "quiz_title": "Important Quiz", "lecture_name": "Lecture 1", "course_name": "...", "pending_count": 3 }
      ],
      "exams": [
        { "exam_id": 2, "exam_title": "Midterm", "course_name": "...", "pending_count": 2 }
      ]
    }
  }
}

• actions_needed.pending_enrollments — full list (not capped) of pending enrollments, newest first, with student + course context for quick approve/reject.
• actions_needed.ungraded_written — counts written answers with written_grade=null on submitted quiz/exam submissions. Each quiz/exam appears once with its pending_count. Empty quizzes: [] / exams: [] means nothing to grade.

Authentication: Teacher, Assistant (ownership-scoped)

Files changed: courses/views.py (TeacherDashboardView), courses/urls.py

Prerequisites Rework — Quiz/Exam Only, Same-Lecture Validation

LecturePrerequisite changes

Before: Could set homework, quiz, or exam from any lecture as a prerequisite. Students might need to buy an extra lecture just to access a prerequisite assessment.

After:

New prerequisite flow for teachers:

1. Create a quiz inside the lecture you want to gate
2. Write questions that test prerequisite knowledge from earlier lectures
3. Set that quiz as the prerequisite with a passing_score
4. Student buys the lecture → takes the quiz → if they know the material, they pass → videos unlock
5. No extra purchases needed — the prerequisite assessment is in the same lecture

Error if trying to use a quiz from a different lecture:

{"non_field_errors": ["Prerequisite quiz must belong to the same lecture. Quizzes from other lectures cannot be used as prerequisites."]}

API changes:

• GET /courses/lectures/<pk>/available-assessments/ no longer returns homeworks
• VideoPlayView no longer checks homework prerequisites
• Signals cleanup for homework prerequisites removed

Multi-Identifier Login (Email, Gmail, Phone)

POST /accounts/login/ — Login with username, email, gmail, or student phone

Before: Only accepted username (the User.username field). Students who forgot their username couldn't log in even though they knew their email.

After: The username field now accepts:

1. Username (direct match)
2. Email (User.email)
3. Gmail (any profile's gmail field — Student, Teacher, Assistant, SiteOwner)
4. Phone number (StudentProfile.phone_number — unique field, students only)

Backend resolves the input to the actual username before authenticating. No frontend changes needed — same {"username": "...", "password": "..."} request body.

Files changed: accounts/serializers.py

Student Dashboard Consolidated Endpoint

GET /courses/student/dashboard/

New consolidated endpoint that returns all student dashboard data in a single response, replacing 5 separate API calls:

Response includes: enrolled_courses[] (with per-course balance, teacher info, purchased lecture count), my_lectures stats (total/active/expired), nearly_expired_lectures[] (lectures expiring soon with remaining hours), homeworks stats (total/submitted/graded/pending), and quizzes stats (total/not_started/in_progress/submitted).

Authentication: Student only

Files changed: courses/views.py, courses/serializers.py, courses/urls.py

API Consolidation — Removed Duplicate Endpoints

Removed Endpoints

The following duplicate student-only endpoints have been removed. Their data is now available through the existing list endpoints (which now include student-specific submission fields).

Enhanced List Endpoints

GET /learning/quizzes/ — NEW fields for students: quiz_status (not_started|in_progress|submitted), submission_id, score, score_visible

GET /learning/homeworks/ — NEW fields for students: question_count, is_submitted, submission_id, score, status (submitted|graded), submitted_at

GET /learning/exams/ — NEW fields for students: quiz_status (not_started|in_progress|submitted), submission_id, score, score_visible

Files changed: learning/views.py, learning/serializers.py, learning/urls.py

Quiz/Exam Question Editing — Auto-Regrade on Changes

PUT/PATCH /learning/quizzes/<id>/ and /learning/exams/<id>/

Before: Blocked editing questions entirely if any submissions existed. Teachers had to delete the quiz and recreate it.

After: Teachers can freely edit questions, add new ones, or remove them. All existing submissions are auto-regraded with the new data.

New error for blocked question_type changes:

{"non_field_errors": ["Cannot change question type after submissions exist. Delete and recreate the question instead."]}

Files changed: quizzes/serializers.py, exams/serializers.py

Student Dashboard Endpoints (My Lectures, Homeworks, Quizzes)

GET /courses/my-lectures/

New endpoint that returns ALL purchased lectures across all enrolled courses in a single response. No more per-course iteration. Includes expiry status, active session indicator, content counts (videos, materials, homeworks, quizzes), and session tracking.

GET /learning/homeworks/all/

New endpoint that returns ALL homeworks for all purchased lectures across all courses in a single response. Shows submission status and score if graded. Includes course/lecture/topic context for each homework — no more merging data from multiple endpoints.

GET /learning/quizzes/all/

New endpoint that returns ALL quizzes for all purchased lectures across all courses in a single response. Shows quiz status (not_started/in_progress/submitted), score if visible, and settings. Includes full course/lecture/topic context.

All three endpoints are Student-only (require student_profile).

Written Answers Review Endpoint

GET /learning/quizzes/<pk>/written-answers/ + GET /learning/exams/<pk>/written-answers/

New endpoints for teachers to review and grade written questions in bulk.

Returns ALL written answers across ALL students who submitted, grouped by question:

{
  "quiz_id": 94,
  "quiz_title": "Important Quiz",
  "total_questions": 2,
  "total_graded": 1,
  "total_pending": 1,
  "written_questions": [
    {
      "question_id": 341,
      "question_text": "What is...?",
      "max_score": 5,
      "answers": [
        {"answer_id": 501, "student_name": "Shahd...", "written_answer": "CO2",
         "current_score": 3, "max_score": 5, "is_graded": true,
         "feedback": "Correct formula...", "graded_by": "Dr Hany"}
      ]
    }
  ]
}

Teachers can see all pending written answers in one view, then grade each using the existing POST /.../grade-written/ endpoint.

Files changed: quizzes/views.py, exams/views.py, quizzes/urls.py, exams/urls.py

Un-Release Endpoints (Scores + Answers)

4 new endpoints to reverse score/answer releases

All require Teacher/Assistant with course ownership. Returns 204 No Content.

Before: Scores/answers could only be released (one-way). No way to revoke. After: Teachers can release, then unrelease, then release again as needed.

Behavior by visibility mode

attempt_number Removed

⚠️ SUPERSEDED (Aug 2026): Multi-attempt quizzes were restored — attempt_number is back on QuizSubmission. See Multi-Attempt Quizzes Restored. This section describes the (reverted) single-attempt era.

The attempt_number field has been fully removed from the system. Since single-attempt is now the only supported mode, the field was redundant.

Changes:

• attempt_number removed from BaseSubmission model (affects QuizSubmission and ExamSubmission)
• Removed from all serializers, views, admin, and models
• Removed from unique_together constraints
• QuizStartView and ExamStartView no longer set attempt_number when creating submissions
• Quiz/exam API responses no longer include attempt_number

Single-Attempt + Submission Deletion

⚠️ PARTIALLY SUPERSEDED (Aug 2026): Quizzes are multi-attempt again (max_attempts enforced); exams remain single-attempt. The delete-submission endpoints below are still the retake mechanism. See Multi-Attempt Quizzes Restored.

Single-Attempt Enforcement (Quizzes + Exams)

Before: max_attempts setting controlled how many times a student could start/submit a quiz or exam (default 1, configurable up to N). The start endpoints checked attempt count against max_attempts.

After: Students can only start a quiz/exam ONCE. No multiple attempts.

• QuizStartView and ExamStartView now check if ANY submission exists for the student+quiz/exam. If yes, block with:

  {"detail": "You have already started this quiz/exam. If you need to retake, ask your teacher to delete your previous submission."}
  

New Delete Endpoints (Teacher/Assistant)

Allow teachers to delete student submissions, enabling retakes:

Authorization: Teacher or Assistant only, must own the course.

Success Response — 204 No Content

Error Responses:

max_attempts Field — Deprecated

The max_attempts field still exists in the QuizSettings and exam settings models/serializers for backward compatibility, but its value is effectively always 1. The backend no longer reads this field to gate access. Setting it to any value has no effect — students always get exactly 1 attempt.

Video Progress Tracking — Dual-Value Completion

POST /courses/progress/update/ & VideoWatchProgress model

Before: progress_seconds tracked only the furthest playhead position. A student could scrub to 90% in 5 seconds and get is_completed without actually watching. Frontend sent updates every 5-30 seconds.

After: Added cumulative_watch_seconds field. is_completed now requires both conditions:

• progress_seconds >= duration * 0.9 (must reach the end — prevents watching only the beginning on repeat)
• cumulative_watch_seconds >= duration * 0.9 (must genuinely watch enough — prevents scrubbing to the end)

New response fields:

• cumulative_watch_seconds — total wall-clock seconds played (not paused/buffering)
• position_percentage — percentage based on progress_seconds (furthest position)

Request changes:

• progress_seconds — still required, still the current playback position
• cumulative_watch_seconds — new, optional, send only on milestones (25%/50%/75%/90%)
• Frontend tracks cumulative time in localStorage — survives page refreshes
• Total requests per video drops from ~30 to ~5-6

Why: Accurate completion tracking without hammering the backend. A 10-min video requires the student to genuinely play >= 9 minutes AND reach >= 9 minutes position to complete.

Balance Endpoint — Now Shows All Enrolled Courses

GET /payments/balance/ — Shows 0 balance for new students

Before: Only returned courses where a CourseBalance record existed (i.e., the student had redeemed a code or received a recharge). Newly approved students with no transactions saw {"count": 0, "results": []}.

After: Returns ALL approved-enrolled courses. Courses without a CourseBalance record show "balance": "0.00" and "id": null.

{"id": null, "course": 1, "course_name": "Chemistry", "balance": "0.00", ...}
{"id": 5,    "course": 2, "course_name": "Physics",   "balance": "150.00", ...}

Why: A student with 0 balance should see their enrolled courses listed, not an empty page.

Single-Session Enforcement (Students Only)

POST /accounts/login/ — Immediate invalidation of previous sessions

Before: Logging in from a new device did NOT invalidate the previous device's tokens. A student could share their credentials and both devices would work simultaneously.

After: Added token_version field to the User model. Each student login increments token_version and embeds it in both the access and refresh tokens. Every API request verifies the token's version matches the user's current version.

Affected files:

• accounts/models.py — added token_version field
• accounts/views.py — LoginView increments + embeds version; TokenRefreshView checks version
• accounts/authentication.py — CookieJWTAuthentication checks version on every API call

New error response for invalidated sessions:

{"error": "Session invalidated by a new login on another device."}

Session-Based Watch Counting

New Model: LectureViewingSession

A model that tracks 6-hour viewing windows for a purchased lecture.

Properties: is_active (true if now < expires_at), remaining_seconds (positive int, 0 if expired)

SESSION_DURATION_HOURS = 6

New Fields on PurchasedLecture

max_watch_count (default=4) is now interpreted as maximum viewing sessions, not maximum per-video watches.

Removed Model Logic

VideoWatchProgress.update_progress() — removed all watch_count/session increment logic. Now only tracks progress_seconds, duration_seconds, and is_completed. No more 5-minute gap session detection.

New Endpoints

POST /courses/purchases/<pk>/start-watching/

If there's an active session (within 6h), returns existing session. Otherwise creates a new 6h session and increments sessions_used.

Success Response — 200 (existing session):

{
  "session": { "id": 1, "purchase": 5, "started_at": "...", "expires_at": "...", "is_active": true, "remaining_seconds": 21540 },
  "sessions_used": 1,
  "sessions_remaining": 3,
  "message": "Resuming existing session."
}

Success Response — 201 (new session):

{
  "session": { "id": 2, "purchase": 5, "started_at": "...", "expires_at": "...", "is_active": true, "remaining_seconds": 21599 },
  "sessions_used": 2,
  "sessions_remaining": 2,
  "message": "Session started. You have 6 hours to watch all videos."
}

Error Responses:

GET /courses/purchases/<pk>/active-session/

Returns the current active session status for a purchase. No session is created — this is read-only.

Response — Active session:

{
  "has_active_session": true,
  "session": { "id": 1, "purchase": 5, "started_at": "...", "expires_at": "...", "is_active": true, "remaining_seconds": 12000 },
  "sessions_used": 1,
  "sessions_remaining": 3
}

Response — No active session:

{
  "has_active_session": false,
  "is_expired": false,
  "sessions_used": 1,
  "sessions_remaining": 3
}

Response — Purchase expired:

{
  "has_active_session": false,
  "is_expired": true,
  "error": "Your access to this lecture has expired."
}

Modified Endpoints

GET /courses/videos/<pk>/play/

Removed old check: SUM(VideoWatchProgress.watch_count) >= purchase.max_watch_count

Added check: must have an active LectureViewingSession (expires_at > now)

If no active session → 403 with {"error": "No active viewing session. Click \"Start watching\" to begin a 6-hour session.", "sessions_used": 1, "sessions_remaining": 3}

POST /courses/progress/update/

Removed old check: SUM(watch_count) >= max_watch_count

Added same session check as the play endpoint — requires an active LectureViewingSession.

PATCH /courses/purchases/<pk>/reopen/

Instead of resetting VideoWatchProgress.watch_count to 0

Now resets purchase.sessions_used to 0 and deletes all LectureViewingSession records for that purchase.

GET /courses/<id>/lectures/

Purchase object now includes:

Serializer Changes

• New LectureViewingSessionSerializer: fields [id, purchase, started_at, expires_at, is_active, remaining_seconds]
• PurchasedLectureSerializer now includes sessions_used
• StudentPurchaseInfoSerializer now includes sessions_used
• VideoWatchProgressSerializer no longer returns watch_count (still exists on model but unused)

General Concept

Instead of per-video session tracking (which was unreliable with internet cuts, page refreshes), the system now uses per-entry session tracking:

1. Student clicks "Start watching" → 1 session consumed from max_watch_count (default 4)
2. 6-hour window opens → all videos in the lecture are freely accessible
3. Within 6 hours → can watch any video, refresh page, internet cuts — all fine
4. After 6 hours → must click "Start watching" again → consumes another session
5. If all 4 sessions used → must contact teacher for reopen (which resets sessions_used to 0)

Homework

GET /learning/homeworks/<id>/submissions/ — Complete Rewrite

Before: Only returned students who actually submitted the homework.

{
  "count": 2,
  "results": [
    { "id": 1, "student_name": "Mariam...", "score": "7.00", "status": "graded", "submitted_at": "..." }
  ]
}

After: Returns ALL students who purchased the lecture, with their submission status. Students who bought but haven't submitted are now included.

{
  "homework_id": 21,
  "homework_title": "Homework 1",
  "lecture_name": "Lecture 1",
  "course_name": "Chemistry",
  "total_purchased": 5,
  "total_submitted": 2,
  "count": 5,
  "results": [
    { "student_id": 78, "student_name": "Mariam...", "is_purchased": true, "submitted": true, "submission_id": 1, "score": "7.00" },
    { "student_id": 79, "student_name": "Shahd...", "is_purchased": true, "submitted": false, "submission_id": null, "score": null }
  ]
}

Added filters: ?submitted=true|false, ?search=name_or_code

Why: Teachers need to see who bought the lecture but hasn't done the homework — not just who already submitted.

GET /learning/quizzes/<id>/results/ — Complete Rewrite

Before: Only returned students who submitted a quiz attempt.

After: Returns ALL students who purchased the lecture, with 3 quiz statuses:

Added filters: ?quiz_status=not_started|in_progress|submitted, ?search=name_or_code

Added meta: total_purchased, total_submitted, total_in_progress

Why: Quizzes have 3 states — students can start a quiz and walk away without finishing. Teachers need to see who's stuck in progress.

Lecture Content Details

New fields added to GET /courses/lectures/<id>/ (Lecture detail serializer)

Same fields added to GET /courses/<id>/lectures/ (Student's course lectures)

Added materials_count, homeworks_count, quizzes_count to each lecture in the student's enrolled course view.

Why: The purchase page needs to show students what a lecture contains (X videos, Y materials, Z quizzes) before they buy. Previously this required separate API calls; now it's included in the lecture detail response.

Permissions Changed

GET /courses/lectures/<id>/available-assessments/

Before: [IsTeacherOrAssistant] — teachers only.

After: [IsAuthenticated] — students can now see published assessments. Teachers/assistants still see all. Ownership check now only applies to teacher/assistant roles.

Why: The purchase page needs to show students whether a lecture has quizzes and homework.

GET /courses/lectures/<id>/prerequisites/

Before: [IsTeacherOrAssistant] — no student access.

After: GET requests now allowed for any authenticated user. POST/PUT/DELETE remain teacher-only.

Why: Students need to see prerequisites before buying a lecture.

Purchase Validation

POST /courses/purchases/buy/ — Added active purchase check

Why: Students could buy the same lecture multiple times while it's still active, losing money each time. Now they can only re-buy after expiry expires.

Removed Endpoints

GET /courses/enrolled/

Before: Separate student-only endpoint returning approved courses with course details.

After: Removed. Use GET /courses/enrollments/?status=approved instead — it now returns cover_picture, topic_count, total_lectures for approved enrollments, plus all the existing enrollment fields.

Why: Duplicated the enrollments endpoint. The serializer was enhanced to include course details instead.

Enrollment Serializer Enhancements

Also: cover_picture used to return null for non-approved enrollments. Now returns the URL for all statuses.

Balance & Transactions

GET /payments/balance/ — Added teacher picture

Added teacher_picture (URL) to each balance entry, sourced from course.teacher.profile_picture.

GET /payments/transactions/ — Added teacher name and picture

Added teacher_name and teacher_picture to each transaction entry.

Why: The transaction history UI needs to show the teacher's name and profile picture alongside each transaction.

Course & Topic Images

GET /courses/<id>/preview/ — Added topic picture

Each topic now returns picture (URL) from topic.picture.

GET /courses/<id>/lectures/ — Added topic picture

Each topic in the student's enrolled course view now returns picture (URL).

Profile Serializer

Removed email field from student profile

The StudentProfileSerializer no longer returns email (from User.email). Students only see gmail (from StudentProfile.gmail) — the field they entered during registration and used for password reset.

Why: These were duplicate fields with the same value from different models, confusing students.

Student-Facing API Documentation

All three missing endpoints were added to API_STUDENT.md:

Overview Matrix Updated

The following missing endpoints were added to API_OVERVIEW.md:

Code History Endpoint

GET /payments/codes/history/ — Fixed performed_by name resolution

Before: performed_by returned the user's username (e.g., "Marmar999999").

After: Uses the same logic as the balance transaction serializer:

• student role → "Student"
• teacher role → teacher_profile.name
• assistant role → assistant_profile.name
• Fallback → user.username

Codes List Endpoint

GET /payments/codes/ — Added search by code

Added SearchFilter with search_fields = ['code']. Now supports ?search=KTMD to filter codes by partial match.

Students Progress Endpoint

GET /courses/lectures/<id>/students-progress/ — Added filters

Before: All enrolled students returned — no search or purchase filtering.