> ## Documentation Index
> Fetch the complete documentation index at: https://docs.criar.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Staff Management

> School employee registry, role-based access control (RBAC) via designations, and leave management.

## 1. API Purpose

The Staff Management API allows school administrators to manage their team. It defines designations with specific permissions that gate access to features within the Teacher App.

***

## 2. Endpoint Definition

| Method | Route                                  | Auth   | Description                  |
| ------ | -------------------------------------- | ------ | ---------------------------- |
| GET    | `/web-app/staff`                       | 🔐 JWT | List all school staff        |
| POST   | `/web-app/staff`                       | 🔐 JWT | Register a new staff member  |
| GET    | `/web-app/staff/:id`                   | 🔐 JWT | View single staff profile    |
| PUT    | `/web-app/staff/:id`                   | 🔐 JWT | Update staff information     |
| POST   | `/web-app/staff/:id/assign-students`   | 🔐 JWT | Map students to a teacher    |
| POST   | `/web-app/staff/:id/unassign-students` | 🔐 JWT | Remove students from teacher |
| POST   | `/web-app/staff/:id/reset-pin`         | 🔐 JWT | Force reset staff PIN        |
| POST   | `/web-app/staff/:id/archive`           | 🔐 JWT | Archive staff member record  |

***

## 3. Authentication Flow

Standard JWT validation.

* Only users with Admin roles can access these endpoints.
* Staff members can view their own profile data via the Auth response or the [Profile API](/skole/api/14-profile-notifications).

***

## 4. Request Structure

#### GET /web-app/staff

**Query Parameters:**

| Field     | Type   | Required | Description                        |
| --------- | ------ | -------- | ---------------------------------- |
| skole\_id | string | Yes      | School identifier.                 |
| search    | string | No       | Search by name or phone.           |
| status    | string | No       | Enum: `active`, `archived`, `all`. |

#### POST /web-app/staff

**Request Body:**

```json theme={null}
{
  "name": "Sarah Miller",
  "designation": "Class Teacher",
  "phone_no": "9876543210",
  "email": "sarah.m@skole.com",
  "rbac": { "attendance": "manage", "diary": "manage" },
  "addresses": [
    {
      "address_type": "current",
      "address": "123 School Lane",
      "city": "Springfield",
      "pincode": 627001
    }
  ]
}
```

#### GET /web-app/staff/:id

**URL Parameters:**

| Field | Type   | Description               |
| ----- | ------ | ------------------------- |
| id    | number | Unique staff database ID. |

#### PUT /web-app/staff/:id

**Request Body:**

```json theme={null}
{
  "designation": "Senior Teacher",
  "email": "sarah.miller@skole.com"
}
```

#### POST /web-app/staff/:id/assign-students

**Request Body:**

```json theme={null}
{
  "student_ids": [45, 46, 47]
}
```

#### POST /web-app/staff/:id/unassign-students

**Request Body:**

```json theme={null}
{
  "student_ids": [45]
}
```

#### POST /web-app/staff/:id/reset-pin

**Request Body:**

```json theme={null}
{
  "pin": "1234"
}
```

#### POST /web-app/staff/:id/archive

**URL Parameters:**

| Field | Type   | Description                 |
| ----- | ------ | --------------------------- |
| id    | number | Staff ID to archive/toggle. |

***

## 5. Response Structure

#### Success: Staff List (200 OK)

**Route:** `GET /web-app/staff`

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id": 10,
      "name": "Sarah Miller",
      "designation": "Class Teacher",
      "status": "active"
    }
  ]
}
```

#### Success: Staff Registered (201 Created)

**Route:** `POST /web-app/staff`

```json theme={null}
{
  "success": true,
  "message": "Staff member registered successfully",
  "data": { "id": 11 }
}
```

#### Success: Staff Profile View (200 OK)

**Route:** `GET /web-app/staff/:id`

```json theme={null}
{
  "success": true,
  "data": {
    "id": 10,
    "name": "Sarah Miller",
    "designation": "Class Teacher",
    "phone_no": "9876543210"
  }
}
```

#### Success: Profile Updated (200 OK)

**Route:** `PUT /web-app/staff/:id`

```json theme={null}
{
  "success": true,
  "message": "Staff profile updated"
}
```

#### Success: Students Assigned (201 Created)

**Route:** `POST /web-app/staff/:id/assign-students`

```json theme={null}
{
  "success": true,
  "message": "Students successfully mapped to teacher"
}
```

#### Success: Students Unassigned (201 Created)

**Route:** `POST /web-app/staff/:id/unassign-students`

```json theme={null}
{
  "success": true,
  "message": "Students unmapped from teacher"
}
```

#### Success: PIN Reset (201 Created)

**Route:** `POST /web-app/staff/:id/reset-pin`

```json theme={null}
{
  "success": true,
  "message": "Staff login PIN forced reset"
}
```

#### Success: Record Archived (201 Created)

**Route:** `POST /web-app/staff/:id/archive`

```json theme={null}
{
  "success": true,
  "message": "Staff record archived"
}
```

***

## 6. Error Responses

| HTTP Code | Description                                          |
| --------- | ---------------------------------------------------- |
| 409       | Staff member with this phone/email already exists    |
| 403       | Forbidden: Only Super Admins can manage designations |

***

## 7. Security Considerations

* **Encryption:** Staff PINs are hashed using `bcrypt`.
* **RBAC Enforcement:** The Teacher App reads the RBAC JSON on login to dynamically enable/disable menu items and UI controls.

***

## 8. Token Usage

```http theme={null}
GET /web-app/staff
Authorization: Bearer <ADMIN_TOKEN>
```

***

## 9. Token Refresh

N/A.

***

## 10. Logout / Session Invalidation

N/A.

***

## 11. Usage Example (cURL)

```bash theme={null}
curl -X POST http://localhost:3000/web-app/staff/1/assign-students \
-H "Authorization: Bearer <TOKEN>" \
-d '{"student_ids": [45, 46]}'
```

***

## 12. Notes / Special Behaviors

* **Status Toggle:** Setting a staff member's status to `0` immediately revokes their Teacher App access, even if their token hasn't expired (checked via session middleware).
* **Multi-School Staff:** A staff member can theoretically belong to multiple schools, but their session is always scoped to a single `skole_id`.