01 — Product Overview (Teachers Module)

• 1. Purpose
• 2. Module boundary: Teachers vs Staff
• 3. Teacher lifecycle (end-to-end)
• 4. Subject & class assignment — two mechanisms (important)
• 5. Permissions reality (read carefully)
• 6. Events & side-effects
• 7. Dependencies
• 8. Business goals
• 9. Success metrics
• 10. Edge cases (derived)
• 11. Assumptions (module)
• 12. Open questions (module-level)

StudyLyon — multi-tenant ERP / School Management API. This package designs the Teachers module client (Flutter, forward-looking spec) against the implemented NestJS backend. All endpoints, DTO fields, schemas, events, and business rules are derived directly from src/modules/teachers/**, src/modules/academics/** (subject assignments), src/modules/staff/**, src/modules/rbac/**, and src/infrastructure/**. No feature is invented; gaps are flagged in Assumptions & Open Questions and marked (planned) / (proposed).

1. Purpose

Teachers is the teaching-profile domain. It answers "who teaches here" for an institution: the employment record of every instructor (linked to a User identity), their department/designation, employment status, qualifications, the subjects they teach and the classes they are class-teacher for, plus — via the subject_assignments collection owned by the Academics module — the per-academic-year matrix of which teacher teaches which subject in which class.

2. Module boundary: Teachers vs Staff

The backend splits "people" into two parallel profile documents that share the same shape for employment basics (userId, employeeNumber, departmentId, designationId, joiningDate) but diverge on domain specifics:

A single users record may own a teacher profile and a staff profile (e.g. a teacher who also works the front office): RELATIONSHIPS.md:32-33 ("A single users record may own multiple profiles"). Both can even coexist with the same userId because they are separate collections with separate uniqueness scopes. The client must treat them as two different records — the Teachers screen never renders Staff records, and vice versa.

3. Teacher lifecycle (end-to-end)

User account created (Users module)
   → Teacher profile created   POST /teachers          [TeacherCreated → in-app]
      → Subjects + classes assigned (two mechanisms, §4)
      → Day-to-day teaching (timetable, attendance, homework — other modules)
      → Profile edited          PATCH /teachers/:id    [TeacherUpdated → audit]
      → Deactivated             DELETE /teachers/:id   [TeacherDeleted → audit]
         (soft-delete: isDeleted=true, queries exclude; PLAN.md:146)

Deactivation is permanent from the client's perspective — there is no re-activation endpoint. DELETE sets isDeleted: true + deletedAt + deletedBy (base.repository.ts:68-74); every subsequent query excludes the record (base.repository.ts:20-30).

4. Subject & class assignment — two mechanisms (important)

The backend has two parallel, non-synchronized ways to link a teacher to subjects/classes:

1. Profile arrays — teacher.subjects[] (ref Subject) and teacher.classTeacherFor[] (ref Class), set via POST /teachers or PATCH /teachers/:id (create-teacher.dto.ts:44-52, teacher.schema.ts:44-48). These are denormalized profile data — there is no server logic that reads them for scheduling.
2. subject_assignments collection — one document per (teacher, subject, class, academicYear) triple: subject-assignment.schema.ts:9-19, managed by POST /subject-assignments, GET /subject-assignments/by-class/:classId, GET /subject-assignments/by-teacher/:teacherId, DELETE /subject-assignments/:id (subject-assignment.controller.ts:21-38). This is the authoritative teaching matrix per academic year (RELATIONSHIPS.md:82-92).

Additionally classes.classTeacherId exists (class.schema.ts:28) as a third class-teacher reference. The three stores are not kept in sync by any code — the client must decide which is canonical for which surface (see OQ-4).

5. Permissions reality (read carefully)

• permissions.constants.ts contains no teacher.* permissions — the teachers endpoints carry none of staff.*, department.manage, designation.manage either (permissions.constants.ts:19-24).
• TeacherController is guarded only by @UseGuards(JwtAuthGuard) (teacher.controller.ts:18-21). The global RbacGuard (app.module.ts:131) passes any request that carries no @Roles/@Permissions metadata (rbac.guard.ts:29).
• The default teacher role ships with ['student.read','attendance.mark','attendance.edit'] (role.schema.ts:26-32) — nothing that lets a teacher read their own profile via GET /teachers/:id is gated server-side; the client must enforce "teacher sees own record only" in UI/routing (OQ-1).
• docs/user-flows/END_TO_END_USER_FLOWS.md:751 anticipates teacher.* permissions ("✅ Admin, Read own — Teacher") — this is a doc-only contract, not implemented.

6. Events & side-effects

Two derivable gaps (see 14-QA): PLAN.md:36 promises "→ email queue → welcome email" but the actual mapping sends TeacherCreated to the in-app queue, not emails; and inapp.worker.ts:47 stores type: 'TeacherCreated' into a notification whose NotificationType enum only admits email_verified|password_reset|verification_resent|welcome (notification.schema.ts:7-12) — an enum-mismatch risk.

7. Dependencies

8. Business goals

9. Success metrics

• Teacher creation → visible in list + dashboard count ≤ 3 s after submit.
• 0 duplicate employeeNumber errors for > 99% of form flows (client validates against existing list + server 409 handles races).
• Assignment editor: no silent conflicts — server has no conflict check on POST /subject-assignments (subject-assignment.service.ts:13-17) so the client must surface duplicates itself (OQ-2).
• Deactivate flow: confirmation dialog → success in 1 call, teacher disappears from all lists (soft-delete) but audit/search retention honored.

10. Edge cases (derived)

• Duplicate userId → 409 "Teacher profile already exists for this user." (teacher.service.ts:29-31).
• Duplicate employeeNumber → 409 "Employee number "X" already exists." (teacher.service.ts:35-38).
• GET /teachers/:id unknown id → 404 "Teacher not found." (teacher.service.ts:56).
• DELETE unknown id → 404 (softDelete returns false → throw) (teacher.service.ts:96-97).
• PATCH unknown id → 404 via findById pre-check (teacher.service.ts:81).
• GET /subject-assignments/by-teacher/:teacherId without academicYearId → filter is {teacherId, academicYearId: undefined} → empty result (query param is required in practice though not validated) (subject-assignment.service.ts:26-31).
• DELETE /subject-assignments/:id unknown id → 404 "Assignment not found." (subject-assignment.service.ts:34-35).
• PATCH /teachers/:id cannot change userId (not in UpdateTeacherDto) — identity link is immutable via this API.
• sort and q params are accepted by PaginationQueryDto but not applied in TeacherService.find (teacher.service.ts:66-78) — client-side search/sort needed or backend enhancement (OQ-3).

11. Assumptions (module)

• Client is forward-looking: backend is complete for this module; these docs are the UI-side spec, consistent with shared ledger A1 (00-shared/12) — PRD lists native mobile as a later-phase, read-only companion; this package specs a full client per user instruction.
• subjects[]/classTeacherFor[] arrays and subject_assignments are treated by the client as complementary: profile arrays render as badges/profile data; the assignments matrix drives the per-year schedule/assignment surfaces (OQ-4 for sync).
• No bulk-import surface exists for teachers (BulkModule exists at app.module.ts:59 but teacher import is not implemented) → bulk import is (planned), not specced as v1.
• Teacher photo/avatar: no photo field exists on Teacher or User in scope — avatar rendering uses initials fallback (AppAvatar, 03_Component_Library.md).

12. Open questions (module-level)