From a6148f9bfd25fa9f9e6685a71dbb24c8023fbfef Mon Sep 17 00:00:00 2001
From: Mark Gregory <mark.gregory@mpba.co.uk>
Date: Tue, 23 Jun 2026 11:01:55 +0100
Subject: [PATCH] proper closer status

---
 .../Controllers/TicketControlsController.php  |  28 ++++-
 Modules/Helpdesk/Livewire/TicketShow.php      |  32 ++++-
 Modules/Helpdesk/README.md                    |  34 ++++++
 .../views/livewire/ticket-create.blade.php    | 109 +++++++++++-------
 .../views/partials/ticket-controls.blade.php  |  91 ++++++++++++++-
 .../Tests/Feature/TicketConversationTest.php  |  60 ++++++++++
 Modules/Helpdesk/changelog.yaml               |  23 ++++
 Modules/Helpdesk/module.json                  |   2 +-
 8 files changed, 329 insertions(+), 50 deletions(-)

diff --git a/Modules/Helpdesk/Http/Controllers/TicketControlsController.php b/Modules/Helpdesk/Http/Controllers/TicketControlsController.php
index b3c6e60f..607b4100 100644
--- a/Modules/Helpdesk/Http/Controllers/TicketControlsController.php
+++ b/Modules/Helpdesk/Http/Controllers/TicketControlsController.php
@@ -16,6 +16,7 @@ use Illuminate\Validation\Rule;
 use Modules\Helpdesk\Models\Status;
 use Modules\Helpdesk\Models\Ticket;
 use Modules\Helpdesk\Services\SlaService;
+use Modules\Helpdesk\Services\TicketService;
 use Modules\Helpdesk\Services\WorkflowNotificationService;
 
 final class TicketControlsController extends Controller
@@ -64,7 +65,7 @@ final class TicketControlsController extends Controller
     /**
      * Persist the selected ticket status from the ticket detail controls.
      */
-    public function updateStatus(Request $request, Ticket $ticket, WorkflowNotificationService $workflow, SlaService $sla): RedirectResponse
+    public function updateStatus(Request $request, Ticket $ticket, WorkflowNotificationService $workflow, SlaService $sla, TicketService $tickets): RedirectResponse
     {
         $this->hydrateUserRelations($ticket);
 
@@ -72,10 +73,21 @@ final class TicketControlsController extends Controller
 
         $validated = $request->validate([
             'status_id' => ['required', 'integer', Rule::exists('helpdesk_statuses', 'id')],
+            'closure_comment' => ['nullable', 'string', 'min:10', 'max:5000'],
+            'closure_internal' => ['nullable', 'boolean'],
         ]);
 
         $status = Status::query()->findOrFail((int) $validated['status_id']);
 
+        if ($status->is_closed) {
+            validator($validated, [
+                'closure_comment' => ['required', 'string', 'min:10', 'max:5000'],
+            ], [
+                'closure_comment.required' => 'A closure comment is required before closing the ticket.',
+                'closure_comment.min' => 'The closure comment must explain why the ticket is being closed.',
+            ])->validate();
+        }
+
         $this->updateTicket($ticket, [
             'status_id' => $status->id,
             'completed_at' => $status->is_closed ? now() : null,
@@ -85,12 +97,24 @@ final class TicketControlsController extends Controller
         $this->ensureBoardContainsStatus($ticket, (int) $status->id);
 
         $fresh = $this->freshTicketForAction($ticket);
+        $actor = $this->actor();
 
         if ($status->is_closed) {
+            $tickets->comment(
+                $fresh,
+                $actor,
+                trim((string) $validated['closure_comment']),
+                (bool) ($validated['closure_internal'] ?? false),
+                [],
+                null,
+                'Closure comment'
+            );
+
+            $fresh = $this->freshTicketForAction($ticket);
             $sla->recordClosure($fresh);
         }
 
-        $workflow->dispatch($fresh, $status->is_closed ? 'ticket.closed' : 'ticket.updated', $this->actor());
+        $workflow->dispatch($fresh, $status->is_closed ? 'ticket.closed' : 'ticket.updated', $actor);
 
         return redirect()
             ->route('helpdesk.tickets.show', $fresh)
diff --git a/Modules/Helpdesk/Livewire/TicketShow.php b/Modules/Helpdesk/Livewire/TicketShow.php
index ea731326..abed51e6 100644
--- a/Modules/Helpdesk/Livewire/TicketShow.php
+++ b/Modules/Helpdesk/Livewire/TicketShow.php
@@ -54,6 +54,10 @@ final class TicketShow extends Component
 
     public ?int $agent_id = null;
 
+    public string $closureComment = '';
+
+    public bool $closureInternal = false;
+
     public ?int $reply_parent_id = null;
 
     public string $replyBody = '';
@@ -144,7 +148,7 @@ final class TicketShow extends Component
         $this->ticket = $this->freshTicket($this->ticket);
     }
 
-    public function updateStatus(WorkflowNotificationService $workflow, SlaService $sla): void
+    public function updateStatus(WorkflowNotificationService $workflow, SlaService $sla, TicketService $tickets): void
     {
         $this->authorize('update', $this->ticket);
 
@@ -157,6 +161,17 @@ final class TicketShow extends Component
 
         $status = Status::query()->findOrFail($statusId);
 
+        if ($status->is_closed) {
+            validator([
+                'closureComment' => $this->closureComment,
+            ], [
+                'closureComment' => ['required', 'string', 'min:10', 'max:5000'],
+            ], [
+                'closureComment.required' => 'A closure comment is required before closing the ticket.',
+                'closureComment.min' => 'The closure comment must explain why the ticket is being closed.',
+            ])->validate();
+        }
+
         $updates = [
             'status_id' => $status->id,
             'completed_at' => $status->is_closed ? now() : null,
@@ -175,6 +190,21 @@ final class TicketShow extends Component
         $this->status_id = (int) $this->ticket->status_id;
 
         if ($status->is_closed) {
+            $user = Auth::user();
+            abort_if($user === null, 403);
+
+            $tickets->comment(
+                $this->ticket,
+                $user,
+                trim($this->closureComment),
+                $this->closureInternal,
+                [],
+                null,
+                'Closure comment'
+            );
+
+            $this->reset(['closureComment', 'closureInternal']);
+            $this->ticket = $this->freshTicket($this->ticket);
             $sla->recordClosure($this->ticket);
         }
 
diff --git a/Modules/Helpdesk/README.md b/Modules/Helpdesk/README.md
index 6eea33ec..0a5f5350 100644
--- a/Modules/Helpdesk/README.md
+++ b/Modules/Helpdesk/README.md
@@ -167,3 +167,37 @@ Helpdesk changes must preserve the established WMS/Laravel module baseline:
 - `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.
+```
+
diff --git a/Modules/Helpdesk/Resources/views/livewire/ticket-create.blade.php b/Modules/Helpdesk/Resources/views/livewire/ticket-create.blade.php
index 248b3b30..a0df77d5 100644
--- a/Modules/Helpdesk/Resources/views/livewire/ticket-create.blade.php
+++ b/Modules/Helpdesk/Resources/views/livewire/ticket-create.blade.php
@@ -274,7 +274,7 @@
                             data-dusk="ticket-body-editor" dusk="ticket-body-editor">{!! $body ?? '' !!}</div>
                     </div>
 
-                    <textarea id="body" wire:model.defer="body" class="sr-only" tabindex="-1" aria-hidden="true"></textarea>
+                    <textarea id="body" wire:model.live="body" class="sr-only" tabindex="-1" aria-hidden="true"></textarea>
 
                     @error('body')
                         <p class="mt-2 text-sm text-red-500">{{ $message }}</p>
@@ -361,57 +361,78 @@
         }
     </style>
     <script>
-        document.addEventListener('DOMContentLoaded', function() {
-            const form = document.querySelector('.helpdesk-ticket-form');
-            const editor = document.querySelector('[data-helpdesk-details-editor]');
-            const bodyField = document.getElementById('body');
+        (() => {
+            const initialisedEditors = window.helpdeskTicketCreateEditors ??= new WeakSet();
 
-            if (!form || !editor || !bodyField) {
-                return;
-            }
+            const syncEditorToLivewire = (form, editor, bodyField) => {
+                const value = editor.innerHTML.trim();
 
-            const syncBody = function() {
-                bodyField.value = editor.innerHTML.trim();
-                bodyField.dispatchEvent(new Event('input', {
-                    bubbles: true
-                }));
-                bodyField.dispatchEvent(new Event('change', {
-                    bubbles: true
-                }));
+                bodyField.value = value;
+                bodyField.dispatchEvent(new Event('input', { bubbles: true }));
+                bodyField.dispatchEvent(new Event('change', { bubbles: true }));
+
+                const livewireRoot = form.closest('[wire\:id]');
+                const livewireId = livewireRoot?.getAttribute('wire:id');
+
+                if (livewireId && window.Livewire?.find(livewireId)) {
+                    window.Livewire.find(livewireId).set('body', value, false);
+                }
             };
 
-            document.querySelectorAll('[data-helpdesk-editor-command]').forEach(function(button) {
-                button.addEventListener('click', function() {
-                    editor.focus();
-                    document.execCommand(button.dataset.helpdeskEditorCommand, false, null);
-                    syncBody();
-                });
-            });
+            const initialiseTicketCreateEditor = () => {
+                document.querySelectorAll('.helpdesk-ticket-form').forEach((form) => {
+                    const editor = form.querySelector('[data-helpdesk-details-editor]');
+                    const bodyField = form.querySelector('#body');
 
-            document.querySelectorAll('[data-helpdesk-editor-format]').forEach(function(button) {
-                button.addEventListener('click', function() {
-                    editor.focus();
-                    document.execCommand('formatBlock', false, button.dataset.helpdeskEditorFormat);
-                    syncBody();
-                });
-            });
-
-            document.querySelectorAll('[data-helpdesk-editor-link]').forEach(function(button) {
-                button.addEventListener('click', function() {
-                    const url = window.prompt('Enter link URL');
-
-                    if (!url) {
+                    if (!editor || !bodyField || initialisedEditors.has(editor)) {
                         return;
                     }
 
-                    editor.focus();
-                    document.execCommand('createLink', false, url);
-                    syncBody();
-                });
-            });
+                    initialisedEditors.add(editor);
 
-            editor.addEventListener('blur', syncBody);
-            form.addEventListener('submit', syncBody);
-        });
+                    const syncBody = () => syncEditorToLivewire(form, editor, bodyField);
+
+                    form.querySelectorAll('[data-helpdesk-editor-command]').forEach((button) => {
+                        button.addEventListener('click', () => {
+                            editor.focus();
+                            document.execCommand(button.dataset.helpdeskEditorCommand, false, null);
+                            syncBody();
+                        });
+                    });
+
+                    form.querySelectorAll('[data-helpdesk-editor-format]').forEach((button) => {
+                        button.addEventListener('click', () => {
+                            editor.focus();
+                            document.execCommand('formatBlock', false, button.dataset.helpdeskEditorFormat);
+                            syncBody();
+                        });
+                    });
+
+                    form.querySelectorAll('[data-helpdesk-editor-link]').forEach((button) => {
+                        button.addEventListener('click', () => {
+                            const url = window.prompt('Enter link URL');
+
+                            if (!url) {
+                                return;
+                            }
+
+                            editor.focus();
+                            document.execCommand('createLink', false, url);
+                            syncBody();
+                        });
+                    });
+
+                    editor.addEventListener('input', syncBody);
+                    editor.addEventListener('keyup', syncBody);
+                    editor.addEventListener('paste', () => window.setTimeout(syncBody, 0));
+                    editor.addEventListener('blur', syncBody);
+                    form.addEventListener('submit', syncBody, { capture: true });
+                });
+            };
+
+            document.addEventListener('DOMContentLoaded', initialiseTicketCreateEditor);
+            document.addEventListener('livewire:navigated', initialiseTicketCreateEditor);
+            initialiseTicketCreateEditor();
+        })();
     </script>
 </div>
diff --git a/Modules/Helpdesk/Resources/views/partials/ticket-controls.blade.php b/Modules/Helpdesk/Resources/views/partials/ticket-controls.blade.php
index b157108f..27cebcdc 100644
--- a/Modules/Helpdesk/Resources/views/partials/ticket-controls.blade.php
+++ b/Modules/Helpdesk/Resources/views/partials/ticket-controls.blade.php
@@ -101,7 +101,8 @@
         </form>
 
         <form method="POST" action="{{ route('helpdesk.tickets.status.update', $ticket) }}"
-              class="mb-4 space-y-2">
+              class="mb-4 space-y-2"
+              data-helpdesk-status-form>
             @csrf
 
             <label class="block text-xs font-bold text-zinc-700 dark:text-zinc-200"
@@ -111,7 +112,9 @@
                     data-dusk="ticket-show-status">
                 @foreach ($statuses as $status)
                     <option
-                        value="{{ $status->id }}" @selected((int) $status_id === (int) $status->id)>{{ $status->name }}
+                        value="{{ $status->id }}"
+                        data-is-closed="{{ $status->is_closed ? '1' : '0' }}"
+                        @selected((int) $status_id === (int) $status->id)>{{ $status->name }}
                     </option>
                 @endforeach
             </select>
@@ -120,6 +123,58 @@
             <p class="text-xs font-bold text-red-600 dark:text-red-400">{{ $message }}</p>
             @enderror
 
+            @error('closure_comment')
+            <p class="text-xs font-bold text-red-600 dark:text-red-400">{{ $message }}</p>
+            @enderror
+
+            <dialog data-helpdesk-close-ticket-dialog
+                    class="w-full max-w-lg rounded-2xl border border-zinc-200 bg-white p-0 shadow-2xl backdrop:bg-slate-950/70 dark:border-zinc-700 dark:bg-zinc-900">
+                <div class="bg-gradient-to-r from-red-800 via-red-700 to-slate-900 px-5 py-4 text-white">
+                    <div class="flex items-center gap-3">
+                        <span class="inline-flex h-10 w-10 shrink-0 items-center justify-center rounded-xl bg-white/15 text-white ring-1 ring-white/20">
+                            <i class="fa-solid fa-lock" aria-hidden="true"></i>
+                        </span>
+                        <div class="min-w-0">
+                            <h3 class="text-base font-black tracking-tight">Close ticket</h3>
+                            <p class="text-xs font-semibold text-red-100">A closure comment is required for the audit trail.</p>
+                        </div>
+                    </div>
+                </div>
+
+                <div class="space-y-4 p-5">
+                    <label class="block text-xs font-bold text-zinc-700 dark:text-zinc-200" for="closure_comment">
+                        Closure comment <span class="text-red-600">*</span>
+                    </label>
+
+                    <textarea id="closure_comment" name="closure_comment" rows="5" minlength="10" maxlength="5000"
+                              placeholder="Explain what was completed, verified, or agreed before closing this ticket."
+                              class="block w-full rounded-xl border border-zinc-300 bg-white p-3 text-sm font-semibold text-zinc-900 shadow-sm focus:border-red-500 focus:ring-red-500 dark:border-zinc-700 dark:bg-zinc-950 dark:text-zinc-100"
+                              data-helpdesk-closure-comment>{{ old('closure_comment') }}</textarea>
+
+                    <label class="flex items-start gap-3 rounded-xl border border-emerald-200 bg-emerald-50 p-3 text-sm text-emerald-950 dark:border-emerald-900 dark:bg-emerald-950 dark:text-emerald-100">
+                        <input type="hidden" name="closure_internal" value="0">
+                        <input type="checkbox" name="closure_internal" value="1"
+                               class="mt-1 rounded border-emerald-400 text-purple-600 focus:ring-purple-500">
+                        <span>
+                            <span class="block font-extrabold">Internal closure note</span>
+                            <span class="mt-1 block text-xs font-semibold opacity-80">Leave unticked to save the closure as a public customer-visible response.</span>
+                        </span>
+                    </label>
+
+                    <div class="flex flex-col-reverse gap-2 sm:flex-row sm:justify-end">
+                        <button type="button" data-helpdesk-close-dialog-cancel
+                                class="inline-flex items-center justify-center rounded-lg border border-zinc-300 bg-white px-4 py-2 text-xs font-black text-zinc-700 shadow-sm hover:bg-zinc-50 dark:border-zinc-700 dark:bg-zinc-950 dark:text-zinc-100 dark:hover:bg-zinc-800">
+                            Cancel
+                        </button>
+                        <button type="submit" data-helpdesk-confirm-close
+                                class="inline-flex items-center justify-center rounded-lg bg-red-600 px-4 py-2 text-xs font-black text-white shadow-sm hover:bg-red-700 focus:outline-none focus:ring-2 focus:ring-red-400/70">
+                            <i class="fa-solid fa-lock mr-2" aria-hidden="true"></i>
+                            Close ticket
+                        </button>
+                    </div>
+                </div>
+            </dialog>
+
             <button type="submit" dusk="update-status"
                     class="inline-flex items-center justify-center rounded-lg bg-blue-600 px-3 py-2 text-xs font-black text-white shadow-sm transition hover:bg-blue-700 focus:outline-none focus:ring-2 focus:ring-blue-400/70">
                 <i class="fa-solid fa-circle-check mr-2" aria-hidden="true"></i>
@@ -154,4 +209,36 @@
             </button>
         </form>
     </details>
+
+    <script>
+        document.addEventListener('DOMContentLoaded', function () {
+            document.querySelectorAll('[data-helpdesk-status-form]').forEach(function (form) {
+                const statusSelect = form.querySelector('[data-dusk="ticket-show-status"]');
+                const dialog = form.querySelector('[data-helpdesk-close-ticket-dialog]');
+                const comment = form.querySelector('[data-helpdesk-closure-comment]');
+                const cancel = form.querySelector('[data-helpdesk-close-dialog-cancel]');
+
+                if (!statusSelect || !dialog || !comment) {
+                    return;
+                }
+
+                form.addEventListener('submit', function (event) {
+                    const selectedOption = statusSelect.options[statusSelect.selectedIndex];
+                    const isClosing = selectedOption?.dataset?.isClosed === '1';
+
+                    if (!isClosing || comment.value.trim().length >= 10) {
+                        return;
+                    }
+
+                    event.preventDefault();
+                    dialog.showModal();
+                    comment.focus();
+                });
+
+                cancel?.addEventListener('click', function () {
+                    dialog.close();
+                });
+            });
+        });
+    </script>
 @endcan
diff --git a/Modules/Helpdesk/Tests/Feature/TicketConversationTest.php b/Modules/Helpdesk/Tests/Feature/TicketConversationTest.php
index 03cd5ce3..9205002c 100644
--- a/Modules/Helpdesk/Tests/Feature/TicketConversationTest.php
+++ b/Modules/Helpdesk/Tests/Feature/TicketConversationTest.php
@@ -222,6 +222,66 @@ final class TicketConversationTest extends TestCase
         self::assertSame($fixtures['high']->id, $ticket->priority_id);
     }
 
+    public function test_closing_ticket_requires_a_closure_comment(): void
+    {
+        $fixtures = $this->seedLookupData();
+        $owner = $this->user();
+        $agent = $this->agent();
+        $ticket = $this->ticket([
+            'owner' => $owner,
+            'agent' => $agent,
+            'status_id' => $fixtures['open']->id,
+            'priority_id' => $fixtures['normal']->id,
+        ]);
+
+        $this->actingAs($agent)
+            ->from(route('helpdesk.tickets.show', $ticket))
+            ->post(route('helpdesk.tickets.status.update', $ticket), [
+                'status_id' => $fixtures['closed']->id,
+            ])
+            ->assertRedirect(route('helpdesk.tickets.show', $ticket))
+            ->assertSessionHasErrors('closure_comment');
+
+        $ticket->refresh();
+
+        self::assertSame($fixtures['open']->id, $ticket->status_id);
+        self::assertNull($ticket->completed_at);
+    }
+
+    public function test_closing_ticket_creates_a_closure_comment(): void
+    {
+        $fixtures = $this->seedLookupData();
+        $owner = $this->user();
+        $agent = $this->agent();
+        $ticket = $this->ticket([
+            'owner' => $owner,
+            'agent' => $agent,
+            'status_id' => $fixtures['open']->id,
+            'priority_id' => $fixtures['normal']->id,
+        ]);
+
+        $this->actingAs($agent)
+            ->post(route('helpdesk.tickets.status.update', $ticket), [
+                'status_id' => $fixtures['closed']->id,
+                'closure_comment' => 'Issue resolved and verified before closure.',
+                'closure_internal' => '0',
+            ])
+            ->assertRedirect(route('helpdesk.tickets.show', $ticket));
+
+        $ticket->refresh();
+
+        self::assertSame($fixtures['closed']->id, $ticket->status_id);
+        self::assertNotNull($ticket->completed_at);
+
+        $this->assertDatabaseHas('helpdesk_comments', [
+            'ticket_id' => $ticket->id,
+            'user_id' => $agent->id,
+            'subject' => 'Closure comment',
+            'body' => 'Issue resolved and verified before closure.',
+            'is_internal' => false,
+        ]);
+    }
+
     public function test_unassigned_agent_cannot_update_another_users_ticket(): void
     {
         $fixtures = $this->seedLookupData();
diff --git a/Modules/Helpdesk/changelog.yaml b/Modules/Helpdesk/changelog.yaml
index be19972f..439d560b 100644
--- a/Modules/Helpdesk/changelog.yaml
+++ b/Modules/Helpdesk/changelog.yaml
@@ -82,3 +82,26 @@
     - Documented Public Reply versus Internal Note usage for responses and SLA handling.
     - Documented recommended close-ticket UI behaviour, closure templates, SLA meanings, audit expectations, reopening guidance, and Helpdesk development standards.
     - Preserved append-only changelog history.
+
+- version: 1.9.38
+  date: 2026-06-23
+  type: bugfix
+  summary: Enforce mandatory closure comments when closing Helpdesk tickets.
+  changes:
+    - Added a close-ticket confirmation dialog that opens when a closed status is selected without a closure comment.
+    - Added server-side validation so closed statuses cannot be saved without a meaningful closure comment.
+    - Stored the closure comment as a Helpdesk response with Public Reply as the default visibility and Internal Note as an explicit option.
+    - Updated the status control UI with closed-status metadata and accessible modal controls.
+    - Added regression tests for blocked closure without a comment and successful closure with an auditable comment.
+    - Preserved append-only changelog history.
+
+- version: 1.9.39
+  date: 2026-06-23
+  type: bugfix
+  summary: Fix Helpdesk ticket create editor body synchronisation.
+  changes:
+    - Updated the ticket creation rich-text Details editor so content is pushed into the Livewire body property before validation.
+    - Added Livewire navigation-safe editor initialisation so the sync logic works after wire:navigate page changes.
+    - Added input, keyup, paste, blur, and submit-capture synchronisation to prevent false "body field is required" validation failures.
+    - Changed the hidden body field to live Livewire binding so the server receives the latest editor content without requiring a page reload.
+    - Preserved append-only changelog history.
diff --git a/Modules/Helpdesk/module.json b/Modules/Helpdesk/module.json
index c83390ce..86234d07 100644
--- a/Modules/Helpdesk/module.json
+++ b/Modules/Helpdesk/module.json
@@ -22,5 +22,5 @@
         "Modules\\Helpdesk\\Providers\\HelpdeskServiceProvider"
     ],
     "files": [],
-    "version": "1.9.37"
+    "version": "1.9.39"
 }