Phase F

docs/integrations/whmcs/reconciliation.md

@@ -0,0 +1,53 @@
+# WHMCS reconciliation (Phase E)
+
+HexaHost GameCloud compares WHMCS service links with server state and reports drift.
+
+## API endpoints
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| `GET` | `/integrations/whmcs/accounts` | ListAccounts sync payload |
+| `POST` | `/integrations/whmcs/services/import` | Link an existing GameCloud server |
+| `POST` | `/integrations/whmcs/reconcile` | Full installation reconciliation |
+| `POST` | `/integrations/whmcs/services/:id/reconcile` | Single-service reconciliation |
+| `GET` | `/integrations/whmcs/events` | Cursor-based event poll |
+| `POST` | `/integrations/whmcs/events/ack` | Acknowledge or dead-letter events |
+
+## Reconciliation checks
+
+- Suspended link without billing suspension
+- Active link with billing suspension
+- Terminated link with non-deleted server
+- Running server while suspended
+- Plan / RAM mismatch (when expected values provided)
+- Orphan servers (WHMCS client without service link)
+- Missing join slug (info)
+
+## Severity
+
+`INFO`, `WARNING`, `BLOCKING`, `DESTRUCTIVE`, `SECURITY`
+
+Automatic repair (`autoRepair: true`, `dryRun: false`) only applies safe fixes:
+
+- Apply billing suspension when link is suspended
+- Clear billing suspension when WHMCS reports Active
+- Block running servers that should be suspended
+
+## Events
+
+GameCloud emits:
+
+- `reconciliation_required` — blocking/security issues found
+- `usage_period_ready` — previous UTC month closed (worker)
+
+WHMCS should poll `GET /events`, process payloads, then `POST /events/ack`. Failed events can be dead-lettered.
+
+## PHP module
+
+- `hexagamecloud_ListAccounts()` — server sync
+- `ApiClient::reconcileService()` / `reconcileAll()`
+- `ApiClient::importService()` for controlled imports
+
+## Worker
+
+Daily at 03:00 UTC the worker runs a lightweight reconciliation pass for all active installations.