[dyad] Kalan branding alt başlığını kaldır

docs/role-communication-leave-workflow.md

@@ -0,0 +1,328 @@
+# Role, Communication, Leave, And Calendar Workflow
+
+## Objective
+
+Implement role-safe school operations for administrators, vice principals,
+teachers, students, and parents. Every API must enforce the same permissions as
+the navigation, and student and parent data must stay scoped to the user.
+
+## Invariants
+
+- `SCHOOL_ADMIN` and `SUPER_ADMIN` retain full school/system administration.
+- `VICE_PRINCIPAL` never creates, deletes, promotes, resets passwords for, or
+  otherwise manages administrator accounts.
+- Teachers can only view and update students enrolled in a class they teach.
+- Students can only access their linked student record.
+- Parents can only access records linked through `ParentStudentLink`.
+- Authorization is enforced server-side; menu filtering is only a convenience.
+
+## Phase 1: Role And Data Access Foundation
+
+Status: implemented
+
+Scope:
+
+- Centralize administrator, user-management, and student-management policy.
+- Restrict student lists, student detail pages, and class-student APIs.
+- Restrict account management to administrators.
+- Explicitly prevent vice principals from modifying administrator accounts.
+- Narrow student, parent, and teacher menus to their allowed workflows.
+
+Files:
+
+- `src/lib/role-access.ts`
+- `src/lib/access-policy.ts`
+- `src/app/api/students/route.ts`
+- `src/app/api/students/[id]/details/route.ts`
+- `src/app/api/classes/[id]/students/route.ts`
+- `src/app/api/users/route.ts`
+- `src/app/api/users/[id]/route.ts`
+
+Verification:
+
+- `pnpm exec tsc --noEmit --pretty false`
+- `pnpm lint`
+- `pnpm test`
+
+## Phase 2: Communication Escalation And Groups
+
+Status: implemented
+
+Scope:
+
+- Add a unified communication policy service.
+- Route student and parent messages to the responsible class teacher first.
+- Persist first-contact timestamp, response timestamp, resolution status, and
+  escalation eligibility after five business days.
+- Allow teachers to message administrators and vice principals directly.
+- Add class and parent group room types, membership generation, and moderator
+  visibility for the responsible teacher and administrator.
+- Prevent student and parent direct administrator threads before escalation.
+
+Schema work:
+
+- Extend `CommunicationRoom` with audience type, class group, escalation,
+  resolution, and visibility state.
+- Extend `CommunicationMessage` with attachment metadata and moderation state.
+- Add migration and backfill safe defaults for existing rooms.
+
+Verification:
+
+- Unit tests for five-business-day calculation and recipient selection.
+- API tests for unauthorized direct escalation and group membership isolation.
+
+Implemented baseline:
+
+- Direct student conversations are assigned to the responsible class teacher.
+- Direct conversations store a five-business-day escalation deadline.
+- Students and linked parents may escalate unresolved conversations after the
+  deadline; the school administrator is then added as a moderator.
+- Teachers and administrators can create class-group rooms only for their
+  authorized school/class context.
+- Membership-based message posting is enforced for group rooms.
+
+## Phase 3: Student And Parent Leave Workflow
+
+Status: implemented
+
+Scope:
+
+- Generalize `IllnessReport` into a leave request workflow for illness,
+  personal days, and religious holidays.
+- Allow evidence attachment metadata without exposing documents outside the
+  approval chain.
+- Require parent approval for student requests.
+- Notify the responsible teacher after parent approval.
+- Require administrator approval before the leave becomes calendar-visible.
+- Create calendar records for the student, teacher, and school administration.
+
+Schema work:
+
+- Add leave type, admin approval, review actor/timestamps, evidence metadata,
+  and linked calendar event fields to `IllnessReport` or migrate to a dedicated
+  `StudentLeaveRequest` model.
+- Add notification records for each workflow transition.
+
+Verification:
+
+- Workflow tests covering pending, parent-approved, teacher-notified,
+  admin-approved, rejected, and calendar-created states.
+
+Implemented baseline:
+
+- Student requests require a linked parent approval.
+- Parent-created requests pass the parent approval stage immediately.
+- Parent approval notifies the responsible teacher.
+- Final approval is restricted to school and super administrators.
+- Final approval creates one class-linked, all-day calendar event and stores the
+  event reference on the leave request.
+- Evidence documents remain on the leave request and are not placed in calendar
+  event notes.
+
+## Phase 4: Teacher Leave And Calendar Visibility
+
+Scope:
+
+- Extend `TeacherAbsence` with administrator approval, vice-principal
+  notification, private administrator notes, and evidence attachments.
+- Keep teacher absence notifications hidden from students.
+- On approval, publish only relevant calendar events to the teacher,
+  administrators, and affected class calendars.
+- Add explicit calendar audience and owner visibility rules.
+
+Schema work:
+
+- Add a `CalendarEventAudience` relation or an audience JSON replacement with
+  recipient users, class groups, and parent visibility.
+- Add `privateAdminNotes` and approval data to `TeacherAbsence`.
+
+Verification:
+
+- API tests that prove private notes and unpublished teacher events cannot be
+  retrieved by students or parents.
+
+## Phase 5: UI Completion And Regression Coverage
+
+Status: implemented
+
+Scope:
+
+- Render role-specific menu items and communication/leave screens.
+- Add escalation countdown/status to student and parent conversations.
+- Add approval work queues for teachers, vice principals, and administrators.
+- Add calendar visibility controls for teachers and students.
+- Add responsive, accessible group and approval UI states.
+
+Verification:
+
+- Role-by-role Playwright journeys.
+- API authorization matrix tests for every protected route.
+- `pnpm exec tsc --noEmit --pretty false`, `pnpm lint`, `pnpm test`, and
+  `pnpm build`.
+
+Implemented baseline:
+
+- Leave cards distinguish parent approval from final administrator approval and
+  show calendar publication only after the final approval.
+- Student and parent conversation panels expose the escalation action only
+  after the five-business-day threshold.
+- Escalated rooms visibly identify their administrative escalation state.
+- `pnpm typecheck` provides a build-first typecheck that avoids stale generated
+  Next type files.
+
+## Dependency Order
+
+1. Phase 1 must precede all others because it establishes reusable access
+   predicates.
+2. Phase 2 and Phase 3 can begin in parallel after Phase 1.
+3. Phase 4 depends on the calendar audience design from Phase 3.
+4. Phase 5 depends on completed APIs from Phases 2 through 4.
+
+## Rollback
+
+- All schema changes use additive columns/tables first.
+- No existing data is deleted by migrations.
+- New policy checks default to deny for unknown roles and missing ownership.
+
+## Phase 6: Endpoint Authorization Hardening
+
+Status: implemented
+
+- User role assignment now uses the same administrator target-protection policy
+  as user update/delete operations.
+- Class updates and deletion are restricted to school administrators; all class
+  reads validate class membership or administrator scope.
+- Bulk student creation validates the caller school and a teacher's assigned
+  class before creating records.
+- Parent-link reads and edits validate teacher student scope and school scope.
+
+## Phase 7: Workflow Scope Hardening
+
+Status: implemented
+
+- Parent communication creation requires an explicitly linked child rather than
+  inferring a profile from the parent's own account.
+- Parent and student leave list filters reject unlinked student identifiers.
+- Communication room deletion is limited to school/super administrators;
+  vice principals cannot remove conversation records.
+- Administrative room closure verifies the administrator belongs to the room's
+  school.
+
+## Phase 8: Leave Record Integrity
+
+Status: implemented
+
+- Teacher absence detail endpoints now require authentication, school scope,
+  and either the absence owner or an administrator.
+- Teachers cannot alter status, or edit/delete a leave once it is approved.
+- Vice principals cannot delete student leave records; reporters may only
+  withdraw requests before either approval stage is processed.
+
+## Phase 9: Academic And Behavioral Data Isolation
+
+Status: implemented
+
+- Learning progress reads and writes enforce linked student, class, and teacher
+  scope rather than accepting arbitrary identifiers.
+- Assessment results validate assessment class access and every target student.
+- Homework submissions return only the logged-in student or linked parent
+  records, and student submissions resolve from the authenticated user ID.
+- Behavior incidents are limited to a teacher's assigned classes for reads and
+  writes.
+
+## Phase 10: Sensitive Student Resource Isolation
+
+Status: implemented
+
+- Health records are administrator-only and additionally validate the target
+  student scope and school on every operation.
+- Portfolio entries resolve to the current student or linked parent children
+  when no explicit authorized student is supplied.
+- Notebook and drawing creation validates class ownership, school ownership,
+  and prevents students from publishing class-visible resources.
+
+## Phase 11: Personal Planning And Calendar Integrity
+
+Status: implemented
+
+- Calendar event updates and deletions require event ownership or administrator
+  authority, plus matching school and class access.
+- Student goals and study plans now use the shared student access predicate for
+  all student, parent, teacher, and administrator callers.
+- Badge awards and XP changes require an authorized teacher/administrator and
+  an accessible student; character updates cannot cross school boundaries.
+
+## Phase 12: Wellbeing And Private Record Isolation
+
+Status: implemented
+
+- Wellness API identity and role now come exclusively from the active session;
+  caller-controlled role query parameters can no longer grant access.
+- Students may submit only their own daily wellness check-ins; teachers may
+  view only assigned classes.
+- Teacher notes verify target student scope before reads or writes.
+- Emergency contacts are restricted to administrators and require school plus
+  authorized target-student scope.
+
+## Phase 13: Operational Resource Isolation
+
+Status: implemented
+
+- Student transport records are administrator-only and verify target student
+  scope for read, create, update, and deletion.
+- Library checkouts validate caller school, target student access, and book
+  school ownership before mutation.
+- Student resource discovery is limited to public resources targeted at their
+  enrolled classes; resource creation verifies school and class ownership.
+- School event creation requires a teacher/administrator and class scope;
+  student lists are restricted to all-school or their enrolled-class events.
+
+## Phase 14: Assessment And Report Isolation
+
+Status: implemented
+
+- Only students may submit lesson answers or peer assessments, and both flows
+  verify the authenticated student and assigned class.
+- Teachers can only create/view peer assessment sessions in their own classes;
+  vice principals cannot create them.
+- Learning goals and report cards enforce the shared student/class access
+  policy for every caller.
+- Student and parent report lists are restricted to published reports for self
+  or linked children; teacher report lists are limited to assigned classes.
+
+## Phase 15: Single-Item Resource Integrity
+
+Status: implemented
+
+- Homework grading/deletion validates the homework class and target student
+  before a teacher or administrator can mutate a submission.
+- Student badge queries, awards, and deletions validate school plus target
+  student scope.
+- Single drawing/resource operations now enforce school and class visibility;
+  student-owned work cannot be republished class-wide.
+- School-event registration, cancellation, and status changes prohibit user ID
+  spoofing and validate the caller's event school/class access.
+
+## Phase 16: Detail Record Scope Enforcement
+
+Status: implemented
+
+- Single learning goals and study plans now verify school and target-student
+  scope before reads, updates, or deletion.
+- Report-card detail/update/delete paths validate student, class, and school
+  scope in addition to publication rules.
+- Emergency-contact detail operations are administrator-only with target
+  student scope enforcement.
+- Library return/renew/delete paths validate the checkout school and student
+  before changing inventory or checkout state.
+
+## Phase 17: Discipline And Student Reflection Isolation
+
+Status: implemented
+
+- Disciplinary cases and behavior interventions validate school and target
+  student scope before reads or writes.
+- Self-assessments now validate student and class ownership on collection and
+  detail endpoints.
+- Study sessions are student-owned: only the authenticated student can create
+  or update a session for their own profile.