Implement WHMCS Addon Dashboard with API for stats and integrate billing provider logic

docs/IMPLEMENTATION_STATUS.md

@@ -2,7 +2,39 @@
 
 Last updated: 2026-06-26
 
-## Current phase: WHMCS Phase E + F — Sync & Usage Billing ✅
+## Current phase: WHMCS Addon Dashboard ✅
+
+### WHMCS Addon module completed
+
+| Area | Status | Notes |
+|------|--------|-------|
+| Addon PHP module | Done | Dashboard, events, reconciliation UI |
+| Module tables | Done | `mod_hexagamecloud_*` on activation |
+| Event poller | Done | Manual + daily cron hook |
+| Dashboard API | Done | `GET /integrations/whmcs/dashboard/stats` |
+| Cron hook | Done | `integrations/whmcs/hooks/hexagamecloud.php` |
+| Docs | Done | `docs/integrations/whmcs/addon-module.md` |
+
+### Billing providers
+
+| Provider | Status | Notes |
+|----------|--------|-------|
+| WHMCS | Done | **Production default** (`BILLING_PROVIDER=whmcs`) |
+| Internal | Done | Dev / free tier credits |
+| Stripe | Stub | Optional fallback webhook — inactive unless `BILLING_PROVIDER=stripe` |
+
+See `docs/billing/providers.md`.
+
+### Abnahmekriterium Addon
+
+- [x] WHMCS admin dashboard shows API health and sync stats
+- [x] Event poll + ack from addon UI and cron hook
+- [x] Reconciliation dry-run from addon UI
+- [ ] Manual E2E: activate addon on WHMCS host
+
+---
+
+## WHMCS Phase E + F — Sync & Usage Billing ✅
 
 ### WHMCS Phase E completed
 
@@ -234,4 +266,4 @@ Server entry fields:
 
 ### Next phase: Post-MVP hardening
 
-- Stripe webhooks, penetration test, WHMCS addon dashboard UI
+- Penetration test, product mapping UI in addon, mTLS for integration API

docs/billing/providers.md

@@ -0,0 +1,43 @@
+# Billing providers
+
+GameCloud supports three billing modes via `BILLING_PROVIDER`:
+
+| Provider | Use case | Credit wallet |
+|----------|----------|---------------|
+| `internal` | Dev / free tier | Required for start |
+| `whmcs` | **Production default** | Bypassed — WHMCS bills customers |
+| `stripe` | Optional fallback without WHMCS | Bypassed — extend webhook handler |
+
+## WHMCS (recommended)
+
+```env
+BILLING_PROVIDER=whmcs
+WHMCS_INTEGRATION_ID=your-integration-id
+WHMCS_API_SECRET=your-secret
+```
+
+Commercial lifecycle (orders, invoices, suspend, usage metrics) runs entirely in WHMCS. GameCloud enforces `billingSuspendedAt` from WHMCS API calls.
+
+## Internal (development)
+
+```env
+BILLING_PROVIDER=internal
+```
+
+Uses the credit wallet and usage metering from Phase 7. Suitable for local development and standalone free tier.
+
+## Stripe (optional fallback)
+
+```env
+BILLING_PROVIDER=stripe
+STRIPE_SECRET_KEY=sk_test_...
+STRIPE_WEBHOOK_SECRET=whsec_...
+```
+
+Webhook endpoint: `POST /api/v1/webhooks/stripe`
+
+When `BILLING_PROVIDER` is not `stripe`, webhooks return `{ received: true, mode: 'ignored' }` without side effects.
+
+The current implementation verifies signatures and logs events idempotently. Extend `StripeWebhookService` to map Stripe customers to GameCloud users if you deploy without WHMCS.
+
+**Do not enable Stripe and WHMCS billing simultaneously** — choose one commercial system of record.

docs/integrations/whmcs/addon-module.md

@@ -0,0 +1,29 @@
+# WHMCS addon module
+
+The addon provides global GameCloud administration inside WHMCS. **WHMCS remains the commercial system of record**; this module does not process payments.
+
+## Install
+
+1. Copy `integrations/whmcs/modules/addons/hexagamecloud` to `/modules/addons/hexagamecloud`
+2. **Setup → Addon Modules** → activate **HexaHost GameCloud**
+3. Configure:
+   - **GameCloud API URL** — e.g. `https://api.example.net`
+   - **Integration ID** — matches `WHMCS_INTEGRATION_ID` on GameCloud
+   - **API Secret** — matches `WHMCS_API_SECRET`
+4. Copy `integrations/whmcs/hooks/hexagamecloud.php` to WHMCS `includes/hooks/hexagamecloud.php`
+
+## Pages
+
+| Tab | Purpose |
+|-----|---------|
+| Dashboard | Health, counts, last sync |
+| Events | Poll, view, ack, dead-letter |
+| Reconciliation | Dry-run / live reconcile |
+
+## Cron
+
+The daily hook polls pending GameCloud events and optionally runs a dry reconciliation when **Auto-reconcile on daily cron** is enabled.
+
+## Billing
+
+Set `BILLING_PROVIDER=whmcs` on GameCloud in production. Stripe (`BILLING_PROVIDER=stripe`) is an optional fallback for standalone deployments without WHMCS — see [billing providers](../../billing/providers.md).