Feature: Add first-class Pagination, Sorting, and Filtering for Employees & Departments

## Summary

Implement consistent, performant pagination + sorting + filtering across `/api/employees` and `/api/departments`. Expose a clear query contract (with sane defaults), return typed metadata, and wire up the React UI with table controls (page size, sort, search, filter chips).

## Motivation

* Current list endpoints fetch everything, which hurts perf as data grows.
* UX needs standard table controls (page/pageSize/sort/search) and URL state.
* Aligns with Swagger/OpenAPI, improves testability, and enables caching.

## API Contract (proposed)

**Endpoints**

* `GET /api/employees`
* `GET /api/departments`

**Query params**

* `page` (int, default `0`) — 0-based
* `size` (int, default `10`, max `100`)
* `sort` (string, default `id,asc`) — format: `,`
* `q` (string, optional) — free-text search (name/email/title for employees; name for departments)
* `filters` (multi or CSV, optional) — e.g. `departmentId=3`, `ageRange=20-29`

**Response (example)**

```json
{
"content": [ /* items */ ],
"page": 0,
"size": 10,
"totalElements": 1234,
"totalPages": 124,
"sort": [{ "property": "id", "direction": "ASC" }],
"hasNext": true,
"hasPrevious": false
}
```

## Backend Tasks (Spring Boot)

* [ ] **Repository**: Use `PagingAndSortingRepository`/`JpaSpecificationExecutor` for both entities.
* [ ] **Specifications**: Build dynamic predicates for `q` and `filters` (case-insensitive).
* [ ] **Controller**: Accept `page`, `size`, `sort`, `q`, `filters` and return `Page → DTO`.
* [ ] **DTOs/Mapping**: Introduce lightweight list DTOs (MapStruct or manual).
* [ ] **Validation**: Clamp `size` (max 100); validate `sort` field against a whitelist.
* [ ] **Indexes**: Add DB indexes for common search/sort fields (`employee.name`, `employee.email`, `employee.department.id`, `department.name`).
* [ ] **Swagger**: Document params & schema; add examples.
* [ ] **Tests**: JUnit tests for pagination boundaries, multi-sort, q+filters combo, invalid params.

## Frontend Tasks (React)

* [ ] **Service layer**: Update `employeeService.js` / `departmentService.js` to pass query params.
* [ ] **State**: Keep `page`, `size`, `sort`, `q`, `filters` in URL query string (deep-linkable).
* [ ] **UI controls**:

* Pagination (next/prev, page size)
* Sort toggles on table headers
* Search box (debounced 300ms)
* Optional filter chips (e.g., Department, Age range)
* [ ] **Empty/Loading/Error** states polished.
* [ ] **Tests**: RTL tests for table interactions and URL/state sync.

## Acceptance Criteria

* ✅ Both endpoints return paged results with correct counts and metadata.
* ✅ Sorting works on whitelisted fields; invalid sort rejected with 400 + helpful message.
* ✅ Search `q` matches case-insensitive substrings on configured fields.
* ✅ React tables reflect and control page/sort/search via the URL.
* ✅ Swagger shows the new params and response schema with examples.
* ✅ Basic load test shows stable latency with `size` up to 100 on 10k rows.

## Nice-to-have (optional, separate PRs welcome)

* Cursor-based pagination variant for very large datasets.
* Server-side caching hints (ETag/Last-Modified) for stable queries.
* Export current result set to CSV via backend stream.

---