01 — Product Overview (Homework Module)

• 1. Purpose
• 2. Business goals
• 3. User goals
• 4. Stakeholders
• 5. Why this exists
• 6. Dependencies
• 7. Success metrics
• 8. Edge cases
• 9. Assumptions (module)
• 10. Open questions (module-level; global ledger in 00-shared/12)
• 11. Glossary (this module)

StudyLyon — multi-tenant ERP / School Management API. This package designs the Homework module client (Flutter, forward-looking spec) against the implemented NestJS backend. All endpoints, DTO fields, schemas, domain events, queue routes, and wire contracts are derived directly from src/modules/homework/**, src/modules/files/**, src/modules/notifications/**, src/infrastructure/bullmq/**, src/modules/rbac/permissions.constants.ts, studylyon-blueprint/04-Modules/Homework.md, PLAN.md §6, and docs/IMPLEMENTATION_PLAN.md. No feature is invented; gaps are flagged in Assumptions & Open Questions.

1. Purpose

Homework is the assignment lifecycle: a teacher creates an assignment for one class and subject with a due date and optional file attachments; a student submits work (remarks + optional attachments) exactly once per homework; the teacher grades the submission with marks + remarks; the parent sees pending and graded homework (read-only; no parent API exists yet — OQ-5). Every state change emits a domain event that is routed over BullMQ to in-app notifications.

2. Business goals

3. User goals

• Teacher: create a homework with a due date and attachments in seconds; see which students submitted; grade with marks + remarks and re-grade when needed.
• Student: see pending homework for my class; submit exactly once (with optional attachment); see my marks and teacher feedback.
• Parent (read): follow child's pending homework and grades.
• Org admin: oversee homework activity; nothing admin-specific exists in the API (OQ-7).

4. Stakeholders

Class teachers, students, parents, subject coordinators (read), org admin, notification delivery pipeline (in-app worker), audit/compliance (event log), QA + design + engineering.

5. Why this exists

Homework is a daily, high-frequency academic workflow. The backend implements the full CRUD + submit + grade loop with strict one-submission-per-student semantics; the client must make this loop frictionless (upload progress, due-date awareness, grade feedback) without ever violating the server's invariants (no resubmission, no marks editing without a grade call).

6. Dependencies

7. Success metrics

• Homework creation → visible to class < 2 s (create + list round-trip).
• Submission success rate ≥ 99.5% of attempts (excl. intended 409 duplicates).
• Duplicate-submission 409 handled gracefully 100% of the time (never a crash/blank).
• Graded feedback visible immediately after PATCH …/grade success.
• Zero cross-tenant leaks in lists/details (tenant scope on every query).

8. Edge cases

• Duplicate submission → 409 DUPLICATE_RESOURCE "Already submitted." (homework.service.ts:92) — also structurally enforced by unique index (homework-submission.schema.ts:37-40).
• Submit to unknown homework → 404 RESOURCE_NOT_FOUND "Homework not found." (homework.service.ts:87,47).
• Grade unknown submission → 404 "Submission not found." (homework.service.ts:126,135).
• Update/delete unknown homework → 404 (homework.service.ts:56-58,71-72).
• Late submission: the server does not check dueDate on submit — late submissions are accepted (OQ-1). The UI must show a late badge derived client-side.
• Regrading: PATCH …/grade is repeatable; each call overwrites marks/remarks, resets gradedAt, and emits another HomeworkGraded (OQ-2).
• Closed homework: status: 'closed' is settable via update (homework.dto.ts:55-58), but nothing enforces it — submit/grade still work on closed homework (OQ-3).
• Marks validation: GradeSubmissionDto.marks has no class-validator decorator (submission.dto.ts:20-21) — negative/non-numeric values are not blocked at the DTO layer (OQ-4).
• Delete homework: soft-delete only (base.repository.ts:68-74); submissions are not cascaded (no cascade in remove(), homework.service.ts:70-81).
• Attachment limits: no size/mime limits in code (files.controller.ts:39, files.service.ts:27-46) — client must enforce (see 14_QA_Checklist.md).
• Update semantics: only title, description, attachments, dueDate, status are updatable; classId/subjectId/teacherId are immutable after create (homework.dto.ts:35-58 vs 4-33).
• findByClass sort: newest due date first (dueDate: -1, homework.repository.ts:20).

9. Assumptions (module)

• Mobile client is forward-looking: backend is complete; this package is the UI-side spec (00-shared/12 A1).
• "Student sees homework scoped to my class" (PLAN.md:67, 6.2) has no dedicated endpoint — the client resolves the student's classId from the Students module profile, then calls GET /homework/class/:classId (OQ-6).
• attachments: string[] on homework and submissions are file record ids returned by POST /files/upload (files.service.ts:27-46); the blueprint's storage path sl/{tenantId}/homework/{uuid} (Homework.md:58) is plan-only — actual storage names files ${randomUUID()}--${originalname} (files.service.ts:31).
• The blueprint's domain-event table (Homework.md:37-41: HomeworkAssigned, HomeworkSubmitted) is stale; the code emits HomeworkCreated/Updated/Deleted/ Submitted/Graded (homework.service.ts:34,59,73,99,136). Code wins.
• Blueprint "Reminders and due alerts" (Homework.md:17) and "Overdue detection via scheduled job" (Homework.md:60) are not implemented — no scheduler/worker exists (OQ-1).
• HomeworkCreated/Updated/Submitted/Graded are routed to the in-app queue (event-queue-map.ts:22-25), but NotificationType enum (notification.schema.ts:7-12) does not contain these values — notification persistence currently fails Mongoose enum validation; treat the in-app notification surface as (planned) until the enum is extended (OQ-8).
• Homework endpoints are guarded only by JwtAuthGuard (homework.controller.ts:19) — no @Permissions() metadata and no homework.* permissions exist (permissions.constants.ts:1-97). Any authenticated user can call every homework endpoint today (OQ-9).

10. Open questions (module-level; global ledger in 00-shared/12)

11. Glossary (this module)