diff --git a/app/Http/Controllers/Api/Scores/ScoreController.php b/app/Http/Controllers/Api/Scores/ScoreController.php index 7f811f52..c8b465a2 100644 --- a/app/Http/Controllers/Api/Scores/ScoreController.php +++ b/app/Http/Controllers/Api/Scores/ScoreController.php @@ -44,6 +44,7 @@ class ScoreController extends BaseApiController 'semester' => $data['semester'] ?? null, 'school_year' => $data['school_year'] ?? null, 'scores_locked' => $data['scoresLocked'] ?? false, + 'missing_ok_map' => $data['missing_ok_map'] ?? [], ]); } diff --git a/app/Models/TeacherClass.php b/app/Models/TeacherClass.php index e6c03743..051f954c 100644 --- a/app/Models/TeacherClass.php +++ b/app/Models/TeacherClass.php @@ -14,6 +14,7 @@ class TeacherClass extends BaseModel protected $fillable = [ 'teacher_id', 'class_section_id', + 'semester', 'school_year', 'position', 'updated_by', @@ -404,6 +405,7 @@ class TeacherClass extends BaseModel return [ 'teacher_id' => [$req, 'integer', 'min:1', 'exists:users,id'], 'class_section_id' => [$req, 'integer', 'min:1'], + 'semester' => [$req, 'string', 'max:25'], 'school_year' => [$req, 'string', 'max:9'], 'position' => [$req, 'string', 'in:' . implode(',', self::allowedPositions())], 'updated_by' => ['nullable', 'integer'], diff --git a/app/Services/Scores/ScoreDashboardService.php b/app/Services/Scores/ScoreDashboardService.php index 99b11b51..fe4546ce 100644 --- a/app/Services/Scores/ScoreDashboardService.php +++ b/app/Services/Scores/ScoreDashboardService.php @@ -114,6 +114,7 @@ class ScoreDashboardService 'homework' => $this->normalizeScore($scoreRow->homework_avg), 'quiz' => $this->normalizeScore($scoreRow->quiz_avg), 'project' => $this->normalizeScore($scoreRow->project_avg), + 'participation' => $this->normalizeScore($scoreRow->participation_score), 'midterm_exam' => $this->normalizeScore($scoreRow->midterm_exam_score), 'final_exam' => $this->normalizeScore($scoreRow->final_exam_score), 'attendance' => $this->normalizeScore($scoreRow->attendance_score), @@ -125,6 +126,24 @@ class ScoreDashboardService unset($student); $classSection = ClassSection::query()->where('class_section_id', $classSectionId)->first(); + $missingOkMap = [ + 'ptap_comment' => MissingScoreOverride::getOverridesMap($classSectionId, $semesterLabel, $schoolYear, 'ptap_comment'), + ]; + if (strtolower($semesterLabel) === 'fall') { + $missingOkMap['midterm_comment'] = MissingScoreOverride::getOverridesMap( + $classSectionId, + $semesterLabel, + $schoolYear, + 'midterm_comment' + ); + } elseif (strtolower($semesterLabel) === 'spring') { + $missingOkMap['final_comment'] = MissingScoreOverride::getOverridesMap( + $classSectionId, + $semesterLabel, + $schoolYear, + 'final_comment' + ); + } return [ 'students' => $students, @@ -133,6 +152,7 @@ class ScoreDashboardService 'semester' => $semesterLabel, 'school_year' => $schoolYear, 'scoresLocked' => GradingLock::isLocked($classSectionId, $semesterLabel, $schoolYear), + 'missing_ok_map' => $missingOkMap, ]; } diff --git a/app/Services/Teachers/TeacherAssignmentService.php b/app/Services/Teachers/TeacherAssignmentService.php index e3276e34..91595428 100644 --- a/app/Services/Teachers/TeacherAssignmentService.php +++ b/app/Services/Teachers/TeacherAssignmentService.php @@ -16,6 +16,7 @@ class TeacherAssignmentService { $context = $this->configService->context(); $schoolYear = $schoolYear ?: (string) ($context['school_year'] ?? ''); + $semester = trim((string) ($context['semester'] ?? '')); $teachers = User::getTeachersAndTAs(); $classSections = ClassSection::query() @@ -39,6 +40,7 @@ class TeacherAssignmentService $assignments = TeacherClass::query() ->when($schoolYear !== '', fn ($q) => $q->where('school_year', $schoolYear)) + ->when($semester !== '', fn ($q) => $q->where('semester', $semester)) ->get() ->toArray(); @@ -113,12 +115,13 @@ class TeacherAssignmentService { $context = $this->configService->context(); $schoolYear = (string) ($input['school_year'] ?? $context['school_year'] ?? ''); + $semester = trim((string) ($input['semester'] ?? $context['semester'] ?? '')); $teacherId = (int) ($input['teacher_id'] ?? 0); $classSectionId = (int) ($input['class_section_id'] ?? 0); $teacherRole = (string) ($input['teacher_role'] ?? ''); $loggedInUserId = (int) ($input['updated_by'] ?? 0); - if ($teacherId <= 0 || $classSectionId <= 0 || $schoolYear === '') { + if ($teacherId <= 0 || $classSectionId <= 0 || $schoolYear === '' || $semester === '') { return ['ok' => false, 'message' => 'Missing required parameters for assignment.']; } @@ -132,6 +135,7 @@ class TeacherAssignmentService ->where('teacher_id', $teacherId) ->where('class_section_id', $classSectionId) ->where('position', $position) + ->where('semester', $semester) ->where('school_year', $schoolYear) ->first(); @@ -143,6 +147,7 @@ class TeacherAssignmentService 'teacher_id' => $teacherId, 'class_section_id' => $classSectionId, 'position' => $position, + 'semester' => $semester, 'school_year' => $schoolYear, 'created_at' => now(), 'updated_at' => now(), @@ -162,15 +167,17 @@ class TeacherAssignmentService $teacherId = (int) ($input['teacher_id'] ?? 0); $classSectionId = (int) ($input['class_section_id'] ?? 0); $position = strtolower((string) ($input['position'] ?? '')); + $semester = trim((string) ($input['semester'] ?? $context['semester'] ?? '')); $schoolYear = trim((string) ($input['school_year'] ?? $context['school_year'] ?? '')); - if ($teacherId <= 0 || $classSectionId <= 0 || !in_array($position, ['main', 'ta'], true) || $schoolYear === '') { + if ($teacherId <= 0 || $classSectionId <= 0 || !in_array($position, ['main', 'ta'], true) || $schoolYear === '' || $semester === '') { return ['ok' => false, 'message' => 'Missing or invalid data for deletion.']; } $assignment = TeacherClass::query() ->where('teacher_id', $teacherId) ->where('class_section_id', $classSectionId) + ->where('semester', $semester) ->where('school_year', $schoolYear) ->where('position', $position) ->first(); diff --git a/docs/new_school_attendance_management_plan.md b/docs/new_school_attendance_management_plan.md new file mode 100644 index 00000000..841cb82e --- /dev/null +++ b/docs/new_school_attendance_management_plan.md @@ -0,0 +1,1265 @@ +# School Attendance Management Plan for Students and Staff + +## 1. Purpose + +The purpose of this plan is to create a clear, consistent system for managing daily attendance for students, staff, contractors, and visitors. The system will track whether each person is present, absent, late, or dismissed early. It will also identify whether attendance events are reported or not reported, provide administrators with a structured follow-up process, and support attendance accuracy through badge scanning, manual entry, and late slip printing. + +The plan is designed to help the school: + +- Maintain accurate attendance records. +- Identify repeated absence, lateness, and early dismissal patterns. +- Follow up quickly on unexplained attendance issues. +- Support students, families, and staff before attendance issues become serious. +- Provide administrators with a clear dashboard for emails, calls, notes, and decisions. +- Automate attendance tracking through a badge scanning system. +- Allow manual attendance entry when badge scanning is not possible. +- Monitor entry, exit, early dismissal, late arrival, and badge exceptions. +- Print late slips for students who arrive after the official start time. + +--- + +## 2. Attendance Categories + +Each student and staff member will be marked under one of the following statuses each school day. + +### A. Present + +The person is at school or work on time and has either: + +- Successfully scanned their badge upon entry, or +- Been manually verified and entered by an authorized staff member. + +### B. Absent + +The person is not present for the school day or assigned workday. + +Absence will be divided into: + +1. **Reported Absence** + The parent, guardian, student if legally permitted, or staff member has informed the school before or on the day of absence. + +2. **Not-Reported Absence** + No valid notice has been received by the school. + +### C. Late + +The person arrives after the official start time. + +Lateness will be divided into: + +1. **Reported Late** + The parent, guardian, student if legally permitted, or staff member has informed the school about the delay. + +2. **Not-Reported Late** + The person arrives late without prior notice or valid explanation. + +### D. Early Dismissal + +The person leaves school before the official end of the school day. + +Early dismissal will be divided into: + +1. **Reported Early Dismissal** + The early dismissal is approved by the school and supported by a valid reason. + +2. **Not-Reported Early Dismissal** + The person leaves without proper authorization or notification. + +--- + +## 3. Badge Scanning Attendance System + +### 3.1 Mandatory Badge Requirement + +Every student, teacher, administrator, support staff member, contractor, and visitor must carry an approved school identification badge after one has been issued. + +The badge is used to record entry and exit activity. It supports attendance accuracy, safety monitoring, and accountability. + +### 3.2 Entry Scanning + +All school members must scan their badge when entering the school campus or building. + +The system will automatically record: + +- Name +- ID number +- Date +- Entry time +- Building or gate location +- Attendance status +- Scan method +- Report status, if applicable + +### 3.3 Exit Scanning + +All school members must scan their badge when leaving the school campus or building. + +The system will automatically record: + +- Name +- ID number +- Date +- Exit time +- Exit location +- Exit method +- Early dismissal status +- Authorized or unauthorized exit status + +### 3.4 Automatic Attendance Classification + +The system will automatically classify attendance based on badge scan times or approved manual entry times. + +| Scan or Manual Entry Result | Attendance Status | +|---|---| +| Badge entry scan before start time | Present | +| Badge entry scan after start time | Late | +| Manual entry before start time | Present | +| Manual entry after start time | Late | +| No badge scan and no manual entry | Absent Pending Verification | +| Authorized early exit scan | Early Dismissal Reported | +| Authorized manual exit entry | Early Dismissal Reported | +| Unauthorized early exit scan | Early Dismissal Not Reported | +| Unauthorized manual exit entry | Early Dismissal Not Reported | + +### 3.5 Missing Badge Procedure + +If a badge is forgotten, lost, damaged, or not yet issued: + +- The individual must report to the office or assigned attendance checkpoint. +- The person’s identity must be verified. +- A manual attendance entry may be completed. +- A temporary badge may be issued when appropriate. +- Repeated failure to carry or use a badge must be tracked as a badge exception. + +--- + +## 4. Manual Attendance Entry for Badge Exceptions + +The attendance system must allow manual attendance entry when a badge scan is not possible. + +Manual entry may be used only when: + +- A badge has not yet been issued. +- A badge is missing. +- A badge is lost. +- A badge is damaged. +- The badge scanner is temporarily unavailable. +- The individual reports directly to the office for verification. + +Manual entry must be completed by an authorized staff member only. + +### 4.1 Manual Entry Process + +When a student, staff member, contractor, or visitor cannot scan a badge, the person must report to the office or assigned attendance checkpoint. + +The authorized staff member must verify the person’s identity and manually enter the attendance record into the system. + +The manual record must include: + +- Name +- Student ID, employee ID, or visitor ID +- Date +- Manual entry time +- Reason for manual entry +- Name of staff member entering the record +- Attendance status +- Notes, if needed + +### 4.2 Manual Entry Time Rule + +When manual entry is used because a badge is not issued, missing, lost, damaged, or unavailable, the system must treat the manual entry time as the official entry scan time. + +The manual entry time will be used to determine whether the person is: + +- Present +- Late +- Absent pending verification + +| Situation | System Action | +|---|---| +| Manual entry before official start time | Mark as Present | +| Manual entry after official start time | Mark as Late | +| No badge scan and no manual entry | Mark as Absent Pending Verification | +| Manual entry with approved prior notice | Mark as Reported | +| Manual entry without approved prior notice | Mark as Not Reported or Pending Clarification | + +### 4.3 Manual Exit Entry + +If a person cannot scan their badge when leaving, an authorized staff member may manually enter the exit time. + +The manual exit entry must include: + +- Name +- Date +- Manual exit time +- Reason for manual exit entry +- Authorized staff member name +- Exit status +- Notes, if needed + +When manual exit entry is used, the system must treat the manual exit time as the official exit scan time. + +### 4.4 Badge Exception Tracking + +Each manual entry must be tracked as a badge exception. + +The system should count repeated badge exceptions, including: + +- 1 Badge Exception +- 2 Badge Exceptions +- 3 Badge Exceptions +- 4 Badge Exceptions +- 5 Badge Exceptions + +Repeated badge exceptions should trigger administrative follow-up. + +### 4.5 Badge Exception Decision Levels + +| Badge Exception Count | Action | Decision | +|---|---|---| +| 1 Exception | Record and allow manual entry | No formal action | +| 2 Exceptions | Issue reminder | Monitor | +| 3 Exceptions | Admin warning | Badge compliance concern | +| 4 Exceptions | Contact parent, guardian, supervisor, or HR | Formal follow-up required | +| 5 Exceptions | Leadership review | Badge replacement, disciplinary action, or attendance intervention | + +### 4.6 Manual Entry Safeguards + +Manual entry must not become a shortcut to avoid badge scanning. + +The system must require: + +- Authorized staff login +- Reason for manual entry +- Timestamp +- Identity verification +- Audit trail +- Admin review for repeated manual entries + +Any suspicious manual entry pattern must be reviewed by administration. + +Examples of suspicious patterns include: + +- Frequent manual entries by the same person +- Manual entries always occurring after start time +- Manual entries without clear reasons +- Manual entries made by unauthorized staff +- Manual entries that conflict with classroom or workplace verification + +### 4.7 Final Manual Entry Rule + +A person without a valid badge scan may still be marked present only if an authorized staff member completes a verified manual entry. + +The manual entry time becomes the official entry scan time for attendance classification and reporting. + +--- + +## 5. Daily Attendance Process + +Attendance will be taken through the badge scanning system, manual entry system, and verification by teachers and administrators. + +For students: + +- Students scan badges when entering. +- Students without badges report to the office for manual entry. +- Teachers verify classroom attendance against badge scan and manual entry records. + +For staff: + +- Staff scan badges when entering and leaving. +- Staff without badges report to the office or assigned administrator for manual entry. +- The office manager, HR officer, or assigned administrator verifies staff attendance through the staff attendance system. + +The attendance system must show: + +- Name +- Student ID or employee ID +- Grade or department +- Date +- Entry scan time or manual entry time +- Exit scan time or manual exit time +- Attendance status: Present, Absent, Late, or Early Dismissal +- Report status: Reported, Not Reported, or Pending Clarification +- Reason, if provided +- Number of absences +- Number of late arrivals +- Number of early dismissals +- Number of badge exceptions +- Combination count of absences, lateness, and early dismissals +- Follow-up action required +- Follow-up action completed +- Final decision or intervention + +--- + +## 6. Reported and Not-Reported Tracking + +Every absence, late arrival, and early dismissal must be classified as either reported or not reported. + +### 6.1 Reported Attendance Event + +A reported attendance event means the school received a valid explanation from the parent, guardian, student if legally permitted, or staff member. + +Examples include: + +- Illness +- Medical appointment +- Family emergency +- Transportation issue +- Approved personal reason +- Approved staff leave +- Professional duty or meeting +- Approved early pickup +- Approved late arrival + +The attendance record must include the reason and the person who reported it. + +### 6.2 Not-Reported Attendance Event + +A not-reported attendance event means no explanation has been received. + +These cases must automatically appear on the admin follow-up page. + +The admin team must contact the parent, guardian, student if appropriate, or staff member to request clarification. + +--- + +## 7. Admin Follow-Up Page + +The school will maintain an attendance follow-up page or dashboard. + +This page will list all students and staff who have: + +- Not-reported absences +- Not-reported lateness +- Not-reported early dismissals +- Missing badge scans +- Manual entries +- Repeated badge exceptions +- Repeated absences +- Repeated lateness +- Repeated early dismissals +- Late students who require late slips +- Late students without slips +- Any combination of attendance concerns requiring action + +### 7.1 Dashboard Table + +| Name | Role/Grade | Status | Scan or Manual Time | Reported/Not Reported | Count | Combination | Parent/Contact | Action Needed | Action Completed | Decision | +|---|---|---|---|---|---|---|---|---|---|---| +| Student/Staff Name | Grade/Department | Absent/Late/Early Dismissal | Time | Reported/Not Reported | 1ABS/2Late/etc. | ABS + Late | Phone/Email | Call/Email/Meeting | Yes/No | Decision | + +### 7.2 Dashboard Actions + +The admin page should allow the administrator to: + +- Send email to parents or guardians. +- Call parents or guardians. +- Send email to staff. +- Call staff members. +- Record the outcome of the call. +- Add notes. +- Mark follow-up as completed. +- Mark case as resolved. +- Escalate repeated cases. +- Generate reports by student, grade, staff member, class, or department. +- View badge scan history. +- Review manual entry history. +- Review unauthorized exits. +- Monitor real-time attendance. +- Print late slips. +- Reprint late slips. +- View late slip history. + +--- + +## 8. Absence Tracking Levels + +Absences will be tracked using levels. + +### 1ABS: First Absence + +Action: + +- Record the absence. +- Verify badge scan and manual entry records. +- Check whether it was reported or not reported. +- If reported, no further action may be needed unless the reason is unclear. +- If not reported, send a same-day email or make a phone call to the parent, guardian, or staff member. + +Decision: + +- Mark as excused if a valid reason is provided. +- Mark as unexcused if no valid reason is provided. +- Keep the student or staff member on the monitoring list. + +### 2ABS: Second Absence + +Action: + +- Review attendance pattern. +- Contact parent, guardian, or staff member if absence is not reported. +- Send a reminder about attendance expectations. + +Decision: + +- Continue monitoring. +- Require explanation if absences are repeated or unclear. +- Refer to teacher, supervisor, or attendance officer if needed. + +### 3ABS: Third Absence + +Action: + +- Admin contacts parent, guardian, or staff member directly. +- Document the reason for repeated absence. +- Check whether support is needed. + +Decision: + +- Create an attendance support note. +- Schedule a meeting if absences are affecting learning or work. +- Assign follow-up responsibility to an administrator. + +### 4ABS: Fourth Absence + +Action: + +- Formal attendance concern is recorded. +- Parent, guardian, student, or staff member is contacted. +- Meeting may be required. + +Decision: + +- Create an attendance improvement plan. +- Set expectations and timeline. +- Identify barriers such as health, transportation, family issues, or workload. + +### 5ABS: Fifth Absence + +Action: + +- Escalate to school leadership. +- Mandatory parent or staff meeting. +- Review all previous communication and documentation. + +Decision: + +- Implement formal intervention. +- Refer to counseling, student support, HR, or external attendance authority if required. +- Continue weekly monitoring until improvement is shown. + +--- + +## 9. Lateness Tracking Levels + +Lateness will be tracked using levels. + +### 1Late: First Late Arrival + +Action: + +- Record late arrival. +- Verify badge scan time or manual entry time. +- Print late slip for student late arrivals. +- Check whether the lateness was reported or not reported. +- If not reported, request clarification. + +Decision: + +- Mark as excused if valid reason is provided. +- Monitor for repeated lateness. + +### 2Late: Second Late Arrival + +Action: + +- Send reminder to parent, guardian, student if appropriate, or staff member. +- Review whether the lateness is becoming a pattern. +- Print late slip for student late arrivals. + +Decision: + +- Continue monitoring. +- Record reason and any repeated cause. + +### 3Late: Third Late Arrival + +Action: + +- Admin follows up directly. +- Identify the cause of repeated lateness. +- Print late slip for student late arrivals. + +Decision: + +- Create a punctuality support note. +- Set clear expectation for improvement. + +### 4Late: Fourth Late Arrival + +Action: + +- Formal punctuality concern is recorded. +- Parent, guardian, student, or staff member is contacted. +- Print late slip for student late arrivals. + +Decision: + +- Create a punctuality improvement plan. +- Schedule a meeting if needed. + +### 5Late: Fifth Late Arrival + +Action: + +- Escalate to school leadership. +- Require a formal meeting. +- Print late slip for student late arrivals. + +Decision: + +- Implement formal intervention. +- Continue monitoring. +- Apply school consequences or HR procedures if appropriate. + +--- + +## 10. Late Slip Printing System + +The attendance system must include a late slip printing process for students who arrive after the official school start time. + +A late slip must be printed whenever a student is marked late through: + +- Badge entry scan after the official start time +- Manual entry after the official start time +- Office verification after the official start time +- Late arrival following an approved appointment or parent report + +### 10.1 Late Slip Purpose + +The late slip confirms that the student has checked in through the proper attendance process before going to class. + +The late slip helps the school: + +- Verify that the student reported to the office. +- Prevent students from entering class without attendance documentation. +- Inform the teacher that the student’s late arrival has already been recorded. +- Reduce duplicate attendance corrections. +- Track reported and not-reported late arrivals. + +### 10.2 Late Slip Information + +Each printed late slip must include: + +- Student name +- Student ID +- Grade level +- Date +- Official late check-in time +- Entry method: Badge Scan or Manual Entry +- Report status: Reported, Not Reported, or Pending Clarification +- Reason for lateness, if provided +- Office staff member name or system user +- Class destination +- Slip number or barcode +- Notes, if needed + +### 10.3 Late Slip Printing Process + +When a student arrives late, the student must scan their badge at the entry point or report to the office for manual entry. + +The system will determine whether the student is late by comparing the badge scan time or manual entry time with the official school start time. + +If the student is late, the system must automatically generate and print a late slip. + +The student must take the late slip to class and give it to the teacher. + +The teacher must accept the student into class and keep or scan the late slip according to school procedure. + +### 10.4 Late Slip Status Rules + +| Late Arrival Situation | System Action | Slip Action | +|---|---|---| +| Badge scan after start time | Mark student Late | Print late slip | +| Manual entry after start time | Mark student Late | Print late slip | +| Reported late arrival | Mark Late Reported | Print late slip | +| Not-reported late arrival | Mark Late Not Reported | Print late slip and add to follow-up page | +| Late arrival with valid reason | Mark Late Excused if approved | Print late slip | +| Late arrival without valid reason | Mark Late Pending or Unexcused | Print late slip and flag for review | +| Student arrives late without checking in | Teacher sends student to office | Print late slip after verification | + +### 10.5 Teacher Verification + +Teachers should not manually admit late students without a late slip unless there is an emergency or administrator approval. + +If a student arrives to class late without a slip, the teacher must send the student to the office or mark the student as **Late Without Slip**. + +The system should flag Late Without Slip cases for admin review. + +### 10.6 Late Slip Follow-Up + +Late slips must connect to the student’s attendance record. + +The system should automatically update: + +- Student lateness count +- Reported or not-reported status +- Follow-up requirement +- Parent contact requirement +- Combination count with absences and early dismissals + +If the late arrival is not reported, the student must appear on the admin follow-up page so the office can contact the parent or guardian for clarification. + +### 10.7 Late Slip Reprint + +Authorized office staff may reprint a late slip if: + +- The original slip is lost. +- The printer fails. +- The teacher requests verification. +- The student is sent back to the office for confirmation. + +Every reprint must be logged in the system. + +The reprint log must include: + +- Reprint time +- Staff member who reprinted the slip +- Reason for reprint +- Number of reprints + +Repeated reprints should be reviewed to prevent misuse. + +### 10.8 Late Slip Audit Trail + +The system must keep a digital record of every late slip. + +The record must include: + +- Slip number +- Student name and ID +- Date +- Late check-in time +- Print time +- Entry method +- Reason +- Reported or not-reported status +- Staff member or system user +- Teacher verification status +- Reprint history + +### 10.9 Final Late Slip Rule + +Any student arriving after the official start time must receive a late slip before going to class. + +The late slip does not erase the lateness. It only confirms that the student followed the required check-in process and that the late arrival has been recorded. + +--- + +## 11. Early Dismissal Tracking Levels + +### 1ED: First Early Dismissal + +Action: + +- Verify exit badge scan or manual exit entry. +- Confirm authorization. + +Decision: + +- Record and monitor. + +### 2ED: Second Early Dismissal + +Action: + +- Review pattern. +- Contact parent, guardian, or staff member if necessary. + +Decision: + +- Continue monitoring. + +### 3ED or More: Repeated Early Dismissal + +Action: + +- Conduct administrative review. +- Determine whether attendance intervention is required. + +Decision: + +- Attendance improvement plan may be required. + +--- + +## 12. Badge Scan Exception Rules + +The attendance system must automatically flag any badge scan issue that may affect attendance accuracy or school safety. + +### 12.1 Missing Entry Scan + +A missing entry scan means the person does not have a recorded arrival scan or manual entry. + +Action: + +- Verify whether the person is physically present. +- Check classroom attendance, office logs, visitor logs, or staff supervisor confirmation. +- Mark the record as manually verified if the person is present. +- Mark as absent pending clarification if the person cannot be verified. + +Decision: + +- Valid manual verification +- Absent pending clarification +- Not-reported absence +- Badge compliance warning + +### 12.2 Missing Exit Scan + +A missing exit scan means the person entered the school but has no recorded departure scan or manual exit entry. + +Action: + +- Confirm whether the person left the building. +- Check classroom dismissal records, office checkout logs, staff schedules, or supervisor confirmation. +- Contact the person, parent, guardian, or supervisor if needed. + +Decision: + +- Valid departure confirmed +- Missing exit scan warning +- Unauthorized exit investigation +- Safety follow-up required + +### 12.3 Multiple Entry or Exit Scans + +Multiple scans may happen because of re-entry, forgotten items, appointments, or badge misuse. + +Action: + +- Review scan times and locations. +- Confirm whether movement was authorized. +- Investigate possible badge sharing or misuse if the scan pattern is unusual. + +Decision: + +- Authorized movement +- Re-entry approved +- Badge misuse warning +- Admin investigation required + +### 12.4 Badge Misuse + +Badge misuse includes: + +- Using another person’s badge +- Allowing another person to use a badge +- Scanning without entering or leaving +- Attempting to avoid attendance tracking + +Action: + +- Admin reviews scan logs. +- Speak with the student or staff member. +- Contact parent, guardian, supervisor, or HR if needed. +- Document the incident. + +Decision: + +- Warning +- Parent or staff notification +- Loss of badge privileges +- Disciplinary action +- Leadership escalation + +--- + +## 13. Combination Tracking: Absence, Lateness, and Early Dismissal + +The system must track combinations of absence, lateness, and early dismissal because a student or staff member may not reach 5ABS or 5Late separately but may still show a serious attendance pattern. + +Examples: + +- 1ABS + 1Late +- 1ABS + 2Late +- 2ABS + 1Late +- 2ABS + 2Late +- 3ABS + 1Late +- 1ABS + 3Late +- 3ABS + 2Late +- 2ABS + 3Late +- 4ABS + 1Late +- 1ABS + 4Late +- 5ABS + any Late +- 5Late + any ABS +- 2ABS + 2Late + 1ED +- 3Late + 2ED +- Badge Exceptions + Late +- Badge Exceptions + ABS +- Late Without Slip + Late Count + +--- + +## 14. Decision Matrix for Absence and Lateness Combinations + +| Combination | Risk Level | Action | Decision | +|---|---|---|---| +| 1ABS + 1Late | Low | Record and monitor | No formal action unless not reported | +| 1ABS + 2Late | Low/Medium | Send reminder | Monitor for pattern | +| 2ABS + 1Late | Medium | Contact parent/staff if not reported | Continue monitoring | +| 2ABS + 2Late | Medium | Admin follow-up | Attendance concern note | +| 3ABS + 1Late | Medium/High | Direct admin contact | Support plan may be needed | +| 1ABS + 3Late | Medium/High | Direct admin contact | Punctuality support note | +| 3ABS + 2Late | High | Parent/staff meeting | Attendance improvement plan | +| 2ABS + 3Late | High | Parent/staff meeting | Punctuality improvement plan | +| 4ABS + 1Late | High | Formal attendance concern | Improvement plan required | +| 1ABS + 4Late | High | Formal punctuality concern | Improvement plan required | +| 4ABS + 2Late or more | Very High | Leadership review | Formal intervention | +| 2ABS + 4Late or more | Very High | Leadership review | Formal intervention | +| 5ABS + any Late | Critical | Mandatory meeting | Escalation and intervention | +| 5Late + any ABS | Critical | Mandatory meeting | Escalation and intervention | +| 5ABS + 5Late | Severe | Senior leadership review | Intensive intervention and possible referral | + +--- + +## 15. Not-Reported Follow-Up System + +All not-reported absences, lateness, and early dismissals must trigger follow-up. + +### Step 1: Same-Day Alert + +The system flags the student or staff member as **Not Reported**. + +The name appears on the admin follow-up page. + +### Step 2: First Contact + +Admin sends an email or makes a phone call. + +For students, the parent or guardian is contacted. + +For staff, the staff member or supervisor is contacted. + +### Step 3: Documentation + +Admin records: + +- Date and time of contact +- Method of contact +- Person contacted +- Explanation received +- Whether the attendance event is excused or unexcused +- Next action + +### Step 4: Second Contact + +If no response is received, admin attempts a second contact. + +This may include: + +- Phone call +- Email +- Text message if permitted +- Contact through emergency contact +- Staff supervisor notification + +### Step 5: Escalation + +If no clarification is received after repeated attempts, the case is escalated to school leadership. + +For students, this may involve: + +- Attendance officer +- Counselor +- Grade-level administrator +- Parent meeting +- Student support team + +For staff, this may involve: + +- Direct supervisor +- HR +- Department head +- Formal attendance review + +--- + +## 16. Email and Call System + +The admin dashboard should include buttons or links for: + +- Send parent email +- Call parent +- Send staff email +- Call staff member +- Mark as contacted +- Mark as resolved +- Escalate case +- Add note +- View badge scan history +- Review entry and exit logs +- Review manual entry logs +- Print or reprint late slips + +### 16.1 Parent Email Template + +**Subject:** Attendance Clarification Needed + +Dear Parent/Guardian, + +Our records show that your child was marked absent, late, or dismissed early, and we have not yet received a reason for this attendance record. + +Please contact the school as soon as possible to clarify the reason. + +Thank you for your cooperation. + +Sincerely, +School Administration + +### 16.2 Staff Email Template + +**Subject:** Attendance Clarification Needed + +Dear Staff Member, + +Our records show that you were marked absent, late, or dismissed early, and we have not yet received a reason for this attendance record. + +Please contact the office or your supervisor as soon as possible to clarify the reason. + +Thank you. + +Sincerely, +School Administration + +### 16.3 Call Script for Parents + +Hello, this is the school office calling about your child’s attendance. Our records show that your child was absent, late, or dismissed early, and we have not yet received a reason. Could you please clarify the reason? + +### 16.4 Call Script for Staff + +Hello, this is the school office calling about your attendance record. Our system shows that you were absent, late, or dismissed early, and we have not yet received a reason. Could you please clarify the reason? + +--- + +## 17. Attendance Decisions + +Each attendance case must end with a clear decision. + +Possible decisions include: + +- Present, no action needed +- Present by verified manual entry +- Reported absence, excused +- Reported absence, unexcused +- Not-reported absence, pending clarification +- Not-reported absence, excused after clarification +- Not-reported absence, unexcused after no response +- Reported late, excused +- Reported late, unexcused +- Not-reported late, pending clarification +- Not-reported late, excused after clarification +- Not-reported late, unexcused after no response +- Late slip printed +- Late without slip +- Late slip verified by teacher +- Reported early dismissal, excused +- Not-reported early dismissal, pending clarification +- Unauthorized early dismissal +- Badge exception recorded +- Badge misuse investigation required +- Attendance support plan required +- Parent or staff meeting required +- Leadership escalation required +- External referral required if applicable + +--- + +## 18. Weekly Attendance Review + +At the end of each week, administrators will review: + +- Students with 1ABS to 5ABS +- Students with 1Late to 5Late +- Students with repeated early dismissals +- Students with combined attendance patterns +- Staff with repeated attendance concerns +- Not-reported cases still pending +- Cases requiring follow-up +- Unauthorized exits +- Badge scan exceptions +- Manual entry exceptions +- Late slips printed +- Late slips not printed +- Late students without slips +- Late slip reprints + +The weekly report should be shared with the appropriate school leaders. + +--- + +## 19. Monthly Attendance Report + +At the end of each month, the school will generate a report showing: + +- Total absences +- Total late arrivals +- Total early dismissals +- Total badge exceptions +- Total manual entries +- Total late slips printed +- Total late slip reprints +- Reported absences +- Not-reported absences +- Reported late arrivals +- Not-reported late arrivals +- Reported early dismissals +- Not-reported early dismissals +- Students with repeated attendance concerns +- Staff with repeated attendance concerns +- Follow-up actions completed +- Unresolved cases +- Improvement trends + +--- + +## 20. Roles and Responsibilities + +### 20.1 Teachers + +Teachers are responsible for: + +- Verifying classroom attendance against badge scans and manual entries. +- Checking late slips for students who arrive late. +- Sending students without late slips to the office. +- Reporting attendance concerns quickly. +- Notifying admin if attendance patterns affect learning. + +### 20.2 Admin Staff + +Admin staff are responsible for: + +- Monitoring the attendance dashboard. +- Monitoring badge scan activity. +- Completing authorized manual entries. +- Printing and reprinting late slips. +- Contacting parents, guardians, and staff. +- Recording explanations and decisions. +- Escalating unresolved cases. + +### 20.3 School Leadership + +School leadership is responsible for: + +- Reviewing repeated or serious cases. +- Approving intervention plans. +- Supporting meetings with parents, students, or staff. +- Ensuring attendance procedures are followed. +- Reviewing badge misuse, unauthorized exit, and repeated manual entry cases. + +### 20.4 Parents and Guardians + +Parents and guardians are responsible for: + +- Reporting student absence, lateness, or early dismissal as early as possible. +- Providing a reason for each attendance event. +- Attending meetings when required. +- Ensuring students understand badge and late slip expectations. + +### 20.5 Staff Members + +Staff members are responsible for: + +- Carrying and scanning their badge daily. +- Reporting absences, lateness, or early departures according to school policy. +- Reporting to the office for manual entry when badge scanning is not possible. +- Providing valid reasons when required. +- Following attendance expectations. + +--- + +## 21. Attendance Improvement Plan + +When a student or staff member reaches a high-risk level, the school may create an improvement plan. + +The plan should include: + +- Attendance concern summary +- Number of absences +- Number of late arrivals +- Number of early dismissals +- Badge scan compliance history +- Manual entry history +- Late slip history, for students +- Reported and not-reported cases +- Reasons provided +- Required improvement target +- Support offered +- Review date +- Consequences if attendance does not improve + +--- + +## 22. Recommended Dashboard Filters + +The attendance page should allow admins to filter by: + +- Present +- Present by badge scan +- Present by manual entry +- Absent +- Late +- Early Dismissal +- Reported absence +- Not-reported absence +- Reported late +- Not-reported late +- Reported early dismissal +- Not-reported early dismissal +- Missing badge scan +- Missing entry scan +- Missing exit scan +- Manual entry +- Manual exit entry +- Badge not issued +- Badge missing +- Badge lost +- Badge damaged +- Badge exception +- Unauthorized exit +- Late slip printed +- Late slip not printed +- Late without slip +- Late slip reprinted +- Late slip pending teacher verification +- Late slip verified by teacher +- Late reported with slip +- Late not-reported with slip +- 1ABS +- 2ABS +- 3ABS +- 4ABS +- 5ABS +- 1Late +- 2Late +- 3Late +- 4Late +- 5Late +- 1ED +- 2ED +- 3ED or more +- Combined ABS and Late +- Combined ABS, Late, and ED +- Pending parent contact +- Pending staff contact +- Resolved +- Escalated +- Grade level +- Class +- Department +- Date range + +--- + +## 23. System Data Requirements + +The attendance system should maintain the following core data fields. + +### 23.1 Person Record + +- Full name +- Student ID or employee ID +- Role: Student, Staff, Contractor, Visitor +- Grade or department +- Homeroom or assigned supervisor +- Parent or guardian contact, if applicable +- Staff supervisor or HR contact, if applicable +- Badge ID +- Badge status: Active, Not Issued, Lost, Missing, Damaged, Replaced + +### 23.2 Attendance Event Record + +- Person ID +- Date +- Attendance status +- Entry scan time +- Manual entry time +- Exit scan time +- Manual exit time +- Official entry time used for attendance +- Official exit time used for attendance +- Report status +- Reason +- Attendance count level +- Follow-up status +- Final decision + +### 23.3 Badge Event Record + +- Badge ID +- Person ID +- Scan type: Entry or Exit +- Scan time +- Scan location +- Scanner device ID +- Successful or failed scan +- Exception reason, if applicable + +### 23.4 Manual Entry Record + +- Person ID +- Manual entry time +- Manual exit time, if applicable +- Reason for manual entry +- Authorized staff user +- Verification method +- Notes +- Audit timestamp + +### 23.5 Late Slip Record + +- Slip number or barcode +- Student ID +- Date +- Late check-in time +- Print time +- Entry method +- Report status +- Reason +- Staff user +- Teacher verification status +- Reprint history + +--- + +## 24. System Rules Summary + +The attendance system must follow these rules: + +1. Badge scan is the preferred method of recording entry and exit. +2. Manual entry is allowed when a badge is not issued, missing, lost, damaged, or unavailable. +3. Manual entry time must become the official entry scan time. +4. Manual exit time must become the official exit scan time. +5. A late student must receive a printed late slip before going to class. +6. A student arriving late without a slip must be sent to the office or flagged as Late Without Slip. +7. Every absence, late arrival, early dismissal, missing scan, manual entry, and badge exception must be logged. +8. Not-reported attendance events must appear on the admin follow-up page. +9. Repeated absences, lateness, early dismissals, badge exceptions, and late slip issues must trigger escalation. +10. Every attendance concern must be closed with a documented decision. + +--- + +## 25. Final Rule + +Every absence, late arrival, early dismissal, missing badge scan, manual entry, late slip, late slip reprint, and unauthorized exit must be recorded, classified, followed up when needed, and closed with a clear decision. + +No not-reported absence, late arrival, early dismissal, badge scan exception, manual entry exception, or late slip issue should remain unresolved without documented contact attempts. + +The badge scanning system must support attendance accuracy, student safety, staff accountability, and timely communication with families. + +Badge data should be reviewed daily by administrators and used together with classroom verification, staff schedules, parent reports, manual entries, late slips, and approved absence records. + +A person should not be considered fully verified as present unless the system shows a valid entry scan or an approved manual verification. + +A student who arrives late should not be sent to class unless the system has recorded the late arrival and generated a late slip. diff --git a/routes/web.php b/routes/web.php index 0601b84b..21776f68 100644 --- a/routes/web.php +++ b/routes/web.php @@ -80,4 +80,10 @@ Route::middleware('web')->group(function () { ->name('teacher.calendar'); Route::middleware('auth')->get('app/teacher/calendar', [TeacherCalendarPageController::class, 'show']) ->name('app.teacher.calendar'); + Route::middleware('auth')->get('teacher/absence-vacation', function () { + return redirect('/app/teacher/absence-vacation'); + })->name('teacher.absence-vacation'); + Route::middleware('auth')->get('teacher/absence_vacation', function () { + return redirect('/app/teacher/absence-vacation'); + })->name('teacher.absence_vacation'); }); diff --git a/tests/Feature/Api/V1/Administrator/TeacherClassAssignmentControllerTest.php b/tests/Feature/Api/V1/Administrator/TeacherClassAssignmentControllerTest.php index 14d2497d..71b56602 100644 --- a/tests/Feature/Api/V1/Administrator/TeacherClassAssignmentControllerTest.php +++ b/tests/Feature/Api/V1/Administrator/TeacherClassAssignmentControllerTest.php @@ -19,7 +19,7 @@ class TeacherClassAssignmentControllerTest extends TestCase $this->seedTeacherUser(); $this->seedClassSection(); - Sanctum::actingAs($admin); + Sanctum::actingAs($admin, [], 'api'); $response = $this->getJson('/api/v1/administrator/teacher-class/assignments?school_year=2025-2026'); $response->assertOk(); @@ -35,7 +35,7 @@ class TeacherClassAssignmentControllerTest extends TestCase $teacher = $this->seedTeacherUser(); $classSectionId = $this->seedClassSection(); - Sanctum::actingAs($admin); + Sanctum::actingAs($admin, [], 'api'); $storeResponse = $this->postJson('/api/v1/administrator/teacher-class/assign', [ 'teacher_id' => $teacher->id, 'class_section_id' => $classSectionId, @@ -48,6 +48,8 @@ class TeacherClassAssignmentControllerTest extends TestCase 'teacher_id' => $teacher->id, 'class_section_id' => $classSectionId, 'position' => 'main', + 'semester' => 'Fall', + 'school_year' => '2025-2026', ]); $deleteResponse = $this->postJson('/api/v1/administrator/teacher-class/delete', [ @@ -62,6 +64,8 @@ class TeacherClassAssignmentControllerTest extends TestCase 'teacher_id' => $teacher->id, 'class_section_id' => $classSectionId, 'position' => 'main', + 'semester' => 'Fall', + 'school_year' => '2025-2026', ]); } @@ -75,6 +79,12 @@ class TeacherClassAssignmentControllerTest extends TestCase private function seedAdminUser(): User { + $roleId = DB::table('roles')->insertGetId([ + 'name' => 'administrator', + 'slug' => 'administrator', + 'is_active' => 1, + ]); + $userId = DB::table('users')->insertGetId([ 'firstname' => 'Admin', 'lastname' => 'User', @@ -92,6 +102,11 @@ class TeacherClassAssignmentControllerTest extends TestCase 'status' => 'Active', ]); + DB::table('user_roles')->insert([ + 'user_id' => $userId, + 'role_id' => $roleId, + ]); + return User::query()->findOrFail($userId); } diff --git a/tests/Feature/TeacherAbsenceVacationRouteTest.php b/tests/Feature/TeacherAbsenceVacationRouteTest.php new file mode 100644 index 00000000..552cb959 --- /dev/null +++ b/tests/Feature/TeacherAbsenceVacationRouteTest.php @@ -0,0 +1,45 @@ + $key, + 'app.cipher' => 'aes-256-cbc', + ]); + + $rawKey = base64_decode(substr($key, 7), true); + $this->app->instance('encrypter', new Encrypter($rawKey, 'aes-256-cbc')); + } + + public function test_authenticated_teacher_absence_vacation_route_redirects_to_spa_page(): void + { + $user = User::factory()->create(); + + $response = $this->actingAs($user)->get('/teacher/absence-vacation'); + + $response->assertRedirect('/app/teacher/absence-vacation'); + } + + public function test_authenticated_legacy_teacher_absence_vacation_route_redirects_to_spa_page(): void + { + $user = User::factory()->create(); + + $response = $this->actingAs($user)->get('/teacher/absence_vacation'); + + $response->assertRedirect('/app/teacher/absence-vacation'); + } +} diff --git a/tests/Unit/Services/Teachers/TeacherAssignmentServiceTest.php b/tests/Unit/Services/Teachers/TeacherAssignmentServiceTest.php index 05bf836e..73344c38 100644 --- a/tests/Unit/Services/Teachers/TeacherAssignmentServiceTest.php +++ b/tests/Unit/Services/Teachers/TeacherAssignmentServiceTest.php @@ -30,6 +30,8 @@ class TeacherAssignmentServiceTest extends TestCase 'teacher_id' => $teacherId, 'class_section_id' => $classSectionId, 'position' => 'main', + 'semester' => 'Fall', + 'school_year' => '2025-2026', ]); } @@ -43,6 +45,7 @@ class TeacherAssignmentServiceTest extends TestCase 'teacher_id' => $teacherId, 'class_section_id' => $classSectionId, 'position' => 'ta', + 'semester' => 'Fall', 'school_year' => '2025-2026', 'created_at' => now(), 'updated_at' => now(), @@ -60,6 +63,8 @@ class TeacherAssignmentServiceTest extends TestCase 'teacher_id' => $teacherId, 'class_section_id' => $classSectionId, 'position' => 'ta', + 'semester' => 'Fall', + 'school_year' => '2025-2026', ]); }