Diagnose before changing data

Troubleshooting and Recovery

Start with the exact message, affected user, hotel, page, time, and action. Avoid deleting records, changing production permissions broadly, or editing the database to hide a workflow problem.

The First Five Checks

1. Read the full on-screen message and validation errors.
2. Confirm the signed-in account, active hotel, role, permission, and assignment.
3. Confirm the record state: dates, room status, reservation status, payment state, or task status.
4. Check the relevant application, queue, mail, payment, webhook, or scheduler logs.
5. Reproduce once after correcting the cause. Do not submit financial or booking actions repeatedly.

Installer and First-run Problems

Login and Permission Problems

Booking and Room Problems

• Room unavailable: inspect overlapping reservations, maintenance holds, occupied state, room capacity, restrictions, and hotel scope.
• Check-in blocked: resolve room readiness, deposit/payment, blacklist, identity, or arrival handover requirement.
• Checkout blocked: resolve folio balance or departure handover. An open dispute should release departure without posting the disputed charge.
• Room will not return to sale: check reservation control, maintenance block, housekeeping state, inspection, and explicit room hold.

Payment and Webhook Problems

1. Find the internal payment/payment-link record and provider reference.
2. Check provider mode, currency, credentials, configured webhook URL, signature verification, and delivery logs.
3. Check whether the same idempotency key/event was already processed.
4. Retry only through the supported retry/recovery action. Do not fabricate a paid status.
5. For refunds, verify the original payment and provider response before changing the folio.

Email, SMS, and WhatsApp

Scheduler and Queue

php artisan schedule:list
php artisan schedule:run
php artisan queue:work --tries=3
php artisan queue:failed

Run commands with the production PHP binary and application user. Use a process supervisor for queue workers. A browser request is not a replacement for the scheduler. Review failed jobs before retrying so a persistent provider or data error does not loop.

Stale Page or Asset

php artisan optimize:clear
php artisan view:cache
npm ci
npm run build

Use these only in a controlled deployment. Confirm the web server serves the current public/build/manifest.json and that old CDN/browser caches are invalidated. Never solve a stale UI by exposing development files or bypassing the public document root.

Documentation Problems

• Use the authenticated /docs route inside the application or serve the static documentation/ folder separately.
• Static documentation is intentionally outside the production public web root unless the buyer publishes it.
• Protected screenshots use authenticated media routes in-app. Do not move private evidence or guest documents into documentation media.
• If an image fails, the page shows a written fallback; verify the relative source file exists in documentation/assets/media/.

Read-only Diagnostic Commands

php artisan about
php artisan migrate:status
php artisan route:list
php artisan access:audit --fail-on-drift
composer validate --strict
composer audit
npm audit --omit=dev

What to Include When Escalating

• Page/route, exact time and timezone, account role, hotel, record reference, and action attempted.
• Exact message and a redacted screenshot showing enough context.
• Relevant log correlation/reference, not an entire log containing secrets.
• Whether the issue is repeatable and whether it affects one record, one hotel, or every hotel.
• Never send .env, database dumps, private evidence, passwords, provider secrets, or unredacted guest documents through ordinary support channels.