02 — User Personas (Homework Module)
- 1. Teacher (subject/class teacher) — primary creator & grader
- 2. Student — single-time submitter
- 3. Parent — read-only monitor
- 4. Org Admin — overseer
- 5. Platform Admin (cross-tenant support)
- 6. Role → homework-appearance matrix
Roles, goals, permissions, and expected behavior for every consumer of the Homework module. Permission values are exact from
rbac/permissions.constants.ts(ALL_PERMISSIONS). Homework endpoints today require only a valid JWT (homework.controller.ts:19@UseGuards(JwtAuthGuard)) — nohomework.*permission exists (OQ-9 of 01). Files endpoints are the exception:file.upload/file.read/file.delete(files.controller.ts:30,44,50,56,67).
1. Teacher (subject/class teacher) — primary creator & grader
| Attribute | Value |
|---|---|
| Frequency | Daily; creates 1–5 homework per class per week, grades in batches |
| Permissions | JWT only for homework CRUD/submit/grade today (homework.controller.ts:19); file.upload for attachments (files.controller.ts:30) |
| Goal | Assign homework with a clear due date; see submission status per student; grade with marks + remarks; re-grade when a student asks |
| Pain points | Late submissions mixed with on-time ones (no server late flag — OQ-1); repeated grading accidentally double-emits events; no bulk grade endpoints |
| Expected | Class-filtered homework list sorted by due date (homework.repository.ts:20); submission list per homework; grade sheet that persists on error (never lose typed marks) |
| Mental model | "I post it, they submit once, I mark it." |
| Core jobs | POST /homework (create), GET /homework/class/:classId (list), GET /homework/:id/submissions (grade sheet), PATCH /homework/:id/submissions/:submissionId/grade (grade), PATCH /homework/:id (edit), DELETE /homework/:id (remove) |
2. Student — single-time submitter
| Attribute | Value |
|---|---|
| Frequency | Daily check; submit before due date |
| Permissions | JWT only; no special student scoping server-side (any JWT may submit any homework with any studentId — submit() trusts dto.studentId, homework.service.ts:83-112) |
| Goal | See pending homework for my class, submit exactly once with optional attachment, see my marks + teacher remarks |
| Pain points | No per-student "my homework" endpoint (PLAN.md:67 is not implemented — OQ-6); duplicate tap on submit → 409; no server-side late flag |
| Expected | My-class list resolved via student profile classId → GET /homework/class/:classId; submit button that disables after success; grade feedback row when status: 'graded' (homework-submission.schema.ts:24) |
| Mental model | "Submit once, done. Teacher's feedback appears in the same place." |
| Core jobs | GET /homework/class/:classId, GET /homework/:id, POST /homework/:id/submit, GET /files/:id/download |
3. Parent — read-only monitor
| Attribute | Value |
|---|---|
| Frequency | Weekly; check pending/graded homework of children |
| Permissions | student.read (role seed intent, role.schema.ts); no homework API exists for parents — "parent view" is (planned) (IMPLEMENTATION_PLAN.md:227) |
| Goal | Know what's assigned, whether the child submitted, and the grade |
| Pain points | Nothing to call today (OQ-5); relies on notifications (planned) and the child's device |
| Expected | Deep link to homework detail from notification; read-only rendering (no submit/grade controls) |
| Mental model | "Is it done, and what did they get?" |
| Core jobs | (planned) GET /homework/class/:classId + GET /homework/:id read-only; today: notification feed only |
4. Org Admin — overseer
| Attribute | Value |
|---|---|
| Frequency | On demand (complaints, audits) |
| Permissions | JWT only; audit.read exists in ALL_PERMISSIONS (permissions.constants.ts:54) but no homework admin surface |
| Goal | See what homework exists in a class, who graded what, intervene (edit/delete) |
| Pain points | No dashboard/aggregate homework endpoints (OQ-7) |
| Expected | Class homework list + submission list via the same generic endpoints; delete as cleanup tool |
| Mental model | "Same screens as a teacher, with delete power." |
5. Platform Admin (cross-tenant support)
| Attribute | Value |
|---|---|
| Permissions | isPlatformAdmin bypasses tenant scope in scopedFilter (base.repository.ts:21-23) |
| Behavior | Can read any tenant's homework via the same endpoints; support-diagnostics only |
6. Role → homework-appearance matrix
| Value | Teacher | Student | Parent | Org admin |
|---|---|---|---|---|
| Create homework form | ✓ | — | — | ✓ |
| Edit / delete homework | ✓ | — | — | ✓ |
| Class homework list | ✓ (own classes) | ✓ (my class, resolved) | (planned) | ✓ |
| Submission form | — | ✓ | — | — |
| Grade sheet | ✓ | — | — | — |
| Grade feedback view | ✓ | ✓ (own only, client-gated) | (planned) | ✓ |
| Attachments upload | ✓ (file.upload) | ✓ (file.upload) | — | ✓ |
| Attachment download | ✓ (file.read) | ✓ (file.read) | (planned) | ✓ |
Honesty note: the server does not distinguish these roles on homework endpoints today (JWT-only guard, OQ-9). The matrix is the intended product behavior the client should implement with role-based UI gating (hide create/grade controls for students), which becomes authoritative the moment
@Permissions('homework.*')land.