Feature: RBAC (Roles & Permissions) + Audit Trail (+ optional Admin Impersonation)

### Summary

Introduce **Role-Based Access Control** with granular **permissions** and an **audit trail** of sensitive actions. (Optional: safe **admin impersonation** for support.) Seed roles: `ADMIN`, `HR`, `MANAGER`, `EMPLOYEE`.

---

#### Why

* Enterprise staple: least-privilege access and traceability.
* Protects employee PII and HR operations (create/update/delete).
* Makes demo production-grade and aligns with login/registry already present.

---

#### Scope (v1)

1. **RBAC**

* Roles + permissions enforced via Spring Security annotations and custom voters.
* Endpoint & data-level guards (employees/departments).
2. **Audit Trail**

* Persist “who did what, when, to which resource, from which IP/UA”.
3. **Admin UI**

* Manage user roles, view audit entries (filter/sort/export).
4. **OpenAPI/Swagger**

* Document new endpoints + security schemes.
5. **(Optional) Impersonation**

* ADMIN can assume a user temporarily (token with `impersonated=true` claim) with full trace + banner in UI.

---

#### Data Model (MySQL)

```sql
-- roles & permissions
CREATE TABLE roles (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
name VARCHAR(64) UNIQUE NOT NULL, -- ADMIN | HR | MANAGER | EMPLOYEE
description VARCHAR(255)
);

CREATE TABLE permissions (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
name VARCHAR(128) UNIQUE NOT NULL, -- EMPLOYEE_READ, EMPLOYEE_CREATE, ...
description VARCHAR(255)
);

CREATE TABLE role_permissions (
role_id BIGINT NOT NULL,
permission_id BIGINT NOT NULL,
PRIMARY KEY (role_id, permission_id),
FOREIGN KEY (role_id) REFERENCES roles(id),
FOREIGN KEY (permission_id) REFERENCES permissions(id)
);

-- user ↔ role (assuming a users table exists or augment current auth model)
CREATE TABLE user_roles (
user_id BIGINT NOT NULL,
role_id BIGINT NOT NULL,
PRIMARY KEY (user_id, role_id)
);

-- audit log
CREATE TABLE audit_logs (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
actor_user_id BIGINT,
action VARCHAR(64) NOT NULL, -- CREATE_EMPLOYEE, UPDATE_DEPARTMENT, LOGIN, IMPERSONATE_START, ...
resource_type VARCHAR(64) NOT NULL, -- EMPLOYEE | DEPARTMENT | USER | AUTH
resource_id VARCHAR(64) NULL,
details JSON NULL,
ip VARCHAR(64) NULL,
user_agent VARCHAR(255) NULL,
impersonated TINYINT(1) DEFAULT 0
);
```

**Seed permissions (suggested):**

* `EMPLOYEE_READ`, `EMPLOYEE_CREATE`, `EMPLOYEE_UPDATE`, `EMPLOYEE_DELETE`
* `DEPARTMENT_READ`, `DEPARTMENT_CREATE`, `DEPARTMENT_UPDATE`, `DEPARTMENT_DELETE`
* `USER_READ`, `USER_ROLE_ASSIGN`
* `AUDIT_READ`, `IMPERSONATE_USER` *(optional)*

**Seed role mappings (example):**

* `ADMIN`: all permissions
* `HR`: EMPLOYEE\_\* + DEPARTMENT\_\* + AUDIT\_READ
* `MANAGER`: EMPLOYEE\_READ, EMPLOYEE\_UPDATE (own dept), DEPARTMENT\_READ
* `EMPLOYEE`: EMPLOYEE\_READ (self only)

---

#### Backend (Spring Boot)

* Add Spring Security config:

* JWT filter: extract roles/permissions into `SecurityContext`.
* Method security: `@PreAuthorize("hasAuthority('EMPLOYEE_CREATE')")` etc.
* Add AOP/Filter for **audit logging** on protected endpoints (success + key failures).
* Controllers:

* `POST /api/admin/users/{id}/roles` (assign roles)
* `GET /api/admin/roles` / `GET /api/admin/permissions`
* `GET /api/admin/audit` (paged, filter by actor, action, resource, date)
* `(opt) POST /api/admin/impersonate/{userId}` → returns short-lived JWT with `impersonated=true`
* `(opt) POST /api/admin/impersonate/stop`
* Add data scoping helpers (e.g., manager can update employees in their department only).
* Swagger/OpenAPI:

* Add `bearerAuth` security scheme + annotate new endpoints.
* Tests (JUnit5):

* Permission matrix tests for each protected route.
* Audit log written for create/update/delete & impersonation.
* Token with/without authorities.

---

#### Frontend (React)

* **Admin → Roles & Permissions** page:

* List users, current roles, assign/remove roles (multi-select).
* **Admin → Audit Logs**:

* Table with filters (date, actor, action, resource), CSV export.
* UI cues:

* Hide/disable buttons the user can’t perform.
* (opt) Impersonation banner with “Stop impersonating”.
* Error toasts for 403/401; auto-refresh tokens as today.

---

#### Security & Compliance

* Principle of least privilege; deny by default.
* Token contains roles/permissions (or role IDs; permissions resolved server-side).
* Audit entries immutable; expose read-only API.
* Rate-limit admin endpoints.
* Ensure CORS config stays tight.

---

#### Acceptance Criteria

* Users with insufficient permissions are blocked (HTTP 403) and no state changes occur.
* Admin can assign roles; changes take effect on next token refresh.
* All create/update/delete on Employees/Departments generate audit entries with actor, resource, and timestamp.
* Swagger shows secured endpoints and can authorize via JWT.
* (opt) Impersonation flows are fully logged and visibly indicated in UI.

---

#### Tasks

**Backend**

* [ ] DB migrations for roles/permissions/audit tables + seed data.
* [ ] Spring Security config + JWT authority mapping.
* [ ] Permission checks on existing controllers (`employees`, `departments`).
* [ ] Admin controllers for roles/permissions, audit listing.
* [ ] Audit AOP/Filter + log writer.
* [ ] (opt) Impersonation endpoints + token claims.
* [ ] Swagger updates.
* [ ] JUnit tests for auth matrix + audit.

**Frontend**

* [ ] Admin pages: Role assignment, Audit log viewer.
* [ ] Permission-aware UI (disable/hide actions).
* [ ] (opt) Impersonation banner & stop action.
* [ ] Error handling & toasts.

**Docs/DevOps**

* [ ] Update `README.md`, `openapi.yaml`, `.env.example` (JWT/AUDIT settings).
* [ ] Seed script or SQL dump for roles/permissions.
* [ ] CI: run new backend tests; minimal e2e happy-path.

---

#### Open Questions

* Do we store **permissions** explicitly in JWT, or only **roles** and resolve permissions server-side for flexibility?
* Data scoping rules for MANAGER: by department only, or also by location/team?
* Audit retention policy (e.g., 180 days) + export limits.

---