# 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 `