303 lines
10 KiB
Markdown
303 lines
10 KiB
Markdown
# 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.
|
|
```
|
|
|
|
## Ticket Workflow Stabilisation Checklist
|
|
|
|
This module treats the following workflows as mandatory production Helpdesk behaviour. Future changes must preserve these flows and update tests when behaviour changes.
|
|
|
|
### Create ticket
|
|
|
|
1. Open **Helpdesk > Tickets > Create**.
|
|
2. Enter a subject and details.
|
|
3. Use the browser spell checker in the subject and details editor before submitting.
|
|
4. Attach supporting files where useful.
|
|
5. Click **Create Ticket** once.
|
|
|
|
Validation must run only after **Create Ticket** is clicked. Rich-text editor synchronisation must not trigger premature validation or require a second click.
|
|
|
|
### Public reply
|
|
|
|
1. Open a ticket.
|
|
2. Choose **Public reply**.
|
|
3. Enter the response.
|
|
4. Submit the response.
|
|
|
|
A public reply is visible in the conversation and counts toward the first-response SLA. The first public response should set the first response timestamp once and must not be overwritten by later replies.
|
|
|
|
### Internal note
|
|
|
|
1. Open a ticket.
|
|
2. Choose **Internal note**.
|
|
3. Enter staff-only information.
|
|
4. Submit the note.
|
|
|
|
Internal notes are not customer-visible and must not satisfy the public first-response SLA.
|
|
|
|
### Close ticket
|
|
|
|
1. Open the ticket controls.
|
|
2. Select a closed status.
|
|
3. Enter a mandatory closure comment when prompted.
|
|
4. Choose whether the closure comment is public or internal.
|
|
5. Confirm **Close ticket**.
|
|
|
|
The closure comment is required for auditability. The resolution SLA should be recorded after closure.
|
|
|
|
### Reopen ticket
|
|
|
|
1. Open a closed ticket.
|
|
2. Select an open or in-progress status.
|
|
3. Add a reopen reason where the UI requires one.
|
|
4. Continue with public replies, internal notes, timers and attachments.
|
|
|
|
The original closure history must remain intact.
|
|
|
|
### SLA
|
|
|
|
The SLA panel must show clear operational wording:
|
|
|
|
- Awaiting public reply.
|
|
- Due soon.
|
|
- SLA met.
|
|
- Responded late.
|
|
- Breached.
|
|
|
|
It should show who first responded, when they responded, and how long it took. SLA audit events should be retained for review.
|
|
|
|
### Timer
|
|
|
|
1. Start a timer only when work begins.
|
|
2. The live elapsed timer appears only while the timer is running.
|
|
3. End the timer when work stops.
|
|
4. Confirm the saved time in the ticket log.
|
|
|
|
Timer UI must not leave hidden or unused JavaScript files behind.
|
|
|
|
### Attachments
|
|
|
|
Attachments may be added to tickets and responses. Uploaded files must remain validated by type and size, stored safely, and associated with the correct ticket/comment.
|
|
|
|
### Ticket reference sequence
|
|
|
|
Ticket references must be generated from `helpdesk_ticket_sequences` when the migration has run. The sequence row is locked during ticket creation, and the initial value is calculated from all existing ticket references, including soft-deleted tickets. This avoids duplicate references such as reusing `HD-2026-00002`.
|
|
|
|
### Spell checking
|
|
|
|
Browser-native spell checking is enabled on ticket subjects, details, public replies, threaded replies, timer notes and closure comments using `spellcheck="true"` and `lang="en-GB"`.
|
|
|
|
### Regression coverage expected
|
|
|
|
The module should keep tests around:
|
|
|
|
- Create ticket submit-only validation.
|
|
- Body editor synchronisation.
|
|
- Public and internal replies.
|
|
- Mandatory closure comments.
|
|
- Reopen behaviour where implemented.
|
|
- SLA state and audit trail updates.
|
|
- Timer start/end logging.
|
|
- Attachment validation and association.
|
|
- Reference sequence collision prevention.
|
|
- Browser spellcheck attributes on writable fields.
|
|
|