Add 8 files, update 14 files

plans/role-communication-leave-workflow.md

@@ -0,0 +1,160 @@
+# 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
+
+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.
+
+## 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
+
+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`.
+
+## 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.