# Helpdesk Module

Professional Livewire-first Helpdesk module for ticket management, public/internal responses, SLA tracking, time logging, audit history, and operational support workflows.

## Closing a Ticket

A ticket should only be closed when the issue has been resolved, verified, duplicated elsewhere, cancelled, or no further action is required.

The recommended closure workflow is:

1. Open the ticket detail page.
2. Review the latest public and internal responses.
3. Confirm the ticket can be closed.
4. Add a closure comment explaining why the ticket is being closed.
5. Set the ticket status to `Closed`.
6. Save the change.
7. Confirm the closure appears in the conversation or audit trail.

## Closure Comment Requirement

Every closed ticket must have a closure comment. The comment should explain the reason for closure clearly enough that another agent, manager, auditor, or customer can understand the decision later.

A good closure comment should include:

- What was resolved or confirmed.
- Any action that was taken.
- Whether the customer/user needs to do anything else.
- Whether the ticket can be reopened if the issue returns.

Example closure comment:

```text
Issue resolved and verified.

The requested work has been completed and no further action is currently required. This ticket is now being closed.

If the issue reoccurs or additional information becomes available, please reopen the ticket or create a new support request referencing this ticket number.
```

## Public Reply vs Internal Note

When adding a response, choose the correct visibility.

### Public Reply

Use **Public Reply** when the customer or requester should see the message.

Public replies are used for:

- First-response SLA tracking.
- Customer-visible updates.
- Resolution explanations.
- Closure comments that the requester should see.

### Internal Note

Use **Internal Note** when the message is only for agents, managers, or support staff.

Internal notes are used for:

- Investigation notes.
- Technical diagnostics.
- Private handover comments.
- Internal escalation context.

Internal notes should not count as a customer response or first-response SLA event.

## Recommended Close Ticket UI Behaviour

The preferred Helpdesk behaviour is:

1. Agent clicks **Close Ticket**.
2. A close panel or modal opens.
3. The agent must enter a closure comment.
4. The agent chooses **Public Reply** or **Internal Note**.
5. The system validates the comment.
6. The system saves the response.
7. The ticket status changes to `Closed`.
8. The activity/audit trail records the status change and closure reason.

Validation should require a meaningful closure comment:

```php
'closure_comment' => ['required', 'string', 'min:10'],
```

## Closure Templates

Closure templates can make support work faster and more consistent. Suggested templates:

- Resolved and verified
- User confirmed fixed
- Duplicate ticket
- Unable to reproduce
- Configuration change completed
- Training or user guidance provided
- Cancelled by requester
- No further action required

Agents may select a template and edit the final message before closing the ticket.

## SLA Meaning

### First Response SLA

The first-response SLA is satisfied when the first qualifying public agent response is posted.

Typical states:

| State | Meaning |
| --- | --- |
| Awaiting public reply | No qualifying public agent response has been posted yet. |
| Due soon | The first-response target is close to its deadline. |
| SLA met | The first public response was posted on time. |
| Responded late | The first public response was posted after the SLA deadline. |
| Breached | The SLA deadline passed without a qualifying public response. |

### Resolution SLA

The resolution SLA is satisfied when the ticket is resolved or closed within the agreed target time.

Typical states:

| State | Meaning |
| --- | --- |
| Awaiting resolution | The ticket has not yet been resolved or closed. |
| Due soon | The resolution target is close to its deadline. |
| SLA met | The ticket was resolved or closed on time. |
| Breached | The resolution deadline was missed. |

## Audit and Compliance Expectations

Ticket closure should be auditable. The system should preserve:

- Previous status.
- New status.
- User who closed the ticket.
- Closure timestamp.
- Closure comment.
- Visibility of the closure comment.
- SLA state at the time of closure.

Do not delete historical responses or SLA records when a ticket is closed.

## Reopening a Ticket

If a closed ticket needs further work:

1. Open the closed ticket.
2. Click **Reopen** or change the status back to `Open` / `In Progress`.
3. Add a reopen reason.
4. Save the change.
5. Continue the conversation using public replies or internal notes as appropriate.

The reopen reason should be stored in the ticket activity/audit trail.

## Development Standards

Helpdesk changes must preserve the established WMS/Laravel module baseline:

- Livewire-first workflows.
- Module files remain under the existing `Modules/Helpdesk` structure.
- Livewire components remain under `Modules/Helpdesk/Livewire`.
- No unused JavaScript files.
- No duplicate Blade paths such as `Resources/views/views`.
- No `.DS_Store`, `__MACOSX`, or generated rubbish files in deliverables.
- `changelog.yaml` must be append-only.
- `module.json` version must match the latest `changelog.yaml` version.
- Tests must be added or updated for workflow changes.

## Closing a Ticket With a Mandatory Comment

The ticket status control now enforces an auditable closure workflow.

### How to close a ticket

1. Open the Helpdesk ticket.
2. Open **Ticket controls**.
3. Change **Status** to a closed status, for example **Closed**.
4. Click **Update status**.
5. The **Close ticket** dialog opens if no closure comment has been entered.
6. Enter a clear closure comment explaining what was resolved or why the ticket is being closed.
7. Leave **Internal closure note** unticked when the customer/requester should see the closure response.
8. Tick **Internal closure note** only when the closure reason is staff-only.
9. Click **Close ticket**.

### Closure comment rules

- A closed status cannot be saved without a closure comment.
- The closure comment must be at least 10 characters.
- Public closure comments are saved as normal Helpdesk responses.
- Internal closure comments are saved as internal notes and are only visible to users allowed to see internal notes.
- The ticket `completed_at` timestamp is set when a closed status is saved successfully.
- The resolution SLA is recorded after the closure is saved.

### Recommended closure wording

```text
Issue resolved and verified.

The requested work has been completed and no further action is currently required. This ticket is now closed.
```