Phase F

docs/IMPLEMENTATION_STATUS.md

@@ -2,7 +2,50 @@
 
 Last updated: 2026-06-26
 
-## Current phase: WHMCS Phase D — SSO ✅
+## Current phase: WHMCS Phase E + F — Sync & Usage Billing ✅
+
+### WHMCS Phase E completed
+
+| Area | Status | Notes |
+|------|--------|-------|
+| ListAccounts API | Done | `GET /integrations/whmcs/accounts` |
+| Service import | Done | `POST .../services/import` |
+| Reconciliation | Done | Full + per-service, severity classification |
+| Integration events | Done | Cursor poll + ack/dead-letter |
+| Worker daily sync | Done | 03:00 UTC reconciliation tick |
+| WHMCS PHP | Done | `ListAccounts`, reconcile/import client |
+| Docs | Done | `docs/integrations/whmcs/reconciliation.md` |
+
+### WHMCS Phase F completed
+
+| Area | Status | Notes |
+|------|--------|-------|
+| Usage metrics API | Done | `GET .../services/:id/usage` |
+| Usage adjustments | Done | `POST .../usage/adjustments` |
+| Export audit | Done | `WhmcsUsageExport` + content hash |
+| Test mode | Done | `testMode=true` → DRAFT exports |
+| WHMCS PHP | Done | `MetricProvider`, `UsageUpdate` |
+| Docs | Done | `docs/integrations/whmcs/usage-billing.md` |
+
+### Abnahmekriterium Phase E
+
+- [x] ListAccounts liefert alle verknüpften Services
+- [x] Reconciliation erkennt Status-, Plan- und Orphan-Drift
+- [x] Events cursorbasiert mit Ack/Dead-Letter
+- [x] Import bestehender Server möglich
+- [ ] Manual E2E: WHMCS Server-Sync + Reconcile-Button
+
+### Abnahmekriterium Phase F
+
+- [x] Metriken aus `usage_records` aggregiert (UTC-Perioden)
+- [x] Idempotente Exporte mit Hash
+- [x] Adjustments ohne Rohdaten-Mutation
+- [x] WHMCS MetricProvider + UsageUpdate
+- [ ] Manual E2E: WHMCS Usage Metrics Abrechnungslauf
+
+---
+
+## WHMCS Phase D — SSO ✅
 
 ### WHMCS Phase D completed
 
@@ -191,4 +234,4 @@ Server entry fields:
 
 ### Next phase: Post-MVP hardening
 
-- WHMCS Phase E (reconciliation), Phase F (usage billing), Stripe webhooks, penetration test
+- Stripe webhooks, penetration test, WHMCS addon dashboard UI

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.

docs/integrations/whmcs/usage-billing.md

@@ -0,0 +1,50 @@
+# WHMCS usage billing (Phase F)
+
+GameCloud aggregates immutable usage from `usage_records` and exposes WHMCS-compatible metrics.
+
+## Metrics
+
+| Key | Source |
+|-----|--------|
+| `runtime_minutes` | Sum of metered runtime |
+| `memory_gib_minutes` | RAM × runtime (GiB-minutes) |
+| `cpu_core_minutes` | Runtime × plan CPU cores |
+| `storage_gib_days` | Allocated disk × period days |
+| `backup_storage_gib_days` | Completed backup sizes |
+| `egress_gib` | Reserved (0 until metering) |
+| `extra_port_days` | Reserved (0) |
+| `priority_queue_minutes` | Queue priority weighted runtime |
+| `managed_service_units` | Reserved (0) |
+
+## API
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| `GET` | `/integrations/whmcs/services/:id/usage` | Period metrics + UsageUpdate values |
+| `POST` | `/integrations/whmcs/services/:id/usage/adjustments` | Post-export corrections |
+
+Query parameters:
+
+- `periodStart` / `periodEnd` — ISO-8601 UTC (default: current UTC month)
+- `testMode=true` — draft export, no billing event
+
+Responses are idempotent per installation, service, period, and test mode. Each export stores a `contentHash` for audit.
+
+## Adjustments
+
+Corrections never mutate historical raw `usage_records`. Submit metric deltas via the adjustments endpoint; the export status becomes `ADJUSTED`.
+
+## PHP module
+
+- `hexagamecloud_MetricProvider()` — returns `metrics` for WHMCS usage metrics
+- `hexagamecloud_UsageUpdate()` — returns `diskusage` and `bandwidth` for classic billing
+
+Both call `GET .../usage` on GameCloud.
+
+## Test mode
+
+Set `testMode` in the API query or enable test mode in the product config. Test exports use status `DRAFT` and do not emit `usage_period_closed` events.
+
+## Pricing
+
+All prices remain in WHMCS. GameCloud only supplies measured quantities.