# Position-Based Access Control ## Purpose This feature lets administrators create reusable access templates for a position. When an employee receives that position, the system can apply the template's role, menus, permissions, brand access, and visibility rules. ## Access flow ```mermaid flowchart TD A[Create or edit position] --> B{Configure access now?} B -- Yes --> C[Create or update position template] C --> D[Choose role, menus, permissions and brand scope] D --> E[Save template] E --> F[Apply template to matching employee users] B -- No --> G[Position has no configured access] G --> H[Employee role with no administrative access] I[Employee position changes] --> J{Exactly one active template?} J -- Yes --> F J -- No --> H ``` ## Administrator workflow 1. Open the Users page. 2. Select **Manage Position Templates** beside the search field. 3. Select a position. 4. Create or update its access template. 5. Configure the default role, menus, permissions, visible roles, visible positions, and brand scope. 6. Save the template and apply it to the selected employee or all employees with that position. The same configuration window can be opened immediately after creating a position from the Position modal or Employee modal. ## Rules - A position with exactly one active template is applied automatically when an employee is moved into that position. - A position without a template defaults to the `employee` role. - If a position has zero or multiple active templates, the system does not guess which template to apply. - Moving an employee away from a templated position removes the stale template assignment and its access. - Manual access changes are tracked as user overrides. - Template edits increment the template version. - `ADMIN` and `SUPERADMIN` receive the dedicated `users.access.view` and `users.access.manage` permissions. - Advanced Role Visibility supports both visible roles and visible positions. - `ADMIN` templates always expose Scope Access and Advanced Role Visibility; empty selections preserve the established unrestricted Admin fallback. - Brand Admin access is limited by the brands stored in the template's brand scope. - Branch Managers are restricted on the server to branches where `branches.assigned_employee_id` matches their employee ID. ## Database installation The normal installation method is: ```powershell php backend/scripts/migrate.php ``` For a manual database installation, import: ```text backend/migrations/20260831_position_access_control.sql ``` For the separate Admin scope and visibility compatibility script, see: ```text backend/migrations/20260831_admin_position_template_scope_visibility.sql ``` Detailed behavior is documented in `docs/admin-position-template-scope-visibility.md`. The standalone SQL file is non-destructive and can be rerun. Create a database backup before applying schema changes in production. ## API endpoints | Endpoint | Method | Purpose | | --- | --- | --- | | `/api/users/templates/list` | GET | Load templates, assignment, brands, and available positions | | `/api/users/templates/save` | POST | Create or update a template | | `/api/users/templates/apply` | POST | Apply a template to one user or all matching users | | `/api/users/templates/delete` | POST | Deactivate a template and clear related assignments | The endpoints accept a `username` when configuring an existing employee or a `position_id` when configuring a newly created position that has no employee yet. ## Verification status - All four PHP migrations are applied. - PHP syntax passed for all changed backend files. - Focused frontend lint passed with no errors. - The production frontend build passed. - Database validation found no orphan templates, position mismatches, invalid assignment versions, or missing Brand Admin scope. - Employee login no longer requests the protected role-list endpoint during root redirection. - Branch Manager filtering is implemented, but a branch-manager account must be assigned to a branch for an end-to-end data test. - The project test suite currently has 35 passing and 4 pre-existing unrelated failures involving attendance contracts and legacy direct network clients. ## Modified files ### New backend files - `backend/migrations/20260831_001_user_access_permissions.php` - `backend/migrations/20260831_002_position_access_templates.php` - `backend/migrations/20260831_003_position_access_template_brand_scope.php` - `backend/migrations/20260831_004_role_visible_positions.php` - `backend/migrations/20260831_position_access_control.sql` - `backend/server/branch_scope.php` - `backend/users/position_access_assignment_helper.php` - `backend/users/templates/apply.php` - `backend/users/templates/delete.php` - `backend/users/templates/list.php` - `backend/users/templates/save.php` - `backend/users/templates/template_apply_service.php` - `backend/users/user_access_catalog.php` - `backend/users/user_access_policy.php` ### Modified backend files - `backend/config/employee_assignment_helper.php` - `backend/employee_assignment/reassign_employee_assignment.php` - `backend/employeesSide/add_employee.php` - `backend/attendance/attendance.php` - `backend/attendance/attendance_requests.php` - `backend/attendance/get_attendance_aggregates.php` - `backend/attendance/schedule_status.php` - `backend/brand_api/assign_branch_manager.php` - `backend/departments/department.php` - `backend/departments/positions/fetch_positions.php` - `backend/employeesSide/bulk_update_employees.php` - `backend/employeesSide/employees.php` - `backend/employeesSide/update_employee.php` - `backend/late_request_clockInOut/get_late_attendance_requests.php` - `backend/leaveAPIAdmin/get_archived_leaves.php` - `backend/leaveAPIAdmin/read_leave.php` - `backend/overtime/overtime_request.php` - `backend/payroll/payroll.php` - `backend/schedule-manager/get-employee-grouped.php` - `backend/server/admin_request.php` - `backend/user_access_api/read_user_brand_access.php` - `backend/user_access_api/save_user_brand_access.php` - `backend/user_role_lists/add_role.php` - `backend/user_role_lists/delete_role.php` - `backend/user_role_lists/get_roles.php` - `backend/user_role_lists/update_role.php` - `backend/users.php` - `backend/users/get_access.php` - `backend/users/get_user_access.php` - `backend/users/menu/getAllUsers.php` - `backend/users/menu/getMenuAccess.php` - `backend/users/menu/update_menu_access.php` - `backend/users/permissions.php` - `backend/users/update_access.php` - `backend/users/update_user_access.php` - `backend/users/update_users.php` - `backend/users/users.php` - `backend/tests/run.php` ### New frontend files - `frontend/src/users/PositionTemplateLauncher.jsx` - `frontend/src/users/PositionTemplateManagerModal.jsx` - `frontend/src/users/hooks/useAccessTemplates.jsx` ### Modified frontend files - `frontend/src/App.jsx` - `frontend/src/authentication/ProtectedRoute.jsx` - `frontend/src/authentication/RoleBaseRedirect.jsx` - `frontend/src/authentication/useRoles.jsx` - `frontend/src/components/dashboard/taskManager.jsx` - `frontend/src/components/departments/department.jsx` - `frontend/src/components/departments/positions/positions.jsx` - `frontend/src/components/employees/EmployeeModal.jsx` - `frontend/src/components/employees/employees.jsx` - `frontend/src/components/employees/empAndDepHooks/useEmployeeAndDep.js` - `frontend/src/components/employees/employeeAPI/EmployeeAndDepAPI.js` - `frontend/src/components/schedule-manager/schedule-manager-components/LayouSMDashboard.jsx` - `frontend/src/components/schedule-manager/schedule-manager-components/components/ScheduleGrid.jsx` - `frontend/src/components/user_role_lists/hooks/useRoles.jsx` - `frontend/src/components/utils/axiosInstance.js` - `frontend/src/features/brandManagement/components/ScopeAccessSection.jsx` - `frontend/src/users/AccessModal.jsx` - `frontend/src/users/UserManagementBreadcrumbs.jsx` - `frontend/src/users/Users.jsx` - `frontend/src/users/hooks/usePermissions.jsx` - `frontend/src/users/userAccessComponents/ConfirmPopup.jsx` - `frontend/src/users/userAccessComponents/permissions.jsx` - `frontend/src/users/users_dashboard/usersDashboard.jsx` ### Documentation - `docs/fullscreen-schedule-approvals-and-employee-transfers.md` - `docs/position-access-control.md` Runtime log files are intentionally omitted from this source-code list.