08 — Form Specifications (Students Module)

• 1. Create Student (wizard step 2–4 → POST /students)
• 2. Enroll (POST /students/:id/enroll)
• 3. Transfer (POST /students/:id/transfer)
• 4. Update student (PATCH /students/:id)
• 5. Upload document (POST /students/:id/documents)
• 6. CSV bulk import (POST /bulk/import/students)
• 7. Create parent (POST /parents)
• 8. Link parent (POST /parents/link/:studentId)
• 9. Avatar upload (POST /users/:id/avatar)
• Validation UX rules (all forms)

Every field of every form, exactly mapped to the server DTOs. Types/validation from the DTO files (class-validator decorators); enums from schemas. All fields not listed do not exist server-side. * = required by backend.

1. Create Student (wizard step 2–4 → POST /students)

Payload DTO: create-student.dto.ts. Identity step targets POST /users (users.controller.ts:36-40).

Identity step (POST /users) — user schema fields (user.schema.ts:16-35): firstName* (required), middleName?, lastName* (required), displayName?, email* (unique per tenant → 409; lowercase), phone?. UI submits only firstName, lastName, email, phone?.

Server status on create: always active (student.service.ts:65), admissionType default new, enrollment ACTIVE with joinedAt = now.

2. Enroll (POST /students/:id/enroll)

DTO: enroll-student.dto.ts.

Side effect banner: existing ACTIVE enrollments → transferred + leftAt (student.service.ts:125-139).

3. Transfer (POST /students/:id/transfer)

DTO: transfer-student.dto.ts.

Guard: student status must be active (student.service.ts:175-179).

4. Update student (PATCH /students/:id)

DTO: update-student.dto.ts — every field optional mirror of create plus: status? (plain string, no enum validation — update-student.dto.ts:60-63; UI must only send valid StudentStatus values), metadata? (object, update-student.dto.ts:78-80). Note: PATCH with $set writes only provided fields (student.service.ts:144). Client edit form = create fields minus class path (class changes go through transfer/enroll) plus status only via lifecycle actions, not the form.

5. Upload document (POST /students/:id/documents)

Server has no size/mime limits (OQ-9). Client (proposed) limits: ≤ 10 MB, mime ∈ {pdf, jpg, png, webp}. uploadedBy = actor userId (student.service.ts:269).

6. CSV bulk import (POST /bulk/import/students)

Adapter columns (students-import.adapter.ts:17-26):

Derived resolution: class = first class matching {gradeId, sectionId, academicYearId} (students-import.adapter.ts:131-141) — error "No class found for grade "{g}" section "{s}".".

Parsing rules (bulk-import.service.ts:26-35): header row required (first row = column names), skip_empty_lines, trim, columns: true. Empty file → 400 "CSV must include a header row and data." Malformed → 400 "Malformed CSV: could not parse file." Row numbering: index + 2 (header = row 1).

Export template (GET /bulk/export/students, students-import.adapter.ts:87-98): columns admissionNumber, rollNumber, status, admissionDate — sorted by admissionNumber asc. This is an export format, not an import template — flagged in UI (import columns differ).

7. Create parent (POST /parents)

DTO: create-parent.dto.ts.

Guard: one parent profile per userId → 409 "Parent profile already exists for this user." (parent.service.ts:30-34).

8. Link parent (POST /parents/link/:studentId)

DTO: link-parent.dto.ts.

Student existence checked (student-parent-link.service.ts:27); parent existence not checked (OQ-11).

9. Avatar upload (POST /users/:id/avatar)

Multipart field file (users.controller.ts:96); updates avatarFileId on the user doc (user.schema.ts:34-35).

Validation UX rules (all forms)

• Run validator on submit + after first error; clear on edit (00-shared/03 B).
• 400 VALIDATION_ERROR → map details[].field to fields (00-shared/06 §5); focus first invalid (00-shared/09 §10).
• 409 → inline conflict with suggested action (search existing / change admission number).
• Submit buttons: disabled while pending (anti-double-submit, 00-shared/08 §6).