# Interview Module

The Interview module coordinates candidate interviews, schedules participants and records feedback for recruitment.

## Database Schema

**interview_stages**
- `id` INT PRIMARY KEY
- `name` VARCHAR
- `sequence` INT
- `description` TEXT

**interviews**
- `id` INT PRIMARY KEY
- `application_id` INT
- `stage_id` INT
- `calendar_event_id` INT NULL
- `status` VARCHAR
- `scheduled_start` DATETIME
- `scheduled_end` DATETIME
- `created_by` INT
- `created_at` DATETIME

**interview_participants**
- `id` INT PRIMARY KEY
- `interview_id` INT FOREIGN KEY
- `employee_id` INT FOREIGN KEY
- `role` VARCHAR
- `rsvp_status` VARCHAR

**interview_feedback**
- `id` INT PRIMARY KEY
- `interview_id` INT FOREIGN KEY
- `reviewer_id` INT
- `score` INT
- `notes` TEXT
- `created_at` DATETIME

## API Endpoints

The module follows the REST pattern `/api/{resource}` with custom actions.

### Basic CRUD
```
GET    /api/interviews               # list interviews
POST   /api/interviews               # create interview
GET    /api/interviews/{id}          # view interview
PUT    /api/interviews/{id}          # update interview
DELETE /api/interviews/{id}          # delete interview

GET    /api/interview_stages         # list stages
POST   /api/interview_stages         # create stage
GET    /api/interview_stages/{id}    # view stage
PUT    /api/interview_stages/{id}    # update stage
DELETE /api/interview_stages/{id}    # delete stage
```

### Interview Actions
```
POST /api/interviews/{id}/schedule       # set start/end times and calendar event
POST /api/interviews/{id}/addParticipant # assign participant
POST /api/interviews/{id}/changeStage    # move to a new stage
POST /api/interviews/{id}/updateStatus   # update status only
GET /api/interviews/availableSlots       # find open time slots
POST /api/interviews/{id}/feedback       # record feedback
```

### Reports
```
GET /api/interviewreports/turnaroundTime
GET /api/interviewreports/noShowRates
GET /api/interviewreports/interviewerLoad?start=YYYY-MM-DD&end=YYYY-MM-DD
GET /api/interviewreports/candidatePerformance
```
## Multi-Step Scheduling

The scheduling wizard guides users through three stages:
1. **Select Participants** – choose employees who will attend.
2. **Meeting Details** – enter duration and call `GET /api/interviews/availableSlots` to fetch open times.
3. **Pick Time Slot** – select one slot for all chosen candidates.

After completing the wizard, a draft interview record is created per candidate. HR finalizes each interview by setting its status to `Confirmed` using `POST /api/interviews/{id}/updateStatus`.


## Usage Examples

### Schedule an Interview
```bash
curl -X POST -b cookie.txt \
  -H 'Content-Type: application/json' \
  -d '{"scheduled_start":"2024-06-01 10:00","scheduled_end":"2024-06-01 11:00"}' \
  http://localhost/api/interviews/5/schedule
```

### Add a Participant
```bash
curl -X POST -b cookie.txt \
  -H 'Content-Type: application/json' \
  -d '{"employee_id":3,"role":"Interviewer"}' \
  http://localhost/api/interviews/5/addParticipant
```
### Find Available Slots
```bash
curl -b cookie.txt "http://localhost/api/interviews/availableSlots?employee_ids=3,4&duration=60"
```

### Submit Feedback
```bash
curl -X POST -b cookie.txt \
  -H 'Content-Type: application/json' \
  -d '{"reviewer_id":3,"score":8,"notes":"Good fit"}' \
  http://localhost/api/interviews/5/feedback
```

## Required Permissions

Only users with the `Super Admin` or `Admin` role may modify interviews and stages. Grant `interviews.getAll` to roles that should view schedules.

## Workflow Triggers

Audit events such as `interview_schedule`, `interview_reschedule` and `interview_cancel` are logged. Workflows can listen for these names to send notifications or update records.