TenantAtlas/specs/256-external-support-desk-handoff/quickstart.md

Quickstart — External Support Desk / PSA Handoff

Prereqs

• Docker is running.
• Laravel Sail dependencies are installed.
• The support-request foundation from Spec 246 is already present in the workspace.
• One application-configured external support desk target is available through apps/platform/config/support_desk.php, or a fake target is available for implementation tests.

Run locally after implementation

• Start containers:
  • export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail up -d
• Run targeted unit proof:
  • export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/SupportRequests/ExternalSupportDeskHandoffServiceTest.php tests/Unit/Support/SupportRequests/SupportRequestLatestHandoffSummaryTest.php
• Run targeted feature proof:
  • export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/SupportRequests/TenantSupportRequestExternalHandoffTest.php tests/Feature/SupportRequests/OperationRunSupportRequestExternalHandoffTest.php tests/Feature/SupportRequests/SupportRequestExternalHandoffAuthorizationTest.php tests/Feature/SupportRequests/SupportRequestExternalHandoffAuditTest.php
• Format after implementation:
  • export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent

Manual smoke after implementation

1. Sign in to /admin as a workspace member with tenant entitlement and support_requests.create capability.
2. Open one tenant at /admin/t/{tenant} and trigger Request support.
3. Verify the action shows the existing context summary plus the new handoff mode controls. If no external target is configured in config/support_desk.php, verify the action clearly stays in internal_only mode.
4. Submit the tenant-context flow with create_external_ticket and verify the success notification includes the internal support reference plus the created external ticket reference.
5. Reopen the tenant-context action and verify the latest-handoff summary names the same internal support reference and external ticket reference.
6. Submit the tenant-context flow with link_existing_ticket and verify the stored summary shows the linked external reference without issuing a create call.
7. Force the external create path to fail, including the five-second timeout path, and verify the action returns explicit partial-success or warning feedback, the internal support request still exists, and the latest-handoff summary shows the persisted failure summary.
8. Open one canonical run detail page at /admin/operations/{run} for a run that resolves to the same entitled tenant scope and repeat create, link, and failure checks there.
9. Verify a non-member or non-entitled actor receives 404, while an in-scope member without support_requests.create sees the action disabled and receives 403 on execution.
10. Verify no new support-request resource, support queue, global-search result, or OperationRun side effect appears in this slice.

Notes

• Filament v5 remains on Livewire v4.0+ in this repo; the feature stays inside native Filament page actions.
• No provider registration change is part of this slice; Laravel 12 panel providers remain registered in bootstrap/providers.php.
• No globally searchable resource is added, so there is no new global-search contract to satisfy.
• No destructive action is introduced, so ->requiresConfirmation() is not newly involved here.
• No asset strategy changes are required. The general deploy step cd apps/platform && php artisan filament:assets remains unchanged.

Implementation Close-Out Expectations

• The targeted unit and feature commands above pass.
• Manual smoke proves create, link, and explicit failure handling from both existing support-aware surfaces.
• Audit review shows support_request.created, support_request.external_ticket_created, support_request.external_ticket_linked, and support_request.external_handoff_failed events with the expected bounded metadata.
• Internal-only support-request submission still works when the external target is unavailable or intentionally bypassed.
• No new support product surface appears beyond the two existing actions.