Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

09 — User Behaviour (Homework Module)

Expected behaviour (derived from server semantics + shared interaction rules), the common mistakes users make with these screens, and the UX countermeasures.

1. Expected behaviour (server-contract-driven)

  • Submission is exactly-once. The server refuses a second submission with 409 "Already submitted." (homework.service.ts:88-92) and the schema enforces it with a unique index (homework-submission.schema.ts:37-40). The UI must treat "already submitted" as done, not as an error — a student who submits from two devices, or double-taps, must land on an informative state.
  • Late submission is accepted. No due-date check exists in submit() (homework.service.ts:83-112) — the UI must never hard-block a submit, only inform (OQ-1). The late badge is client-computed until the server provides a flag.
  • Grading overwrites. Re-grading replaces marks/remarks and resets gradedAt (homework.service.ts:127-134). Teachers should be warned before overwriting; students should see the newest grade only.
  • Homework deletion hides the homework (soft-delete, base.repository.ts:68-74) but keeps submissions — after delete, the homework detail 404s; teachers should be told submissions are retained server-side.
  • Update is partial. Only title/description/attachments/dueDate/status change (homework.dto.ts:35-58) — a teacher who expects to move homework to another class will fail; the UI disables those fields.
  • Lists are class-scoped and due-date-sorted (homework.repository.ts:19-20) — the "due soon" grouping the UI shows matches the sort.
  • No role enforcement on the server (OQ-9): any JWT can create/grade. The client gates by role; when perms land, gates stay.

2. Common mistakes & countermeasures

MistakeRelatedUX countermeasure
Double-tap "Submit" → 409submitdisable button on first tap; map 409 → "Already submitted" info banner, never red error
Submitting from two devicessubmitthe 409 path above; submission state always re-read from server on screen open
Teacher grades the wrong studentgradegrade sheet shows student avatar+name header and the homework title; require explicit row selection
Typing marks like "20/25"gradenumeric-only keyboard + input formatter (digits only); "Out of {max}" hint
Setting a due date in the pastcreatedate picker min = today; edit form warns if past date selected
Expecting to move homework to another classeditfields disabled + helper "Class/subject cannot be changed"
Deleting homework thinking it vanishes submissionsdeleteconfirm dialog copy: "Students' submissions are kept."
Losing typed grade on network errorgradeform state preserved on 5xx; retry offered; never navigate away on failure
Upload stuck mid-flight (network loss)attachmentsper-file failed state + retry; snackbar guidance; no silent corruption (10 §2)
Closing app mid-uploadattachmentspending uploads shown on return (proposed); uploads not resumed (B7)

3. Power & new users

  • Power teacher: keyboard N (new homework), batch grading flow "Next ungraded" (proposed); pastes marks lists (tab-separated → client fills rows, (proposed)).
  • New student: first run — "Homework" tab shows empty state + explanation "Assignments from your teachers will appear here".

4. Mobile & a11y users

  • One-thumb: primary CTA full-width bottom-ish; FAB reachable.
  • TalkBack/VoiceOver: full submit + grade flows walkable; upload progress announced; late badge read with text, not color.
  • Dynamic type 200%: cards reflow, maxLines only on labels.
  • Reduced motion: no shake/stagger; status changes = fade.

5. Cross-device & conflict

  • Student submits on phone; teacher grades on web — student's next open of the detail shows the grade (no WS homework topic yet; re-fetch on focus + pull-to-refresh).
  • Two teachers grade the same submission concurrently: last write wins (server updateById $set, homework.service.ts:127); the second grader's sheet shows the current grade on load (re-fetch before save if stale — compare gradedAt).

6. Interrupted sessions & retries

  • App killed mid-submit: on restart, the detail re-fetches; if the submission landed, the 409 path shows "Already submitted"; if not, the form restores draft (proposed).
  • Upload interrupted: per-file retry (new upload); no resume (B7).
  • 429 (uploads/rapid actions): countdown, no auto-retry (00-shared/07 §4).
  • Session expiry mid-flow: sessionExpired overlay → login → return to the same screen (state preserved where safe, 10 §3).

7. Abandonment

  • Create form abandoned → draft kept locally (client memo, (proposed)); "Discard?" prompt on back with content.
  • Submit form abandoned → draft (remarks + picked files) kept; badge on the card "Draft" (proposed).
  • Grade sheet abandoned mid-entry → typed values kept until sheet closed deliberately.

8. Frustration points → UX treatments (summary)

FrustrationTreatment
"Already submitted" shown as red errorRe-map to info banner + disable submit
Can't tell if my homework is lateclient-computed LateBadge with icon+text
No "my homework" list (OQ-6)resolve classId from profile; cache it (TTL 24 h)
Marks has no server bounds (OQ-4)client validation + "Out of {max}" hint; flag server fix
Grading overwrites silently (OQ-2)regrade confirm + overwrite banner
Homework deleted → submissions kept (no cascade)explain in delete confirm; teacher can still see submissions? (no — list 404s with homework; document in OQ)

9. Adoption path (holistic)

P0 (client): list → detail → create → submit → grade → feedback, all server-confirmed. P1: late badges, regrade UX, upload progress polish, drafts. P2 (planned): GET /homework student endpoint (PLAN.md:67), parent read view (IMPLEMENTATION_PLAN.md:227), bulk assign, plagiarism check, homework emails (IMPLEMENTATION_PLAN.md Phase 4), WS homework topic, push notifications (00-shared/12 B3).