but if u dell that A202 was last year, and last year many fk use this, if u new update physics lab it will be affect for ole year all data right? so what is the solution
3:37 PM


Yes, exactly, it will affect old-year data if you update same master row.

Two safe solutions:

Snapshot (most common)
Keep room_id FK
Also store room_name_snapshot in slot
Old year shows snapshot, new year uses new value
Versioned master records (no snapshot)
Do not edit A202 row
Create new room row Physics Lab with new id
Old slots keep old room_id, new slots use new room_id
If your priority is “old year must never change”, use one of these two.
Directly editing same room row is not safe for history.

New Slot

Organisation *
Select organisation
Term *
Select organisation first
Staff Member *
Select organisation first
Course / Module
Select course (optional)
Room
Select room
Room Label
Capacity: 0 seats

Start Time *
04:00 PM
End Time *
05:00 PM
Class Start Date *
13-05-2026
Class End Date *
14-05-2026
Day of Week *
Mon
Tue
Wed
Thu
Fri
Sat
Sun
Cancel
Create Slot

# Academic Timetable Module Documentation

## 1) Module Goal
This module manages academic scheduling across 6 pages:
1. `AcademicStaff`
2. `AcademicTerms`
3. `AcademicCourses`
4. `AcademicRooms`
5. `AcademicTimetable`
6. `AcademicOverview` (HR read-only workload view)

It supports:
- Master data setup (staff/terms/courses/rooms)
- Slot scheduling with date-range + day-of-week loop creation
- Change logs and exports (CSV/PDF/ICS)

---

## 2) Codebase Map

## Frontend Pages
- `frontend/src/pages/AcademicStaff.tsx`
- `frontend/src/pages/AcademicTerms.tsx`
- `frontend/src/pages/AcademicCourses.tsx`
- `frontend/src/pages/AcademicRooms.tsx`
- `frontend/src/pages/AcademicTimetable.tsx`
- `frontend/src/pages/AcademicOverview.tsx`

## Frontend API client
- `frontend/src/api/services.ts` -> `academicTimetableAPI`

## Backend Controllers
- `backend/app/Http/Controllers/Api/AcademicTimetableController.php`
- `backend/app/Http/Controllers/Api/AcademicCourseController.php`

## Backend Models
- `backend/app/Models/AcademicTerm.php`
- `backend/app/Models/AcademicCourse.php`
- `backend/app/Models/AcademicRoom.php`
- `backend/app/Models/AcademicStaff.php`
- `backend/app/Models/AcademicTimetableSlot.php`
- `backend/app/Models/AcademicTimetableChangeLog.php`

## Migration/Seeder
- `backend/database/migrations/2026_07_20_000001_create_academic_timetable_tables.php`
- `backend/database/seeders/AcademicTimetableFakeDataSeeder.php`

---

## 3) Database Design (Core)

## 3.1 Master tables
- `academic_terms`
- `academic_courses`
- `academic_rooms`
- `academic_staff`

## 3.2 Transaction table
- `academic_timetable_slots`

Important slot columns:
- `term_id`
- `employee_id`
- `course_id`
- `course_code`
- `course_name`
- `room_id`
- `room_name`
- `room_label`
- `day_of_week`
- `start_time`
- `end_time`
- `recurrence`
- `slot_date`
- `status`
- `notes`

## Why store both IDs + names in slot?
- IDs (`course_id`, `room_id`) keep relational linkage.
- Copied fields (`course_code`, `course_name`, `room_name`, `room_label`) keep old slot display stable if masters are edited later.

---

## 4) Joins & Read Pattern

Typical slot list join (`AcademicTimetableController@index`):
- `academic_timetable_slots` + `academic_terms` + `hr_employee` + `academic_rooms`
- Scope by organization through term org.

Room display fallback:
- `COALESCE(academic_timetable_slots.room_name, academic_rooms.name)`

Course display:
- Slot list returns `course_code`, `course_name`
- Also aliased to `module_code`, `module_name` for frontend compatibility.

---

## 5) 6 Page Functional Documentation

## 5.1 Academic Staff (`AcademicStaff.tsx`)
### List
- Shows assigned academic staff by organization.
- Displays manager flag.

### Add
- Assign employee to org as academic staff.

### Edit
- Toggle manager status.

### Remove
- Remove assignment.

---

## 5.2 Academic Terms (`AcademicTerms.tsx`)
### List
- Columns: Year, Term name, Start/End date, Status, Actions.

### Add
- Create term with org + date range.

### Edit
- Update year/name/date/status.

### Delete
- Only if no active slots depend on term.

---

## 5.3 Academic Courses (`AcademicCourses.tsx`)
### List
- Columns: Code, Module name, Type, Status, Actions.

### Add
- Requires organization + department + module code + module name + lecture type.

### Edit
- Update code/name/type/status.

### Delete
- Blocked if course is referenced by active slots.

---

## 5.4 Academic Rooms (`AcademicRooms.tsx`)
### List
- Columns: Room name, Label/Floor, Capacity, Status, Actions.

### Add
- Create room with org/name/label/capacity.

### Edit
- Update name/label/capacity/status.

### Delete
- Standard delete with validations from backend.

---

## 5.5 Academic Timetable (`AcademicTimetable.tsx`)
### List
- Shows slot rows with employee, course/module, room, day/date, time, recurrence, status.

### Add (New Slot modal)
Current simple UI flow:
1. Organisation
2. Term
3. Staff Member
4. Course/Module
5. Room
6. Class Start Date
7. Class End Date
8. Day-of-week checkboxes
9. Start/End time

### Create behavior (backend)
In `store()`:
- If `class_start_date + class_end_date + days_of_week[]` provided:
  - Loop each date in range
  - Match selected weekdays
  - Insert one slot row per matched date
- While inserting each row:
  - Copy `course_code/course_name` from selected course
  - Copy `room_name/room_label` from selected room

### Edit behavior
In `update()`:
- Update selected slot row
- If `course_id` changed, refresh copied course fields
- If `room_id` changed, refresh copied room fields

### Delete behavior
- Soft delete + status cancellation + change log

### Change log
- Saved in `academic_timetable_change_logs`

---

## 5.6 Academic Overview (`AcademicOverview.tsx`)
### Purpose
- HR read-only workload and compliance view.

### Features
- Staff cards
- Weekly grid/list/workload/availability tabs
- Workload CSV and PDF export

### Notes
- UI currently static/mock-rich in frontend; export endpoints are real.

---

## 6) Key API Endpoints (v1)
Base: `/api/v1/academic-timetable`

## Staff
- `GET /staff`
- `POST /staff/assign`
- `PATCH /staff/{id}/toggle-manager`
- `DELETE /staff/{id}`

## Terms
- `GET /terms`
- `POST /terms`
- `PUT /terms/{id}`
- `DELETE /terms/{id}`

## Rooms
- `GET /rooms`
- `POST /rooms`
- `PUT /rooms/{id}`
- `DELETE /rooms/{id}`

## Courses
- `GET /courses`
- `POST /courses`
- `PUT /courses/{id}`
- `DELETE /courses/{id}`

## Slots
- `GET /`
- `POST /`
- `PUT /{id}`
- `DELETE /{id}`
- `GET /{id}/changes`

## Exports
- `GET /my/export.csv`
- `GET /my/export.ics`
- `GET /workload-report.csv`
- `GET /workload-report.pdf`

---

## 7) Rebuild Project (Academic module) Checklist

1. Run migrations (clean DB preferred for this module changes).
2. Seed academic fake data.
3. Create at least one:
- Organization
- Department
- Academic course
- Academic room
- Academic term
- Academic staff assignment
4. Open `AcademicTimetable` page and create new slot with date range + days.
5. Verify:
- Multiple slot rows inserted
- Course/room fields copied into slot
- Edit updates copied fields for that row
- List/export/change log works

---

## 8) Operational Rules

1. Organization scope is enforced server-side.
2. Leave conflict validation blocks invalid slot dates.
3. Status and soft-delete are both used for slot lifecycle.
4. For historical display consistency, use slot copied fields (`course_name`, `room_name`) in reporting views.

---

## 9) Future Enhancement Ideas

1. Bulk edit for generated slot series.
2. Conflict engine for room-time overlap.
3. Recurrence profile table (`series_id`) to track grouped schedules.
4. Advanced filters in list/export by org/term/course/room.

---

## 10) Quick Troubleshooting

1. "Nothing to migrate" after changing existing migration:
- Existing DB already ran migration. Use new alter migration or fresh rebuild.

2. Old non-academic migrations fail:
- Run targeted migration path or fix migration history first.

3. Slot insert created none:
- Date range + day checkboxes may have no matching day.
- Validate leave conflict messages.

# Probation Reviews & Performance Full - Technical Documentation

## 1. Probation Reviews

### 1.1 Purpose
The Probation Reviews module manages end-to-end probation workflows for employees, led by managers and HR oversight.

### 1.2 Core Functional Scope
- Create probation reviews
- Manage review objectives
- Capture scoring and narrative feedback
- Schedule and complete probation meetings
- Run sign-off and final decision workflow
- Keep auditability of changes and outcomes

### 1.3 Main User Personas
- **Manager**: Creates and drives probation reviews for direct reports
- **HR/Admin**: Monitors review status, compliance, and outcomes
- **Employee**: Participates in self-assessment/signing steps where enabled

### 1.4 Frontend Areas
Admin pages:
- `frontend/src/pages/ProbationReviews.tsx`
- `frontend/src/pages/ProbationList.tsx`
- `frontend/src/pages/ProbationReviewDetail.tsx`
- `frontend/src/pages/ProbationQuestions.tsx`

Employee/Manager pages:
- Manager probation pages in employee portal (list, detail, objectives)

### 1.5 Backend Controllers (Key)
- `backend/app/Http/Controllers/Api/ProbationReviewController.php`
- `backend/app/Http/Controllers/Api/ProbationQuestionController.php`
- `backend/app/Modules/Employee/Interfaces/Http/Controllers/ManagerProbationController.php`

### 1.6 Employee-Module API Routes (Key)
Under `manager/probation` and `manager/probation-objectives`:
- List my reviews
- List team reviews
- Create review
- Review detail + PDF
- Send self-assessment
- Score objective
- Save round review
- Save narrative
- Schedule/complete meeting
- Send for signing
- Manager sign
- Submit decision
- CRUD for objectives
- CRUD for objective categories/questions

(Defined in `backend/app/Modules/Employee/Interfaces/Routes/api.php`)

### 1.7 Domain Models (Key)
- `ProbationReview`
- `ProbationReviewObjective`
- `ProbationQuestionCategory`
- `ProbationQuestion`
- `ProbationReviewSignature`
- `ProbationReviewAuditLog`
- `ProbationReviewType`
- `ProbationResult`
- `HrEmployeeEmploymentProbationResult`

### 1.8 Workflow Summary
1. Manager creates probation review for an employee
2. Objectives/questions are assigned or customized
3. Progress and scoring are recorded by phase/round
4. Meeting is scheduled and completed
5. Narrative and recommendations are finalized
6. Signatures and final decision are captured
7. Outcome is stored for employment/probation history

### 1.9 Access & Permissions
- Manager-facing actions require manager route access and scoped employee context
- Admin pages are permission-gated through admin permission routes
- Data access is constrained by organizational/manager relationship

---

## 2. Performance Full

### 2.1 Purpose
The Performance Full module covers the full performance lifecycle including cycles, nominations, shortlist, analytics, feedback systems, and recognition/rewards.

### 2.2 Functional Components
- Performance cycles management
- Performance nominations and shortlist
- Performance analytics dashboards
- 360 feedback workflows
- Upward feedback workflows
- Recognition and rewards workflows

### 2.3 Frontend Areas
Admin pages (core):
- `frontend/src/pages/PerformanceCycles.tsx`
- `frontend/src/pages/PerformanceAnalytics.tsx`
- `frontend/src/pages/Feedback360Cycles.tsx`
- `frontend/src/pages/Feedback360Workspace.tsx`
- `frontend/src/pages/Feedback360QuestionSets.tsx`
- `frontend/src/pages/Feedback360QuestionSetEditor.tsx`
- `frontend/src/pages/RecognitionRewardsDashboard.tsx`
- `frontend/src/pages/RecognitionCreateNomination.tsx`
- `frontend/src/pages/RecognitionConfig.tsx`
- `frontend/src/pages/RecognitionDetail.tsx`

### 2.4 Backend Controllers (Key)
- `PerformanceCycleController`
- `PerformanceNominationController`
- `PerformanceShortlistController`
- `PerformanceScoringController`
- `PerformanceAnalyticsController`
- `PerformanceCertificateController`

Employee-side controllers:
- `EmployeeFeedbackController`
- `EmployeeRecognitionController`

### 2.5 Employee-Module API Route Groups
From employee module routes:
- `performance/*` (nominations and related performance actions)
- `feedback/*` (360 and upward review actions)
- `recognitions/*` (recognition submission/approval/view actions)

### 2.6 Domain Models (Key)
Performance:
- `HrPerformanceCycle`
- `HrPerformanceNomination`
- `HrPerformancePanelScore`
- `HrPerformanceScoringCriterion`
- `HrPerformanceAuditLog`
- `HrPerformanceAwardCategory`

Recognition:
- `Recognition`
- `RecognitionNomination`
- `RecognitionApproval`
- `RecognitionReward`
- `RecognitionCategory`
- `RecognitionAuditLog`
- `RecognitionBudgetLimit`

Feedback:
- Feedback review/answer/signoff entities
- Reviewer nomination and report entities

### 2.7 End-to-End Flow Summary
1. HR/Admin defines performance cycle(s)
2. Nominations are submitted and validated
3. Shortlisting and scoring process is run
4. Analytics/reporting dashboards update continuously
5. 360/upward feedback reviews are executed (where configured)
6. Recognition nominations and approvals are processed
7. Rewards and final outputs (certificates/reports/payroll sync hooks) are produced

### 2.8 Permissions & Governance
- Admin route access controlled by permission keys (e.g., performance, feedback, recognition permissions)
- Employee feature routes protected by feature middleware/flags
- Actions are role-bound and context-scoped (employee, manager, panel, approver)

### 2.9 Implementation Notes
- Module is split across multiple controllers and route groups for maintainability
- Admin and employee portals provide role-appropriate UX for the same lifecycle
- Audit logs and approval trail are central for traceability and governance