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

08 — Form Specifications (Teachers Module)

Field-by-field specs. Server column = exact DTO contract (create-teacher.dto.ts, update-teacher.dto.ts, create-subject-assignment.dto.ts). Weak-validation warnings are derived facts (missing class-validator decorators).

F1 — Create Teacher (POST /teachers)

#FieldTypeRequiredServer validationClient inputDefault
1userIdstring (ObjectId)✅@IsMongoId (create-teacher.dto.ts:6-7)Searchable user picker (Users module)—
2employeeNumberstring✅@IsString (create-teacher.dto.ts:10-11)Text, mono font, uppercase hint—
3departmentIdstring (ObjectId)—@IsOptional @IsMongoId (:15-16)AppDropdown from GET /departments—
4designationIdstring (ObjectId)—@IsOptional @IsMongoId (:20-21)AppDropdown from GET /designations—
5joiningDatedate string—@IsOptional @IsDateString (:25-26)AppDatePicker, maxDate = today (proposed)—
6employmentStatusstring enum—@IsOptional @IsString — enum not validated (:31-33)Segmented AppDropdown, 4 values from EmploymentStatus (teacher.schema.ts:7-12)active
7qualificationstring—@IsOptional @IsString (:37-38)Multiline AppTextField, 2 lines max (proposed)—
8experienceYearsnumber—no validator at all (:41-42)Numeric AppTextField, int ≥ 0, ≤ 60 (proposed)—
9subjectsstring[] (ObjectId[])—no array/MongoId validator (:45-46)Multi-select chips from GET /subjects[] (schema default teacher.schema.ts:44)
10classTeacherForstring[] (ObjectId[])—no validator (:48-52)Multi-select chips from GET /classes[] (schema default teacher.schema.ts:47)

Submit payload (exact)

{ "userId": "…", "employeeNumber": "TCH001", "departmentId": "…",
  "designationId": "…", "joiningDate": "2024-08-12", "employmentStatus": "active",
  "qualification": "M.Sc.", "experienceYears": 6, "subjects": ["…"], "classTeacherFor": ["…"] }

Server responses

  • 201→200 envelope data = created Teacher doc (timestamps auto, teacher.schema.ts:14).
  • 409 DUPLICATE_RESOURCE: user-linked profile exists / employee number exists (teacher.service.ts:29-37) → inline AppBanner; keep form state (no reload).
  • 400 VALIDATION_ERROR: field details mapped (00-shared/07 §3).
  • Notes: tenantId never sent (from token, base.repository.ts:33-35); metadata not part of create DTO (update only).

F2 — Update Teacher (PATCH /teachers/:id)

#FieldNotes
1–9same as F1 minus userIdupdate-teacher.dto.ts:4-49; userId immutable
10metadataRecord<string, unknown> optional (update-teacher.dto.ts:51-53); client sends {key: primitive} rows only (proposed)
  • Partial semantics: $set merge (teacher.service.ts:82) — omitted fields untouched; client sends only changed fields.
  • Conflict rules on update: no server checks — PATCH can set employeeNumber to an existing number with no 409 (unlike create; teacher.service.ts:80-93 only checks existence of the target record). Client pre-validates against loaded roster; server-side race remains (OQ-3).
  • Status transitions allowed: any of 4 enum values, no workflow restriction server-side.

F3 — Subject Assignment (POST /subject-assignments)

#FieldTypeRequiredServer validationClient input
1teacherIdstring (ObjectId)✅@IsMongoId (create-subject-assignment.dto.ts:6-7)Prefilled from teacher detail; editable in standalone mode (proposed)
2subjectIdstring (ObjectId)✅@IsMongoId (:9-10)Searchable picker from GET /subjects
3classIdstring (ObjectId)✅@IsMongoId (:12-13)Year-scoped picker from GET /classes
4academicYearIdstring (ObjectId)✅@IsMongoId (:15-16)AppDropdown from GET /academic-years, default isCurrent

Client-side rules (server gaps)

  • Duplicate guard: block exact (teacher, subject, class, year) already in matrix — no server uniqueness (subject-assignment.schema.ts:24-25 indexes are non-unique; subject-assignment.service.ts:13-17 has no check) (OQ-2).
  • Same teacher teaching 2 subjects in one class: allowed (no cross-check with timetable slots — timetable has its own conflict detection at timetable.service.ts:16-30).
  • Submit disabled until all 4 set; double-submit guard.

Responses

  • 200 data = SubjectAssignment doc. Errors: 400 (invalid ids), 500; no 404 path for unknown teacherId/subjectId/classId (no existence checks — client must ensure picker values are valid).