# Help Desk / Support Ticketing Module

Enterprise support desk integrated into CHM ERP. Follows the same patterns as Planning & Budgeting: thin controllers, service layer, Spatie permissions, activity log, and CHM UI components.

## Access

- **Menu:** Support → Help Desk (requires `helpdesk.menu` or related ticket permissions)
- **Base URL:** `/admin/helpdesk/dashboard`
- **Middleware:** `EnsureHelpDeskAccess` — module gate on all helpdesk routes

## Permissions

All permissions use group **Help Desk**. Seed with:

```bash
php artisan db:seed --class=HelpDeskModuleSeeder
```

| Permission | Purpose |
|---|---|
| `helpdesk.menu` | Show sidebar menu |
| `ticket.view` | Base view access |
| `ticket.view_all` | See all tickets |
| `ticket.view_department` | See department tickets |
| `ticket.view_own` | See own tickets only |
| `ticket.create` | Create tickets |
| `ticket.assign` / `ticket.reassign` | Assignment |
| `ticket.reply` / `ticket.comment` | Replies and internal notes |
| `ticket.close` / `ticket.reopen` | Lifecycle |
| `ticket.escalate` | Manual escalation |
| `ticket.dashboard` | Dashboard KPIs |
| `ticket.reports` / `ticket.export` | Reports & Excel export |
| `ticket.categories` / `ticket.sla` | Settings |

Super Admin bypasses all checks via `AuthServiceProvider` Gate hook.

## Architecture

```
routes/helpdesk.php
app/Http/Controllers/HelpDesk/*
app/Services/HelpDesk/*
app/Models/HelpDesk/*
app/Policies/TicketPolicy.php
app/Support/HelpDeskPermissions.php
app/Jobs/HelpDesk/ProcessHelpDeskEscalationsJob.php
```

### Workflow

1. Requester creates ticket → auto `HD-{YEAR}-{#####}` number
2. SLA policy applied from priority
3. Optional auto-assignment by category/department
4. Technicians reply (public / internal / private)
5. Resolve → close (with optional rating/feedback)
6. Automatic escalation job runs every 15 minutes for overdue / SLA breaches

### SLA defaults (seeded)

| Priority | Response | Resolution |
|---|---|---|
| Critical / Emergency | 15 min | 2 hours |
| High | 1 hour | 8 hours |
| Medium | 4 hours | 24 hours |
| Low | 24 hours | 3 days |

### Escalation levels (seeded)

1. Support Officer → Supervisor  
2. Department Head → Programs  
3. IT Manager → Admin  
4. Executive Director → Director  

## Database

Migration: `2026_08_05_100000_create_helpdesk_tables.php`

Tables: `helpdesk_categories`, `helpdesk_sla_policies`, `helpdesk_escalation_rules`, `helpdesk_tags`, `helpdesk_tickets`, `helpdesk_ticket_tag`, `helpdesk_ticket_comments`, `helpdesk_ticket_attachments`, `helpdesk_ticket_escalations`, `helpdesk_ticket_relations`

## Notifications

Uses existing Laravel notification channels (`mail`, `database`) with bell-icon in-app alerts:

- Created, assigned, replied, escalated, resolved, closed, reopened, overdue

## Configuration

`config/helpdesk.php`:

- `max_upload_kb` — default 10240 (10 MB), override via `HELPDESK_MAX_UPLOAD_KB`
- `allowed_mimes` — attachment whitelist

## Scheduled jobs

`ProcessHelpDeskEscalationsJob` is scheduled every 15 minutes in `app/Console/Kernel.php`. Requires cron:

```bash
* * * * * php /path/to/artisan schedule:run
```

## UI pages

| Route name | View |
|---|---|
| `helpdesk.dashboard` | Dashboard KPIs & trends |
| `helpdesk.tickets.*` | CRUD + assign/resolve/close/reopen/escalate |
| `helpdesk.reports.index` | Filterable report listing |
| `helpdesk.reports.export` | Excel export |
| `helpdesk.settings.categories` | Category management |
| `helpdesk.settings.sla` | SLA policy editor |

## Setup checklist

```bash
php artisan migrate
php artisan db:seed --class=HelpDeskModuleSeeder
php artisan permission:cache-reset   # if using permission cache
```

Assign Help Desk permissions to roles via **Roles & Permissions** admin UI, or extend `HelpDeskModuleSeeder::$rolePermissions`.

## Testing flow

1. Log in as user with `ticket.create`
2. Create ticket at `/admin/helpdesk/tickets/create`
3. Assign as user with `ticket.assign`
4. Post internal note and public reply
5. Resolve → close with rating
6. Verify dashboard counts and notification bell entries