# Disciplinary Module

The Disciplinary module manages employee violation records and related actions. It stores case details, evidence files, interviews and final decisions.

## Database Schema

**violation_types**
- `id` INT PRIMARY KEY
- `name` VARCHAR
- `handbook_ref` VARCHAR

**disciplinary_cases**
- `id` INT PRIMARY KEY
- `employee_id` INT
- `violation_id` INT
- `severity` ENUM(minor, major, critical)
- `summary` TEXT
- `status` ENUM(open, under_review, closed)
- `assigned_to` INT (user id)
- `created_at` DATETIME

**case_evidence**
- `id` INT PRIMARY KEY
- `case_id` INT FOREIGN KEY
- `file_path` VARCHAR
- `description` TEXT

**interview_logs**
- `id` INT PRIMARY KEY
- `case_id` INT FOREIGN KEY
- `person` VARCHAR
- `notes` TEXT
- `logged_at` DATETIME

**disciplinary_actions**
- `id` INT PRIMARY KEY
- `case_id` INT FOREIGN KEY
- `action` VARCHAR
- `effective_date` DATE
- `approved_by` INT
- `created_at` DATETIME

**appeals**
- `id` INT PRIMARY KEY
- `case_id` INT FOREIGN KEY
- `employee_id` INT
- `reason` TEXT
- `status` ENUM(submitted, review, resolved)
- `created_at` DATETIME

## API Endpoints

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

### Basic CRUD
```
GET    ../api/disciplinarycases            # list cases
POST   ../api/disciplinarycases            # create case
GET    ../api/disciplinarycases/{id}       # view case
PUT    ../api/disciplinarycases/{id}       # update case
DELETE ../api/disciplinarycases/{id}       # delete case
```

### Case Actions
```
POST ../api/disciplinarycases/{id}/addEvidence
POST ../api/disciplinarycases/{id}/logInterview
POST ../api/disciplinarycases/{id}/assignOfficer
POST ../api/disciplinarycases/{id}/recordAction
POST ../api/disciplinarycases/{id}/changeStatus
```

### Appeals
```
POST ../api/appeals/submit/{caseId}
POST ../api/appeals/review/{id}
```

### Reports
```
GET ../api/reports/disciplinaryTrends?start=YYYY-MM-DD&end=YYYY-MM-DD
```
Add `export=csv|pdf|xlsx` to download the data.
Returns counts grouped by violation type and month.

## Usage Examples

### Create a Case
```bash
curl -X POST -b cookie.txt \
  -H 'Content-Type: application/json' \
  -d '{"employee_id":2,"violation_id":1,"severity":"minor"}' \
  http://localhost/api/disciplinarycases
```

### Add Evidence
```bash
curl -X POST -b cookie.txt \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"/evidence/pic.jpg"}' \
  http://localhost/api/disciplinarycases/1/addEvidence
```

### Submit an Appeal
```bash
curl -X POST -b cookie.txt \
  -H 'Content-Type: application/json' \
  -d '{"reason":"Disagrees with decision"}' \
  http://localhost/api/appeals/submit/1
```

## Required Permissions

- **Employee** – `disciplinary_cases.getById`, `appeals.submit`, `appeals.getById`
- **HR Administrator** – full CRUD on `disciplinary_cases`, `case_evidence`, `interview_logs`, `disciplinary_actions`, `appeals`, `violation_types`

Update the `roles_permissions` table accordingly so only authorized roles may access these endpoints.

## Workflow Triggers

Workflows may react to disciplinary events using the `WorkflowEngine`. Typical trigger names include:

- `disciplinary.caseOpened` – fired after a new case is created.
- `disciplinary.caseUpdated` – when evidence or interviews are added.
- `disciplinary.caseClosed` – when status changes to closed.
- `disciplinary.appealSubmitted` – when an employee submits an appeal.

A workflow definition can listen for these events and send notifications, wait for approvals or update other records.