# Roles API

The Roles module manages role-based access control (RBAC) for the system.

## Model

```json
{
  "id": "uuid",
  "name": "Teacher",
  "description": "Teacher role with classroom permissions",
  "code": "TEACHER",
  "permissions": {
    "Student": ["list", "read"],
    "Attendance": ["list", "read", "create", "update"],
    "Class": ["list", "read"]
  },
  "team_id": "team-uuid",
  "created_at": "2024-01-01T00:00:00Z"
}
```

## Permissions Structure

Permissions are organized by module and action:

```json
{
  "ModuleName": ["action1", "action2"]
}
```

### Available Actions

| Action | Description |
|--------|-------------|
| `list` | View list of records |
| `read` | View single record details |
| `create` | Create new records |
| `update` | Modify existing records |
| `delete` | Delete records |
| `export` | Export records to Excel |
| `import` | Import records from Excel |

## Endpoints

### List Roles

**Endpoint:** `POST /api/roles/list`

!!! warning "Admin Only"
    Role management requires admin role.

### Get Role by ID

**Endpoint:** `GET /api/roles/:id`

### Create Role

**Endpoint:** `POST /api/roles`

**Request:**
```json
{
  "name": "Counselor",
  "description": "School counselor role",
  "code": "COUNSELOR",
  "permissions": {
    "Student": ["list", "read"],
    "Behavior": ["list", "read", "create", "update"],
    "Guardian": ["list", "read"]
  }
}
```

### Update Role

**Endpoint:** `PUT /api/roles/:id`

### Delete Role

**Endpoint:** `DELETE /api/roles/:id`

### Save Permissions

Update role permissions:

**Endpoint:** `PUT /api/roles/:id/save_permission`

**Request:**
```json
{
  "permissions": {
    "Student": ["list", "read", "create"],
    "Attendance": ["list", "read", "create", "update", "delete"]
  }
}
```

## User-Role Assignment

### Assign Users to Role

**Endpoint:** `PUT /api/roles/:id/assign`

**Request:**
```json
{
  "user_ids": ["user-uuid-1", "user-uuid-2"]
}
```

### Remove Users from Role

**Endpoint:** `PUT /api/roles/:id/remove`

**Request:**
```json
{
  "user_ids": ["user-uuid-1"]
}
```

## Built-in Roles

| Role | Description |
|------|-------------|
| `Root` | Super admin with all permissions |
| `Admin` | Administrative staff |
| `Teacher` | Teaching staff |
| `Student` | Student (limited access) |
| `Guardian` | Parent/guardian (limited access) |

## Permission Check

The system checks permissions via middleware:

```go
middlewares.PermissionMiddleware("Student", "create", "")
```

Returns 403 Forbidden if user lacks required permission.