updated design

Modules/Helpdesk/Documentation/Remote_Sync.md

@@ -0,0 +1,83 @@
+# Helpdesk Remote Sync
+
+The Helpdesk module can synchronise its configuration and operational data between two Helpdesk installations.
+
+## Configure both hosts
+
+Use a long random shared token. You can use the same token in both directions or separate inbound/outbound tokens.
+
+```dotenv
+HELPDESK_SYNC_REMOTE_URL=https://other-helpdesk.example.com
+HELPDESK_SYNC_REMOTE_TOKEN=replace-with-a-long-random-token
+HELPDESK_SYNC_ACCEPT_TOKEN=replace-with-a-long-random-token
+
+HELPDESK_SYNC_INCLUDE_ATTACHMENTS=true
+HELPDESK_SYNC_MAX_ATTACHMENT_BYTES=10485760
+HELPDESK_SYNC_TIMEOUT=120
+```
+
+After changing `.env`:
+
+```bash
+php artisan optimize:clear
+```
+
+## Check the remote endpoint
+
+```bash
+curl -H "Authorization: Bearer YOUR_TOKEN" \
+    https://other-helpdesk.example.com/api/helpdesk/sync/status
+```
+
+## Pull from the configured remote host
+
+```bash
+php artisan helpdesk:sync pull
+```
+
+## Push to the configured remote host
+
+```bash
+php artisan helpdesk:sync push
+```
+
+## Settings only
+
+```bash
+php artisan helpdesk:sync pull --settings-only
+php artisan helpdesk:sync push --settings-only
+```
+
+## Do not transfer attachment file contents
+
+```bash
+php artisan helpdesk:sync pull --without-files
+```
+
+Attachment database metadata still synchronises when Helpdesk data is included.
+
+## Mirror mode
+
+By default, sync is non-destructive: rows are inserted or updated but destination-only rows are retained.
+
+To make the destination mirror the source:
+
+```bash
+php artisan helpdesk:sync pull --mirror
+```
+
+Use mirror mode carefully. It can delete Helpdesk records from the destination.
+
+## User mapping
+
+Helpdesk users are mapped by email address, not numeric user ID. `helpdesk_admin` and `helpdesk_agent` flags are synchronised. Password hashes are never copied. If a referenced user does not exist on the destination, a local user record is created with a random password.
+
+## API endpoints
+
+All sync endpoints require a Bearer token matching `HELPDESK_SYNC_ACCEPT_TOKEN`.
+
+- `GET /api/helpdesk/sync/status`
+- `GET /api/helpdesk/sync/export`
+- `POST /api/helpdesk/sync/import`
+
+The payload is versioned using `schema_version`.