334 lines
12 KiB
Markdown
Executable File
334 lines
12 KiB
Markdown
Executable File
# 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 Thredary/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"`.
|
||
|
||
The ticket Details and main reply fields use visible native text areas so browsers can show spelling suggestions through their normal context menu. When a word is underlined, right-click or Ctrl-click it to choose a suggested correction. Browser spell checking does not usually open a separate application popup, and the exact suggestion menu is controlled by the user’s browser and operating system dictionary settings.
|
||
|
||
### 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.
|
||
|
||
|
||
## Rich Editor, Spellcheck, Clear and Close Workflow
|
||
|
||
The ticket create and reply forms use rich HTML editing controls. Do not replace the rich editor with a plain `<textarea>` to enable spelling suggestions. Spellcheck must be enabled on the actual `contenteditable` editor surface using `spellcheck="true"`, `lang="en-GB"`, `autocorrect="on"` and `autocomplete="on"`.
|
||
|
||
Browser spell suggestions appear inline as red underlines and are selected from the browser context menu by right-clicking or Ctrl-clicking the misspelled word.
|
||
|
||
The create-ticket **Clear** action must only clear transient user-entered content:
|
||
|
||
- subject
|
||
- details/body
|
||
- tags
|
||
- attachments
|
||
|
||
It must preserve configured routing defaults such as account, board, priority, category, project, team and due-date defaults.
|
||
|
||
When a user selects a closed ticket status, the professional closure modal must open on the first interaction. A closure comment remains mandatory, and the user can choose whether the closure comment is public or internal.
|
||
|
||
## Spellcheck and Rich Editor
|
||
|
||
The Helpdesk rich editor keeps its HTML controls for formatting, lists, links, quotes and pasted content. Browser-native spellcheck is enabled on the editable area, but the module deliberately does not ship a fake inline spellchecker because replacing the editor with a textarea removes the toolbar and breaks the workflow.
|
||
|
||
If a full inline spelling engine is required later, add it as a deliberate editor plugin integration with regression tests for formatting, Livewire body sync, ticket create, reply, clear, close modal, and attachment handling. Do not replace the rich editor with a plain textarea.
|
||
|
||
## Timer Log Refresh
|
||
|
||
The ticket timer dispatches `helpdesk-ticket-time-log-updated` after start and stop. The ticket detail Livewire component listens for that event and refreshes ticket aggregates so the time summary and log modal update without a page reload.
|
||
|
||
Working Github setup with gitea
|