# Admin Position Template Scope and Visibility

## Purpose

Position access templates with the default role `ADMIN` can now configure the same important targeting controls used by other administrative roles:

- **Scope access** selects the brands stored with the template.
- **Advanced role visibility** selects the employee roles and positions an Admin can view.

`SUPERADMIN` remains unrestricted and its advanced visibility editor is not exposed.

## User workflow

1. Open **Users**.
2. Open **Manage Position Templates**.
3. Select a position and create or edit a template.
4. Set **Default role** to `ADMIN`.
5. Select the required roles and positions under **Advanced role visibility**.
6. Enable the required brands under **Scope access** and select a default brand.
7. Save the template.
8. Apply the template to the position users.

## Behavior

- Advanced role visibility is shown and expanded automatically for an `ADMIN` template.
- `ADMIN` may include the `ADMIN` role in its visible-role selection, but cannot select `SUPERADMIN`.
- Selected role and position visibility is stored in `user_role_list` and therefore affects every user assigned the `ADMIN` role.
- Selected brands are stored in `position_access_template_brand_scope` and copied to `user_brand_access` when the template is applied.
- Leaving every brand disabled preserves the existing global Admin fallback.
- An empty Admin role-visibility list preserves the existing unrestricted Admin behavior.
- Once one or more Admin visibility choices are saved, employee, attendance, attendance-summary, and payroll queries enforce those selections.
- `BRAND_ADMIN` still requires at least one enabled brand with the `admin` access level.
- Only a `SUPERADMIN` can create, change, or apply templates whose default role is `ADMIN` or `SUPERADMIN`.

## Data flow

```mermaid
flowchart LR
    A[Position Template Launcher] --> B[Select ADMIN role]
    B --> C[Advanced role visibility]
    B --> D[Scope access]
    C --> E[user_role_list]
    D --> F[position_access_template_brand_scope]
    E --> G[Employee, attendance and payroll filtering]
    F --> H[Apply template]
    H --> I[user_brand_access]
```

## Database installation

Normal installations that already applied the position access-control migrations require no additional schema migration. The feature uses the existing `visible_roles`, `visible_positions`, and `position_access_template_brand_scope` structures.

For a manual or partially upgraded database, import the standalone script. It requires the base `position_access_templates` table; run `20260831_position_access_control.sql` first when that table is missing.

```text
backend/migrations/20260831_admin_position_template_scope_visibility.sql
```

Example:

```powershell
mysql.exe -u your_user -p your_database -e "source backend/migrations/20260831_admin_position_template_scope_visibility.sql"
```

The script is non-destructive and rerunnable. It creates only missing structures and finishes with verification queries. Back up a production database before running schema changes.

## Modified files

### Frontend

- `frontend/src/users/PositionTemplateManagerModal.jsx`

### Backend

- `backend/users/templates/save.php`
- `backend/employeesSide/employees.php`
- `backend/attendance/attendance.php`
- `backend/attendance/get_attendance_aggregates.php`
- `backend/payroll/payroll.php`

### New files

- `backend/migrations/20260831_admin_position_template_scope_visibility.sql`
- `docs/admin-position-template-scope-visibility.md`

## Verification

- PHP syntax checks passed for every modified backend file.
- Focused ESLint passed for the Position Template Manager.
- The frontend production build passed.
- `git diff --check` passed.

## Important note

Advanced visibility belongs to the role, not one individual template assignment. Changing `ADMIN` visibility from a position template changes what all users with the `ADMIN` role can view. Brand scope is stored per template and copied to each user when that template is applied.