front-end/banu-front

Fork 0

Files

T

sajjadtalkhabi 9660e3fe8f

Deploy banu-front / deploy (push) Successful in 1m28s

Details

fix: linter

2026-05-28 15:52:48 +03:30

46 KiB

Raw Blame History

Backend API — response model gaps

This document tracks fields the frontend already consumes that are not yet present in the current backend response models. Each section lists:

Postman / current spec: what the backend returns today.
UI also needs: fields the frontend mock fixture exposes and the UI reads from. These must be added to the real response to remove the mock.
Used by: where on the frontend the field is consumed.

Naming convention: the backend uses snake_case; the HTTP client camelizes responses, so this doc lists backend keys in snake_case and notes the camelCase form the UI sees.

⚠️ Cross-cutting: `name` vs `first_name` / `last_name`

The current Postman models expose only a single name field on the user object. The UI cannot work with name alone.

The signup form (/register) collects two separate inputs: نام (first name) and نام خانوادگی (last name). If the backend only stores name, these two inputs collapse on the server and cannot be returned to the UI later.
After signup, GET /auth/me is the source of truth for the authenticated user — the layout header, the dashboard, and EditProfilePage.vue all read firstName / lastName (not name). A /auth/me response without first_name / last_name leaves these views blank.
Every other user-returning endpoint has the same need (/admin/users list rows, /admin/users/:id detail modal, /admin/users create, /admin/users/:id update, /admin/users/:id/role assign-roles response, login response data.user, register response, etc.).

Required action on the backend side:

Persist first_name and last_name as independent columns on the user table — accept them as separate keys in every write endpoint that touches the user (/register, POST /admin/users, PATCH /admin/users/:id).
Return first_name, last_name, and the convenience full_name (or keep name) in every user-returning response. The UI will continue reading firstName / lastName; fullName / name are used only where a single display string is needed (tables, badges).
If the existing data already only has name, do a one-time migration (split on the first whitespace, fall back to leaving last_name empty for single-token names). New writes must keep the two columns in sync with name / full_name.

The per-endpoint tables below repeat first_name / last_name under each "Missing — UI also needs" section so the backend dev cannot miss it on individual routes; this top section explains why it is the same answer everywhere.

POST `/media/upload` — single-step media upload (canonical)

This is the only media-upload endpoint in the project. Earlier revisions of this doc referenced per-resource cover endpoints (POST /terms/:id/image, POST /courses/:id/image, POST /sessions/:id/media) — those were a mistake and have been removed from the FE, the API client, and the mock.

Flow

User picks a file (avatar / cover / attachment) in the form.
FE posts the file as multipart/form-data to POST /media/upload (was POST /upload-temp).
Backend stores the file and returns its media id.
FE puts that id on the resource create/update body under whichever key the resource expects: avatar_id, image_id, cover_id, material_id, etc.
The resource endpoint (POST /courses, PATCH /terms/:id, POST /admin/users, …) resolves the id and attaches the media.

The previous mock endpoint path was /upload-temp. It now lives at /media/upload. The FE function useUploadTemporaryMutation was renamed to useUploadMediaMutation (consumed by the profile form, admin-user form, admin-term form, admin-course forms, admin-session form, and the student-register media/personal-info components).

Mock request

multipart/form-data with a single file field.

Mock response

{
  "success": true,
  "message": "Media uploaded.",
  "data": {
    "id": 1234,
    "upload_id": 1234,
    "url": "https://…/240/240"
  }
}

upload_id is an alias for id and is what older FE code reads (form.value.imageId = payload?.uploadId || payload?.id). Backend should return both keys, or eventually the FE migrates to reading only id.

How the resource body references the upload

Resource form	Field on the body	Backend should treat it as a media id
`/auth/me` profile	`avatar_id`	yes
`POST /admin/users`	`avatar_id`	yes
`POST /terms`	`image_id`	yes — sets `cover_url`
`POST /courses`	`image_id`	yes — sets `cover_url`
`POST /sessions`	`image_id` / `materials[]`	yes — `image_id` sets cover; `materials` array carries session attachments by their media ids

Decision pending: rename FE field image_id → media_id across the board, or have the backend accept the resource-specific field names. The mock currently honors the resource-specific names.

GET `/auth/me` — current user

Mock fixture: src/services/mock/fixtures/me.js (currentMe). Frontend query: useGetMeQuery in src/services/query/auth.js.

This endpoint is the source of truth for the logged-in user immediately after /register (signup). Anything the signup form collects but /auth/me doesn't return is effectively lost from the UI's perspective. See the cross-cutting name vs first_name/last_name note above before reviewing this section.

Spec (already implemented)

Backend key	UI key (camelCase)	Type	Notes
`id`	`id`	number
`name`	`name`	string	Full display name
`email`	`email`	string
`phone`	`phone`	string	E.164, e.g. `+989121234567`
`roles`	`roles`	string[]	e.g. `["student"]`
`avatar_url`	`avatarUrl`	string	Public avatar URL
`avatar_download_url`	`avatarDownloadUrl`	string	Signed/download endpoint
`created_at`	`createdAt`	string	ISO 8601

Missing — UI also needs

Backend key (proposed)	UI key (camelCase)	Type	Used by
`first_name`	`firstName`	string	`EditProfilePage.vue` form, header/greeting
`last_name`	`lastName`	string	`EditProfilePage.vue` form
`full_name`	`fullName`	string	Lists/tables that render a single name string
`phone_number`	`phoneNumber`	string	`EditProfilePage.vue` form (local format, e.g. `09121234567`)
`national_code`	`nationalCode`	string	`EditProfilePage.vue` form, identity validation
`status`	`status`	string	enum: `pending` \| `approved` \| `rejected` — gates access in the UI
`address.address`	`address.address`	string	`EditProfilePage.vue` address textarea
`address.province.id`	`address.province.id`	number	`EditProfilePage.vue` province select
`address.province.name`	`address.province.name`	string
`address.city.id`	`address.city.id`	number	`EditProfilePage.vue` city select
`address.city.name`	`address.city.name`	string
`profile.bio`	`profile.bio`	string	`EditProfilePage.vue` bio textarea
`profile.birth_date`	`profile.birthDate`	string	ISO 8601, `EditProfilePage.vue` date picker
`profile.marital_status`	`profile.maritalStatus`	string	enum: `single` \| `married`
`profile.gender`	`profile.gender`	string	enum: `male` \| `female`
`profile.education_status`	`profile.educationStatus`	string	enum
`profile.seminary_level`	`profile.seminaryLevel`	string	enum
`profile.university_level`	`profile.universityLevel`	string	enum
`profile.university_name`	`profile.universityName`	string
`profile.field_of_study`	`profile.fieldOfStudy`	string
`profile.avatar_id`	`profile.avatarId`	number \| null	Media id returned by `POST /media/upload`

Suggested response shape

{
  "success": true,
  "message": "OK",
  "data": {
    "id": 5,
    "name": "Jane Student",
    "first_name": "Jane",
    "last_name": "Student",
    "full_name": "Jane Student",
    "email": "jane.student@example.com",
    "phone": "+989121234567",
    "phone_number": "09121234567",
    "national_code": "0079827498",
    "status": "approved",
    "roles": ["student"],
    "avatar_url": "http://localhost:8080/storage/users/5/avatar.jpg",
    "avatar_download_url": "http://localhost:8080/api/media/9/download",
    "created_at": "2026-02-01T10:00:00+00:00",
    "address": {
      "address": "...",
      "province": { "id": 1, "name": "تهران" },
      "city": { "id": 11, "name": "تهران" }
    },
    "profile": {
      "bio": "...",
      "birth_date": "1989-06-12T00:00:00.000Z",
      "marital_status": "married",
      "gender": "male",
      "education_status": "graduate",
      "seminary_level": "level_3",
      "university_level": "master",
      "university_name": "تهران",
      "field_of_study": "علوم قرآنی",
      "avatar_id": null
    }
  }
}

GET `/admin/users` — list users (paginated)

Mock fixture: src/services/mock/fixtures/admin-users.js (adminUsers, makeUser). Mock route: src/services/mock/routes/admin-users.js. Frontend query: useAdminUsersListQuery in src/services/query/admin-users.js. Consumed by: src/features/admin/users/pages/UsersListPage.vue, src/features/admin/users/components/UsersTable.vue.

Spec envelope

{
  "success": true,
  "message": "OK",
  "data": {
    "items": [
      /* user objects */
    ],
    "meta": {
      "current_page": 1,
      "per_page": 20,
      "total": 3,
      "last_page": 1
    }
  }
}

Query params the UI already sends: search, per_page, page, name, national_code, phone_number, role_id, from_date, to_date. The spec only documents search + per_page — backend should accept the rest or the UI filters need to be reworked.

Per-item spec (already implemented)

Backend key	UI key (camelCase)	Type
`id`	`id`	number
`name`	`name`	string
`email`	`email`	string
`phone`	`phone`	string \| null
`roles`	`roles`	string[]
`avatar_url`	`avatarUrl`	string \| null
`avatar_download_url`	`avatarDownloadUrl`	string \| null
`created_at`	`createdAt`	string

Per-item missing — UI also needs

Backend key (proposed)	UI key (camelCase)	Used by
`first_name`	`firstName`	`UsersTable.vue` (display name), filters
`last_name`	`lastName`	`UsersTable.vue`, delete-confirm dialog
`phone_number`	`phoneNumber`	`UsersTable.vue` (local format display), `UserDetailsModal.vue`
`national_code`	`nationalCode`	`UsersTable.vue`, `UserDetailsModal.vue`
`status`	`status`	enum `pending` \| `approved` \| `blocked` — `UserDetailsModal.vue` badge
`role_id`	`roleId`	`UsersTable.vue` role-change dropdown

GET `/admin/users/:id` — show user

Mock route: same file as above. Frontend query: useAdminUserQuery in src/services/query/admin-users.js. Consumed by: src/features/admin/users/components/modals/UserDetailsModal.vue (opened from the users list — not a route page).

Spec envelope

{
  "success": true,
  "message": "OK",
  "data": {
    /* user object */
  }
}

Spec fields (already implemented)

Same as list-item spec above.

Missing — UI also needs

Detail modal renders the full profile, so it needs the list-item missing fields plus the nested address and profile blocks:

Backend key (proposed)	UI key (camelCase)	Type
`address.address`	`address.address`	string
`address.province.id`	`address.province.id`	number
`address.province.name`	`address.province.name`	string
`address.city.id`	`address.city.id`	number
`address.city.name`	`address.city.name`	string
`bio`	`bio`	string
`birth_date`	`birthDate`	string (ISO)
`fa_birth_date`	`faBirthDate`	string (Jalaali)
`marital_status`	`maritalStatus`	enum
`gender`	`gender`	enum
`education_status`	`educationStatus`	enum
`seminary_level`	`seminaryLevel`	enum
`university_level`	`universityLevel`	enum
`university_name`	`universityName`	string
`field_of_study`	`fieldOfStudy`	string
`profile_completed`	`profileCompleted`	boolean

The modal flattens these (user.bio, user.birthDate, …) rather than reading from user.profile.*, so backend can either return them flat at the top level or the FE select can flatten them — whichever is easier. Document this once decided.

404 — Not found

{
  "success": false,
  "message": "Resource not found."
}

The FE findOrThrow mock throws a 404; the toast/error layer surfaces the message field — keep that key name.

POST `/admin/users` — create user

Mock route: src/services/mock/routes/admin-users.js. API client: apiAddAdminUser in src/services/api/admin-users.js. Query: useAddAdminUserMutation in src/services/query/admin-users.js. Consumed by: src/features/admin/users/pages/UserFormPage.vue (add mode).

Spec request body

{
  "name": "New Teacher",
  "email": "teacher.new@example.com",
  "phone": "+989120000000",
  "password": "StrongPass123!",
  "roles": ["teacher"]
}

What the UI form actually sends today

UserFormPage.vue posts a much richer payload (snake-cased by the HTTP interceptor before going out). The keys that map to the spec are marked with → spec; the rest have no spec equivalent yet:

FE form key (camelCase)	Wire key (snake_case)	Maps to spec?
`firstName`	`first_name`	→ derives `name` together with `lastName`
`lastName`	`last_name`	→ derives `name`
`phoneNumber`	`phone_number`	→ maps to `phone` (needs `09…` → `+98…`)
`roleId`	`role_id`	→ maps to `roles` (single id → name array)
`password`	`password`	→ `password`
`passwordConfirmation`	`password_confirmation`	(spec doesn't document, FE still sends)
`nationalCode`	`national_code`	missing
`birthDate`	`birth_date`	missing
`maritalStatus`	`marital_status`	missing
`gender`	`gender`	missing
`bio`	`bio`	missing
`provinceId`	`province_id`	missing
`cityId`	`city_id`	missing
`address`	`address`	missing
`avatarId`	`avatar_id`	missing (returned by `POST /media/upload`)

The form has no email input. The spec requires email. Either the backend should treat email as optional (auto-generate or accept null), or the FE form needs a new field. Decision pending.

Spec response — `201 Created`

{
  "success": true,
  "message": "User created.",
  "data": {
    /* user object, same shape as GET /admin/users/:id */
  }
}

The response should carry every field listed for GET /admin/users/:id (spec + "ui also needs" — list-item missing fields and the nested address/profile blocks), so the UI can refresh the cache without an extra round-trip.

Spec response — `422 Unprocessable Entity`

{
  "message": "The given data was invalid.",
  "errors": {
    "email": ["The email field is required."]
  }
}

The FE doesn't currently render per-field server errors — it would need a small hook into the form's errors ref. Out of scope for the backend, but worth flagging.

PATCH `/admin/users/:id` — update user

Mock route: same file. API client: apiUpdateAdminUser — changed from PUT to PATCH to match the spec. Query: useUpdateAdminUserMutation. Consumed by: src/features/admin/users/pages/UserFormPage.vue (edit mode).

Spec request body

{
  "name": "Renamed User",
  "roles": ["teacher", "counselor"]
}

Spec implies partial update — only the keys present are changed.

What the UI form actually sends today

Same rich payload as POST above (the same form is used in add + edit mode). Notable differences:

No password / password_confirmation in edit mode.
national_code is sent but is disabled in the UI when the user already has one.
The FE still sends only a single role via role_id, not an array via roles. Backend must either accept role_id or the FE must switch to sending roles: [name]. Decision pending.

Spec response — `200 OK`

{
  "success": true,
  "message": "User updated.",
  "data": {
    /* user object, same shape as GET /admin/users/:id */
  }
}

Same superset of fields as POST response — see GET /admin/users/:id table for the full list the UI needs back.

DELETE `/admin/users/:id` — delete user

Mock route: src/services/mock/routes/admin-users.js. API client: apiDeleteAdminUser in src/services/api/admin-users.js. Query: useDeleteAdminUserMutation in src/services/query/admin-users.js. Consumed by: src/features/admin/users/pages/UsersListPage.vue (via ConfirmModal → onConfirm).

Spec response — `200 OK`

{
  "success": true,
  "message": "User deleted.",
  "data": null
}

The FE only checks for a non-error completion (the mutation's onSuccess invalidates the list cache); the response body isn't read. No additional fields needed.

The previous mock returned a Persian success message (حذف موفق) under a data.message key. That has been replaced by the spec envelope above. If a localized toast is needed, the FE composes it client-side rather than reading data.message.

PATCH `/admin/users/:id/role` — assign roles

Mock route: src/services/mock/routes/admin-users.js. API client: apiUpdateAdminUserRole — changed from POST to PATCH to match the spec. Query: useUpdateAdminUserRoleMutation. Consumed by: src/features/admin/users/components/UsersTable.vue (role-badge dropdown → onChangeRole).

Spec request body

{
  "roles": ["missionary"]
}

The FE now sends { roles: [targetRoleName] } exactly per spec.

Spec response — `200 OK`

{
  "success": true,
  "message": "Roles updated.",
  "data": {
    /* user object, same shape as GET /admin/users/:id */
  }
}

The mock additionally writes roleId (legacy UI key) onto the user so the same record stays consistent in the in-memory store. The FE mutation only triggers invalidateUsers on success, so the envelope itself is not read.

The mock also accepts legacy bodies ({ roleId } and { role }) as a fallback in case other callers exist; new code should send { roles: [...] }.

Terms (`/terms`) — global notes

The previous FE wiring used /admin/terms paths; the spec uses /terms. All five term endpoints below moved to the /terms namespace. The admin-only auxiliary endpoints (/admin/terms/:id/clone, /admin/terms/:id/status, the term-students sub-tree, the term-courses sub-tree) stayed on /admin/terms until the backend specs them.

⚠️ Field name mismatches (apply to every terms endpoint below)

FE / mock key (camelCase)	Spec key (snake_case)	Notes
`image`	`cover_url`	FE reads `term.image`
`startDate`	`starts_at`	FE reads `term.startDate`
`endDate`	`ends_at`	FE reads `term.endDate`
`studentsCount`	(missing)	Used in list view
`coursesCount`	(missing)	Used in list view
`faStartDate` / `faEndDate`	(missing)	Jalaali-formatted display strings; FE can compute client-side, but if backend provides them the FE saves a `formatJalaaliDate` call

The mock currently writes both the spec key and the legacy UI key (coverUrl + image, startsAt + startDate, endsAt + endDate) onto every fixture and response. Required action: backend should either rename to the legacy keys, ship both, or the FE consumers (TermItem.vue, TermFormPage.vue, TermsListPage.vue) need to be migrated to read the spec keys. Decision pending.

GET `/terms` — list terms (paginated)

Mock fixture: src/services/mock/fixtures/admin-terms.js (adminTerms). Mock route: src/services/mock/routes/admin-terms.js. Frontend query: useAdminTermsListQuery. Consumed by: src/features/admin/terms/pages/TermsListPage.vue, src/features/admin/terms/components/TermItem.vue.

Spec envelope

{
  "success": true,
  "message": "OK",
  "data": {
    "items": [
      /* term objects */
    ],
    "meta": { "current_page": 1, "per_page": 20, "total": 2, "last_page": 1 }
  }
}

Per-item spec

Backend key	UI key	Type
`id`	`id`	number
`title`	`title`	string
`description`	`description`	string
`is_active`	`isActive`	boolean
`starts_at`	`startsAt`	string (ISO)
`ends_at`	`endsAt`	string (ISO)
`cover_url`	`coverUrl`	string \| null
`created_at`	`createdAt`	string (ISO)

Per-item missing — UI also needs

See "Field name mismatches" above + students_count and courses_count for the term list cards.

Query params the FE sends: per_page, page, title (free-text), status (0/1), from_date/to_date. The spec only documents per_page and active_only=1 — backend should accept the rest or drop them from the FE.

401 — Unauthenticated

{ "message": "Unauthenticated." }

The global HTTP layer already redirects to /login on 401 (see addUnauthorizeInterceptor in src/services/api/http.js).

GET `/terms/:id` — show term

Mock route: same file. Frontend query: useAdminTermQuery. Consumed by: src/features/admin/terms/pages/TermFormPage.vue (edit mode), src/features/admin/terms/components/modals/TermDetailsModal.vue.

Spec envelope

{
  "success": true,
  "message": "OK",
  "data": {
    /* term object */
  }
}

Same fields as a list item. The detail modal needs the same UI-only keys (image, startDate, endDate, studentsCount, coursesCount).

404 — Not found

{ "success": false, "message": "Resource not found." }

POST `/terms` — create term

Mock route: same file. API client: apiAddAdminTerm. Query: useAddAdminTermMutation. Consumed by: src/features/admin/terms/pages/TermFormPage.vue (add).

Spec request body

{
  "title": "Spring 2026",
  "description": "Spring term covering intro & intermediate units.",
  "is_active": true,
  "starts_at": "2026-03-20",
  "ends_at": "2026-06-20"
}

What the FE form sends today

FE key (camelCase)	Wire key	Maps to spec?
`title`	`title`	→ `title`
`description`	`description`	→ `description`
`startDate`	`start_date`	→ `starts_at` (key rename needed)
`endDate`	`end_date`	→ `ends_at` (key rename needed)
`imageId`	`image_id`	not in spec body — see "Image flow" below

Image flow (canonical): the FE uploads the file to POST /media/upload, gets a media id back, and submits it as image_id with the term create/update body. The backend should resolve image_id against the media table and populate cover_url. No separate per-resource upload endpoint exists — the previously documented POST /terms/:id/image was a mistake and has been removed.

is_active is required by the spec but the FE form doesn't expose a toggle on create (terms are forced to active). The mock defaults it to true; backend should treat is_active as optional with a default of true, or the FE needs a switch on the create form.

Spec response — `201 Created`

{
  "success": true,
  "message": "Term created.",
  "data": {
    /* term */
  }
}

The response should carry every "UI also needs" field from the list section so the FE can refresh the cache without an extra GET.

Spec errors

403 { "success": false, "message": "This action is unauthorized." }
422 { "message": "The given data was invalid.", "errors": { … } }

FE does not yet render per-field server errors.

PATCH `/terms/:id` — update term

Mock route: same file. API client: apiUpdateAdminTerm — changed from PUT to PATCH. Query: useUpdateAdminTermMutation. Consumed by: src/features/admin/terms/pages/TermFormPage.vue (edit).

Spec request body — partial

{ "title": "Spring 2026 (Revised)", "is_active": true }

What the FE form sends today

Same payload as create (the same form handles add + edit). The mock applies a true partial update — keys that are undefined in the payload are left unchanged on the stored term.

Spec response — `200 OK`

{
  "success": true,
  "message": "Term updated.",
  "data": {
    /* term */
  }
}

Spec errors

403 { "success": false, "message": "This action is unauthorized." }

DELETE `/terms/:id` — delete term

Mock route: same file. API client: apiDeleteAdminTerm. Query: useDeleteAdminTermMutation. Consumed by: src/features/admin/terms/pages/TermsListPage.vue (via ConfirmModal).

Spec response — `200 OK`

{ "success": true, "message": "Term deleted.", "data": null }

Spec errors

403 { "success": false, "message": "This action is unauthorized." }

The previous mock returned a Persian success message under data.message — replaced by the spec envelope. FE only invalidates the list cache on success and never reads the body.

Courses (`/courses`) — global notes

These spec endpoints are for offered courses (an instance of a course template tied to a term + teacher). The previous FE wiring used /admin/courses; the spec uses /courses. All six course endpoints below moved to /courses. The admin-only /admin/courses/:id/toggle-status stays where it is until the backend specs it (or until the FE migrates to PATCHing is_active).

The separate course templates API (/admin/course-templates, useAdminCourseTemplatesListQuery, etc.) is not in the spec yet and was not touched.

⚠️ Field name mismatches (apply to every courses endpoint below)

FE / mock key (camelCase)	Spec key (snake_case)	Notes
`image`	`cover_url`	FE reads `course.image`
`teacher` (nested object)	(only `teacher_id` in list)	FE list cards read `course.teacher` for name/avatar; need `teacher` nested on list too
`term` (nested object)	(only `term_id` in list)	FE list cards read `course.term?.title`; need `term` nested on list too
`template` (nested object)	(missing entirely)	FE-only concept (course-template link)
`templateId`	(missing)	Course-template id
`prerequisitesCount`	(missing)	Number badge on list cards
`startDate` / `endDate`	(missing — read from `term.starts_at`/`ends_at`)	List cards currently store dates flat on the course; the FE could derive from the nested `term` instead

The mock currently writes both the spec key and the legacy UI key (coverUrl + image) and includes nested term/teacher objects on both list and detail responses so the existing list cards keep rendering. Required action: backend should either include the nested objects + UI-only counters on every course response, or the FE needs migration. Decision pending.

Nested `teacher` shape

The spec's detail response nests a full teacher user object using the top-level user spec (name, email, phone, roles, avatar_url, …). The UI cards already read course.teacher.firstName / course.teacher.lastName — so this is yet another instance of the cross-cutting name vs first_name/last_name problem. The mock writes both forms on the nested teacher.

GET `/courses` — list courses (paginated)

Mock fixture: src/services/mock/fixtures/admin-courses.js (adminOfferedCourses). Mock route: src/services/mock/routes/admin-courses.js. Frontend query: useAdminCoursesListQuery. Consumed by: src/features/admin/courses/pages/CoursesListPage.vue, src/features/admin/courses/components/CourseItem.vue.

Spec envelope

{
  "success": true,
  "message": "OK",
  "data": {
    "items": [
      /* course objects */
    ],
    "meta": { "current_page": 1, "per_page": 20, "total": 1, "last_page": 1 }
  }
}

Per-item spec

Backend key	UI key	Type
`id`	`id`	number
`term_id`	`termId`	number
`teacher_id`	`teacherId`	number
`title`	`title`	string
`description`	`description`	string
`capacity`	`capacity`	number
`is_active`	`isActive`	boolean
`cover_url`	`coverUrl`	string \| null

Per-item missing — UI also needs

See "Field name mismatches" above. The list cards specifically need term (nested with at least id, title), teacher (nested with id + the user-shape so firstName/lastName/name are available), prerequisitesCount, and image (or the FE migrates to cover_url). template / templateId are FE-only — backend may ignore.

Query params

Spec documents term_id and per_page. FE additionally sends page, title (free-text), status (0/1), from_date, to_date. Backend should accept or the FE filter set needs trimming.

GET `/courses/:id` — show course

Mock route: same file. Frontend query: useAdminCourseQuery. Consumed by: src/features/admin/courses/components/modals/CourseDetailsModal.vue (opened from the list — not a route page), src/features/admin/courses/pages/CourseTemplateFormPage.vue (when editing offered courses via the unified form).

Spec envelope

{
  "success": true,
  "message": "OK",
  "data": {
    "id": 1,
    "term_id": 1,
    "teacher_id": 2,
    "title": "…",
    "description": "…",
    "capacity": 50,
    "is_active": true,
    "cover_url": "…",
    "term": {
      "id": 1,
      "title": "…",
      "description": "…",
      "is_active": true,
      "starts_at": "…",
      "ends_at": "…",
      "cover_url": "…",
      "created_at": "…"
    },
    "teacher": {
      "id": 2,
      "name": "John Teacher",
      "email": "…",
      "phone": "…",
      "roles": ["teacher"],
      "avatar_url": null,
      "avatar_download_url": null,
      "created_at": "…"
    }
  }
}

Missing — UI also needs

Same superset as list-item missing (template/templateId, prerequisitesCount, image, nested teacher carrying firstName/lastName/fullName).

404 — Not found

{ "success": false, "message": "Resource not found." }

POST `/courses` — create course

Mock route: same file. API client: apiAddAdminCourse. Query: useAddAdminCourseMutation. Consumed by: course-creation form (offered-course branch of the existing course form page / modal).

Spec request body

{
  "term_id": 1,
  "teacher_id": 2,
  "title": "Intro to Theology",
  "description": "Foundational course.",
  "capacity": 50,
  "is_active": true
}

What the FE form sends today

FE key (camelCase)	Wire key	Maps to spec?
`termId`	`term_id`	→ `term_id`
`teacherId`	`teacher_id`	→ `teacher_id`
`title`	`title`	→ `title`
`description`	`description`	→ `description`
`capacity`	`capacity`	→ `capacity`
`isActive`	`is_active`	→ `is_active`
`templateId`	`template_id`	does not exist in spec — FE-only
`imageId`	`image_id`	not in spec body — see "Image flow" below

Image flow (canonical): the FE uploads the file to POST /media/upload, gets a media id back, and submits it as image_id with the course create/update body. Backend resolves image_id against the media table and populates cover_url. No separate per-resource upload endpoint exists — the previously documented POST /courses/:id/image was a mistake and has been removed.

Spec response — `201 Created`

{
  "success": true,
  "message": "Course created.",
  "data": {
    /* course */
  }
}

The response should carry every list-item "UI also needs" field (nested term, nested teacher, image, template, templateId, prerequisitesCount) so the FE cache refresh has all it needs.

Spec errors

403 { "success": false, "message": "This action is unauthorized." }
422 { "message": "The given data was invalid.", "errors": { … } }

PATCH `/courses/:id` — update course

Mock route: same file. API client: apiUpdateAdminCourse — changed from PUT to PATCH. Query: useUpdateAdminCourseMutation.

Spec request body — partial

{ "title": "Intro to Theology (v2)", "capacity": 60 }

What the FE form sends today

Same payload shape as create (the same form handles add + edit). The mock now applies a true partial update — only keys present in the payload are written.

Spec response — `200 OK`

{
  "success": true,
  "message": "Course updated.",
  "data": {
    /* course */
  }
}

DELETE `/courses/:id` — delete course

Mock route: same file. API client: apiDeleteAdminCourse. Query: useDeleteAdminCourseMutation. Consumed by: src/features/admin/courses/pages/CoursesListPage.vue (via ConfirmModal).

Spec response — `200 OK`

{ "success": true, "message": "Course deleted.", "data": null }

Previous mock returned a Persian message under data.message — replaced by the envelope. The FE only invalidates the list cache on success.

Sessions (`/sessions`) — global notes

The previous FE wiring used /admin/sessions; the spec uses /sessions. All six session endpoints below moved to /sessions. The admin-only /admin/sessions/:id/toggle-status and /admin/sessions/:sessionId/attendances stay where they are until the backend specs them.

⚠️ Structural mismatch: course vs course-template

The spec says a session belongs to an offered course (course_id). The FE models sessions as belonging to a course template (course_template_id), where a single session can be reused across multiple terms/offered courses (session.used_in_terms).

The mock now stores both courseId (spec) and courseTemplate (UI nested object). When the FE creates a session via course_template_id, the mock auto-derives course_id from the first offered course with that template (best-effort).
Backend should decide: either expose course_template_id on the session endpoints, or the FE needs to migrate to picking an offered course directly when creating a session. Decision pending.

⚠️ Enum mismatch: `type` (spec) vs `session_type` (FE)

The mock derives type from session_type like this (see SESSION_TYPE_TO_SPEC in the fixture):

FE `session_type`	Spec `type`
`in_person`	`offline`
`online`	`online`
`video` / `audio` / `text` / `slide` / `pdf`	`content`

The FE form picks from the 7-value enum and renders different config blocks per value (SessionFormPage.vue). Backend should either:

Adopt the 7-value enum and map to its internal 3-value domain server-side, or
Add a sub-type column (session_subtype etc.) so the FE can still pick video/audio/pdf while type stays in the 3-value spec set.

Decision pending.

⚠️ Flat fields vs `session_config`

The spec flattens what the FE keeps nested in session_config:

Spec key (top-level)	FE key (nested)
`starts_at`	`session_config.start_time`
`location`	`session_config.location` (in_person)
`link`	`session_config.meeting_link` (online)
(missing)	`session_config.platform` (online)
(missing)	`session_config.min_watched_percent` (video/audio)
(missing)	`session_config.min_read_percent` (text/slide/pdf)
(missing)	`session_config.must_complete_before_next`

The mock now writes the spec keys flat AND keeps the legacy session_config nested block so SessionDetailsModal.vue (which reads session.session_config.*) keeps rendering. Required action: backend should either accept the nested session_config and return it back, or the FE detail modal needs to be migrated to read the flat keys + the missing config knobs need a new home (probably a JSON column).

Other UI-only fields the spec doesn't cover

image, duration_minutes, order, materials, used_in_terms, course_template (nested). The FE list cards and detail modal all read these — backend should include them or the FE needs migration. The mock keeps them all.

GET `/sessions` — list sessions (paginated)

Mock fixture: src/services/mock/fixtures/admin-sessions.js (adminSessions). Mock route: src/services/mock/routes/admin-sessions.js. Frontend query: useAdminSessionsListQuery. Consumed by: src/features/admin/sessions/pages/SessionsListPage.vue, src/features/admin/sessions/components/SessionItem.vue.

Spec envelope

{
  "success": true,
  "message": "OK",
  "data": {
    "items": [
      /* session objects */
    ],
    "meta": { "current_page": 1, "per_page": 20, "total": 1, "last_page": 1 }
  }
}

Per-item spec

Backend key	UI key	Type
`id`	`id`	number
`course_id`	`courseId`	number
`title`	`title`	string
`description`	`description`	string
`type`	`type`	enum: `online` \| `offline` \| `content`
`starts_at`	`startsAt`	string (ISO with tz)
`location`	`location`	string \| null
`link`	`link`	string \| null

Per-item missing — UI also needs

See "Structural", "Enum", and "Flat vs session_config" callouts above. Concretely the list card reads: image, courseTemplate.title, durationMinutes, sessionType / sessionTypeFa, usedInTerms[]. None of those are in the spec yet.

Query params

Spec documents course_id + per_page. FE additionally sends title, course_template_id, session_type, from_date, to_date, page. Backend should accept or the FE filter set needs trimming.

GET `/sessions/:id` — show session

Mock route: same file. Frontend query: useAdminSessionQuery. Consumed by: src/features/admin/sessions/components/modals/SessionDetailsModal.vue, src/features/admin/sessions/pages/SessionFormPage.vue (edit mode).

Spec envelope

{
  "success": true,
  "message": "OK",
  "data": {
    "id": 1,
    "course_id": 1,
    "title": "…",
    "description": "…",
    "type": "online",
    "starts_at": "…",
    "location": null,
    "link": "…",
    "media": [
      {
        "id": 15,
        "collection_name": "attachments",
        "file_name": "…",
        "mime_type": "…",
        "file_size": 204800,
        "url": "…",
        "download_url": "…"
      }
    ],
    "course": {
      /* full offered-course object, same shape as GET /courses/:id flat fields */
    }
  }
}

Missing — UI also needs

Detail modal needs: session_config.* (with the config knobs not in spec — platform, min_watched_percent, etc.), course_template (nested), image, duration_minutes, order, materials[], used_in_terms[]. The mock writes all of them.

The spec's media[] and the FE's materials[] are different arrays — media is the new attachments collection (PDFs, slides, recordings); materials is a legacy FE concept. Backend can either collapse them into one field or keep both — flagged for decision.

404 — Not found

{ "success": false, "message": "Resource not found." }

POST `/sessions` — create session

Mock route: same file. API client: apiAddAdminSession. Query: useAddAdminSessionMutation. Consumed by: src/features/admin/sessions/pages/SessionFormPage.vue (add).

Spec request body

{
  "course_id": 1,
  "title": "Week 1 — Overview",
  "description": "Opening session.",
  "type": "online",
  "starts_at": "2026-03-25T18:00:00+03:30",
  "location": null,
  "link": "https://meet.example.com/abc"
}

What the FE form sends today

FE key (camelCase)	Wire key	Maps to spec?
`title`	`title`	→ `title`
`description`	`description`	→ `description`
`courseTemplateId`	`course_template_id`	not in spec — see structural callout
`sessionType`	`session_type`	maps to spec `type` via the table above
`durationMinutes`	`duration_minutes`	missing in spec
`order`	`order`	missing in spec
`sessionConfig.startTime`	`session_config.start_time`	maps to spec `starts_at`
`sessionConfig.location`	`session_config.location`	maps to spec `location`
`sessionConfig.meetingLink`	`session_config.meeting_link`	maps to spec `link`
`sessionConfig.platform`	`session_config.platform`	missing in spec
`sessionConfig.minWatchedPercent`	`session_config.min_watched_percent`	missing in spec
`sessionConfig.minReadPercent`	`session_config.min_read_percent`	missing in spec
`sessionConfig.mustCompleteBeforeNext`	`session_config.must_complete_before_next`	missing in spec
`imageId`	`image_id`	media id from `POST /media/upload`; backend should set `cover_url`
`materials`	`materials[]`	array of media ids (each from `POST /media/upload`); backend attaches them as session media; overlaps with spec `media[]` — see callout

The mock accepts both naming conventions on input. The FE form needs a flat course_id selector to fully match the spec (or backend must accept course_template_id).

Spec response — `201 Created`

{
  "success": true,
  "message": "Session created.",
  "data": {
    /* session */
  }
}

Spec errors

422 { "message": "The given data was invalid.", "errors": { "course_id": [...], "title": [...], "type": [...] } }

PATCH `/sessions/:id` — update session

Mock route: same file. API client: apiUpdateAdminSession — changed from PUT to PATCH. Query: useUpdateAdminSessionMutation.

Spec request body — partial

{ "title": "…", "starts_at": "…" }

What the FE sends today

Same payload shape as create. The mock now applies a true partial update — only keys present in the payload are written.

Spec response — `200 OK`

{
  "success": true,
  "message": "Session updated.",
  "data": {
    /* session */
  }
}

DELETE `/sessions/:id` — delete session

Mock route: same file. API client: apiDeleteAdminSession. Query: useDeleteAdminSessionMutation.

Spec response — `200 OK`

{ "success": true, "message": "Session deleted.", "data": null }

Previous mock returned a Persian message under data.message — replaced by the envelope. The FE only invalidates the list cache on success.

46 KiB Raw Blame History

Backend API — response model gaps

⚠️ Cross-cutting: name vs first_name / last_name

POST /media/upload — single-step media upload (canonical)

Flow

Mock request

Mock response

How the resource body references the upload

GET /auth/me — current user

Spec (already implemented)

Missing — UI also needs

Suggested response shape

GET /admin/users — list users (paginated)

Spec envelope

Per-item spec (already implemented)

Per-item missing — UI also needs

GET /admin/users/:id — show user

Spec envelope

Spec fields (already implemented)

Missing — UI also needs

404 — Not found

POST /admin/users — create user

Spec request body

What the UI form actually sends today

Spec response — 201 Created

Spec response — 422 Unprocessable Entity

PATCH /admin/users/:id — update user

Spec request body

What the UI form actually sends today

Spec response — 200 OK

DELETE /admin/users/:id — delete user

Spec response — 200 OK

PATCH /admin/users/:id/role — assign roles

Spec request body

Spec response — 200 OK

Terms (/terms) — global notes

⚠️ Field name mismatches (apply to every terms endpoint below)

GET /terms — list terms (paginated)

Spec envelope

Per-item spec

Per-item missing — UI also needs

401 — Unauthenticated

GET /terms/:id — show term

Spec envelope

404 — Not found

POST /terms — create term

Spec request body

What the FE form sends today

Spec response — 201 Created

Spec errors

PATCH /terms/:id — update term

Spec request body — partial

What the FE form sends today

Spec response — 200 OK

Spec errors

DELETE /terms/:id — delete term

Spec response — 200 OK

Spec errors

Courses (/courses) — global notes

⚠️ Field name mismatches (apply to every courses endpoint below)

Nested teacher shape

GET /courses — list courses (paginated)

Spec envelope

Per-item spec

Per-item missing — UI also needs

Query params

GET /courses/:id — show course

Spec envelope

Missing — UI also needs

404 — Not found

POST /courses — create course

Spec request body

What the FE form sends today

Spec response — 201 Created

Spec errors

PATCH /courses/:id — update course

Spec request body — partial

What the FE form sends today

Spec response — 200 OK

DELETE /courses/:id — delete course

46 KiB

Raw Blame History

⚠️ Cross-cutting: `name` vs `first_name` / `last_name`

POST `/media/upload` — single-step media upload (canonical)

GET `/auth/me` — current user

GET `/admin/users` — list users (paginated)

GET `/admin/users/:id` — show user

POST `/admin/users` — create user

Spec response — `201 Created`

Spec response — `422 Unprocessable Entity`

PATCH `/admin/users/:id` — update user

Spec response — `200 OK`

DELETE `/admin/users/:id` — delete user

Spec response — `200 OK`

PATCH `/admin/users/:id/role` — assign roles

Spec response — `200 OK`

Terms (`/terms`) — global notes

GET `/terms` — list terms (paginated)

GET `/terms/:id` — show term

POST `/terms` — create term

Spec response — `201 Created`

PATCH `/terms/:id` — update term

Spec response — `200 OK`

DELETE `/terms/:id` — delete term

Spec response — `200 OK`

Courses (`/courses`) — global notes

Nested `teacher` shape

GET `/courses` — list courses (paginated)

GET `/courses/:id` — show course

POST `/courses` — create course

Spec response — `201 Created`

PATCH `/courses/:id` — update course

Spec response — `200 OK`

DELETE `/courses/:id` — delete course

Spec response — `200 OK`

Sessions (`/sessions`) — global notes

⚠️ Enum mismatch: `type` (spec) vs `session_type` (FE)

⚠️ Flat fields vs `session_config`

GET `/sessions` — list sessions (paginated)

GET `/sessions/:id` — show session

POST `/sessions` — create session

Spec response — `201 Created`

PATCH `/sessions/:id` — update session

Spec response — `200 OK`

DELETE `/sessions/:id` — delete session

Spec response — `200 OK`