diff --git a/Modules/Analytics/README.md b/Modules/Analytics/README.md deleted file mode 100644 index c5398012..00000000 --- a/Modules/Analytics/README.md +++ /dev/null @@ -1,5 +0,0 @@ -# Analytics - -Display KPIs, warehouse performance trends, executive summaries, and OTTC analysis. - -Contains actual sample Blade views and placeholder service provider/routes only. diff --git a/Modules/Audit/README.md b/Modules/Audit/README.md deleted file mode 100644 index 03e107c4..00000000 --- a/Modules/Audit/README.md +++ /dev/null @@ -1,5 +0,0 @@ -# Audit - -Review activity logs, data changes, interface events, and administrative actions. - -Contains actual sample Blade views and placeholder service provider/routes only. diff --git a/Modules/CarrierManagement/README.md b/Modules/CarrierManagement/README.md deleted file mode 100644 index 70788878..00000000 --- a/Modules/CarrierManagement/README.md +++ /dev/null @@ -1,5 +0,0 @@ -# Carrier Management - -Maintain carriers, services, and shipment routing master data. - -Contains actual sample Blade views and placeholder service provider/routes only. diff --git a/Modules/ChatGPT/readme.md b/Modules/ChatGPT/readme.md deleted file mode 100644 index fd961169..00000000 --- a/Modules/ChatGPT/readme.md +++ /dev/null @@ -1,28 +0,0 @@ -# ChatGPT Module - -Provides encrypted OpenAI API key storage and an Artisan command for deleting all OpenAI API files visible to the active stored key. - -## Routes - -- `GET /chatgpt` - manage stored API keys. -- `POST /chatgpt/settings` - create a stored API key. -- `PUT /chatgpt/settings/{setting}` - update an API key setting. -- `DELETE /chatgpt/settings/{setting}` - delete an API key setting. - -## Commands - -Preview files without deleting: - -```bash -php artisan chatgpt:delete-api-files --dry-run -``` - -Delete all OpenAI API files without interactive confirmation: - -```bash -php artisan chatgpt:delete-api-files -``` - -## Security - -API keys are encrypted at rest using Laravel's encrypted Eloquent cast and the application `APP_KEY`. diff --git a/Modules/Configuration/README.md b/Modules/Configuration/README.md deleted file mode 100644 index a012d90e..00000000 --- a/Modules/Configuration/README.md +++ /dev/null @@ -1,5 +0,0 @@ -# Configuration - -Centralise system settings, warehouse defaults, interface flags, and feature switches. - -Contains actual sample Blade views and placeholder service provider/routes only. diff --git a/Modules/DocumentArchive/README.md b/Modules/DocumentArchive/README.md deleted file mode 100644 index 8a740892..00000000 --- a/Modules/DocumentArchive/README.md +++ /dev/null @@ -1,5 +0,0 @@ -# Document Archive - -Search cached Sentinel documents, shipment PDFs, labels, and BOL records. - -Contains actual sample Blade views and placeholder service provider/routes only. diff --git a/Modules/Helpdesk/README.md b/Modules/Helpdesk/README.md deleted file mode 100644 index 78cd8fd2..00000000 --- a/Modules/Helpdesk/README.md +++ /dev/null @@ -1,333 +0,0 @@ -# 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"`. - -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 `