banu-front/docs/backend-vs-ui-gaps.md

Backend (Postman) vs Frontend — fields & endpoints to decide on

Source of truth: the Postman collection covering Terms, Courses, Sessions, Exams, Homeworks, Media (2026-05). This doc lists every place where backend and FE disagree on shape, plus FE-side concepts the backend doc has no slot for. Each item needs a product/design call before we wire it up.

Conventions in the rest of this doc:

• B → FE means the backend exposes a field/endpoint that the FE doesn't surface yet.
• FE → B means the FE shows/sends a field the backend doc doesn't accept.
• shape diff means both sides handle the concept but in different shapes (enum values, nesting, naming).

---

Terms

Endpoints

Backend	FE today	Status
GET /terms?per_page&active_only	getTermsList	aligned
GET /terms/:id	showTerm	aligned
POST /terms	addNewTerm	aligned
PATCH /terms/:id	updateTerm	aligned
DELETE /terms/:id	deleteTerm	aligned
—	cloneTerm (POST /admin/terms/:id/clone)	FE-only; backend has nothing. Decide: drop the clone button, or ask backend to add it.
—	changeStatusTerm (POST /admin/terms/:id/status)	Use PATCH /terms/:id with is_active — dedicated status endpoint dropped.
—	listUserTerm, addUserTerm, removeUserTerm, changeLeaveStatus	FE-only. Term-students subtab + leave toggle. Backend exposes nothing equivalent. Keep mock-only until backend adds.
—	listCourseTerm, addCourseTerm, removeCourseTerm	FE-only. Can be replaced by GET /courses?term_id= for the list; the attach/detach side has no backend equivalent (course term_id is set at create-time).

Fields

Backend → FE	FE has it as	Notes
starts_at, ends_at (ISO datetime)	startDate, endDate	Naming diff; we send starts_at/ends_at in the mock already — confirm the FE form should rename or keep an adapter.
cover_url (read) + cover_media_id (write)	coverUrl / coverMediaId	aligned in shape, just camelCase.
created_at	createdAt	aligned.
is_active	isActive	aligned.
description	description	aligned.

FE → B (need decision):

• studentsCount, coursesCount — computed UI counts. Backend response doesn't include them. Either compute client-side or ask backend for ?include=counts.
• image (UI alias of cover) — FE keeps this for a fallback. Backend response only has cover_url.

---

Courses

Endpoints

Backend	FE today	Status
GET /courses?term_id&per_page	getCoursesList	aligned (drop /admin/ prefix in endpoints.js).
GET /courses/:id	showCourse	aligned. Backend response includes nested term and teacher — FE already reads course.term / course.teacher, good.
POST /courses	addNewCourse	aligned. Backend currently requires term_id (422 example), but per user instruction the standalone (template-tab) flow must allow term_id: null. Decide: ask backend to make term_id nullable, or refuse to submit until a term is picked.
PATCH /courses/:id	updateCourse	aligned. Used now for status toggle too (drops dedicated /status endpoint).
DELETE /courses/:id	deleteCourse	aligned.
—	changeStatusCourse (/admin/courses/:id/status)	Dropped. Use PATCH /courses/:id { is_active }.
—	listCourseStudents, addCourseStudent, removeCourseStudent	FE-only. CourseDetailsModal "students" tab + AddCourseStudentModal. Backend doesn't expose course-students; either add a sub-resource or remove the UI. Kept mock-only for now.
—	listCourseSessions, attachCourseSession, detachCourseSession	FE-only. CourseDetailsModal "sessions" tab can be served by GET /sessions?course_id=. The attach/detach side (M:N) has no backend equivalent — backend uses session.course_id (1:N). Kept mock-only for now; recommend swapping the list tab to the regular sessions query.

Fields

Backend ↔ FE	Notes
term_id ⇄ termId	aligned. Nullable in CourseFormPage, required in AddOfferedCourseModal — schema reflects this.
teacher_id ⇄ teacherId	aligned.
capacity ⇄ capacity	aligned.
is_active ⇄ isActive	aligned.
cover_media_id (write) / cover_url (read) ⇄ coverMediaId / coverUrl	aligned.
description ⇄ description	aligned.
Nested term, teacher on show response	FE already reads.

FE → B (need decision):

• sessionsCount — number-of-sessions field on the create form. Backend has nothing. Either compute server-side from related sessions, or drop the field.
• prerequisites (array of { courseId, course }) — backend has no prerequisite relation. Drop or ask backend for it.
• contentType (video/voice/text) + contentMediaId — single course-level content file. Backend treats files only as session media. Decide whether course-level content should move to "intro session" or stay a course concept.
• image (UI alias of cover_url) — kept as a fallback alongside coverUrl.

---

Sessions

Endpoints

Backend	FE today	Status
GET /sessions?course_id&per_page	getSessionsList	aligned.
GET /sessions/:id	showSession	aligned.
POST /sessions	addNewSession	aligned.
PATCH /sessions/:id	updateSession	aligned. Used for status toggle now.
DELETE /sessions/:id	deleteSession	aligned.
—	changeStatusSession (/admin/sessions/:id/toggle-status)	Dropped. Use PATCH with is_active.
—	getSessionsAttendance (/admin/sessions/:sessionId/attendances)	FE-only. SessionAttendanceModal depends on this. Kept mock-only.

Fields — biggest gap of all five resources

Backend	FE today	Notes
type enum: online | offline | content	sessionType enum: in_person, online, video, audio, text, slide, pdf	Shape diff. FE has 7 values; backend has 3. There's an existing SESSION_TYPE_TO_SPEC mapper in services/mock/fixtures/admin-sessions.js. Decide whether the FE keeps the richer 7-value enum (and we map down to backend's 3) or collapses.
starts_at, location, link	All three live inside form.sessionConfig.* plus also derived to top-level startsAt / location / link in the mock	Structural diff. Backend wants flat fields; FE form nests them under sessionConfig keyed by sessionType. The mock derives top-level from sessionConfig.* for show payloads. Decide whether the FE form should flatten the schema to match backend or keep the conditional-by-type config UI.
media_ids[] (write) / media[] (read with collection_name, file_name, mime_type, file_size, url, download_url)	materials[] with { fileId, isRequired, type, title, order }	Shape diff. Backend's media rows are typed by upload-purpose (video/voice/pdf/slide/attachment); FE has its own type enum. Decide which shape the FE keeps.
—	durationMinutes, order, sessionConfig.minWatchedPercent, sessionConfig.minReadPercent, sessionConfig.mustCompleteBeforeNext, sessionConfig.platform	FE → B, all UI-only fields. Backend has nothing equivalent. Drop, move into a metadata JSON, or ask backend to add.
—	usedInTerms	UI-only count, no backend.
—	image (vs media)	UI-only thumbnail; backend doesn't separate.

---

Exams

Endpoints

Backend	FE today	Status
GET /exams/:id (with questions+options)	showExam	aligned.
POST /exams	addNewExam	aligned.
PATCH /exams/:id	updateExam	aligned.
DELETE /exams/:id	deleteExam	aligned.
POST /exams/:examId/questions	—	Backend → FE. New endpoint. Today the FE submits the whole question list inside the exam create/update payload. Decide whether to keep "all-in-one" submission (and ask backend to accept it) or switch to add-questions-after-create.
POST /questions/:questionId/options	—	Backend → FE. Same as above — backend lets you add options one at a time. FE today bundles all options with the question.
POST /exams/:examId/submit	— (student-side feature)	Backend → FE. Student-side; not in current admin UI.
—	getExamsList (/admin/exams)	FE-only. ExamsListPage depends on it. Kept mock-only; ask backend to add a list endpoint.
—	getExamParticipants, showExamParticipant	FE-only. ExamParticipantsModal + ExamParticipantDetailsModal depend on these. Kept mock-only.

Fields

Backend ↔ FE	Notes
session_id ⇄ sessionId	aligned.
title ⇄ title	aligned.
description ⇄ description	aligned.
pass_score ⇄ passingScore	aligned (naming diff).
is_active	Backend → FE. Exam form has no active toggle. Decide whether to add it.
Backend question shape: { question_text, position, options: [{ option_text, is_correct }] }	FE: { title, score, correctAnswerId, answers: [{ id, title }] }	Shape diff. Backend hides is_correct from public reads (only on add). FE concept of score (per-question weighting) has no backend slot. Decide: keep FE scoring (ask backend to store) or drop.

FE → B (need decision):

• durationMinutes — no backend slot.
• randomize — no backend slot.
• endDate / startDate — exam validity window, no backend slot.
• usedInTerms — derived UI count.

---

Homeworks (FE calls them "assignments")

Endpoints

Backend	FE today	Status
POST /homeworks	addNewAssignment	aligned (URL renamed to /homeworks; FE key name kept).
PATCH /homeworks/:id	updateAssignment	aligned.
DELETE /homeworks/:id	deleteAssignment	aligned.
POST /homeworks/:homeworkId/submit (student)	—	Backend → FE. Student submit, not in admin UI yet.
PATCH /homework-submissions/:submissionId/review	reviewAssignmentSubmission	aligned (URL renamed).
—	getAssignmentsList	FE-only. AssignmentsListPage depends on it. Kept mock-only.
—	showAssignment, getAssignmentSubmissions, showAssignmentSubmission	FE-only. Detail + submissions list — kept mock-only.

Fields

Backend ↔ FE	Notes
session_id ⇄ sessionId	aligned.
title, description	aligned.
deadline (single datetime)	FE: startDate + endDate + computed durationDays	Shape diff. Backend has one deadline; FE has a window. Decide: drop start/end and use single deadline, or ask backend to add a window.
is_active	Backend → FE. FE form has no active toggle.
Submission status: accepted | denied	FE: pending | approved | rejected | needs_revision	Shape diff. Backend has two states; FE has four. The FE pending/needs_revision have no backend slot.
Submission media_id (single)	FE attachments[] (multiple)	Shape diff. Backend allows one file per submission; FE expects many.
Submission teacher_feedback ⇄ reviewerNote	naming diff.
Submission reviewed_at (read)	—	Backend provides; FE doesn't surface.

FE → B (need decision):

• priority enum (mandatory \| optional) — no backend slot.
• submissionsCount — derived count, no backend slot.

---

Media

Endpoints

Backend	FE today	Status
POST /media (multipart with purpose + file)	uploadMedia	aligned URL & method.
GET /media/:id/download	—	Backend → FE. Add as downloadMedia.
DELETE /media/:id	—	Backend → FE. Add as deleteMedia.

Fields

• Backend response: { id, collection_name, file_name, mime_type, file_size, url, download_url }. FE today reads payload.id, payload.url, sometimes payload.uploadId (a now-stale field). Cleanup needed: drop uploadId, use id everywhere.
• Backend purpose enum: avatar | cover | video | voice | pdf | slide | attachment | homework_file. FE upload calls currently hardcode purpose: 'cover' or purpose: 'content'. content is not in the backend enum. Decide which of the backend purposes each FE uploader should send (e.g., session video → video, course PDF → pdf, homework upload → homework_file).
• Pending media TTL: backend deletes unreferenced pending uploads after 24h. FE doesn't track this; if a user uploads a cover, abandons the form, and comes back next day, the cover_media_id reference will 404 on submit. Document the failure mode.

---

Cross-cutting

Snake_case vs camelCase

Backend wire format is snake_case throughout. FE today reads camelCase (e.g., the mock returns coverUrl, isActive). When the real backend lands, the FE will either need:

• a HTTP-layer transformer (camelize on response, snake_case on request), or
• camelCase field aliases on the backend serializer.

Decide before swapping the mock for the real API. Affects every screen.

/admin/ URL prefix

Backend doc has none — endpoints live at /terms, /courses, etc. The FE previously had /admin/courses, /admin/sessions, /admin/exams, /admin/assignments. Aligned to backend (prefix dropped). Auth context (admin role) is implicit in the token, not the URL.

Sub-features that depend on missing backend endpoints

UI screens that work today against the mock but have no backend equivalent in the current doc (kept mock-only with TODOs in endpoints.js):

• Term: clone term, term status toggle, students-in-term subtab, leave toggle, courses-in-term subtab (could swap to GET /courses?term_id=)
• Course: status toggle (swapped to PATCH), students-in-course subtab, attach/detach sessions (M:N), AddCourseStudentModal, AddSessionToCourseModal
• Session: status toggle (swapped to PATCH), attendance roster
• Exam: list page, participants list, participant detail
• Assignment/Homework: list page, detail show, submissions list, submission detail

For each of these we need to either (a) ask backend to expose the endpoint, or (b) drop the UI surface.