Initialer Laravel Commit für BetiX

docs/gateway.md

@@ -0,0 +1,93 @@
+# API Gateway in this Laravel App
+
+This app acts as a thin API Gateway in front of an external backend API. All feature controllers proxy to the external API and no longer access a local database.
+
+## Configuration
+
+Set these env vars (see `config/services.php`):
+
+- `BACKEND_API_BASE` (default: `http://casinoapi.test`)
+- `BACKEND_API_TOKEN` (required, Bearer service token)
+- `BACKEND_API_TIMEOUT` (float seconds, default `8.0`)
+
+## Standard Upstream Headers
+
+Every upstream call includes:
+
+- `Authorization: Bearer {BACKEND_API_TOKEN}`
+- `X-User-Id: <laravel_auth_user_id>`
+- `X-User-Device: <sha256(User-Agent|SessionId)>`
+- `X-User-IP: <sha256(ip)>`
+- `Accept: application/json` (SSE endpoints use `text/event-stream`)
+
+## Timeouts & Retries
+
+- Timeout: `8` seconds (configurable via `BACKEND_API_TIMEOUT`).
+- Retries: GET requests retry 2x on timeout/5xx with 100ms backoff. Mutations (POST/PATCH/DELETE) do not retry.
+
+## Error Mapping (Gateway → Frontend)
+
+- Upstream 4xx → same 4xx, body:
+  ```json
+  { "error": "client_error", "message": "Invalid request" }
+  ```
+- Upstream 5xx (reachable server) → `503`, body:
+  ```json
+  { "error": "service_unavailable", "message": "Internal server error" }
+  ```
+- Network/Timeout/Unreachable → `502`, body:
+  ```json
+  { "error": "bad_gateway", "message": "API server not reachable" }
+  ```
+
+## Shared Building Blocks
+
+- `App\Services\BackendHttpClient` centralizes Base URL, token, timeout, GET retry policy, and user-context headers.
+- `App\Http\Controllers\Concerns\ProxiesBackend` provides the error mapping helpers used by all controllers.
+
+## Domains proxied
+
+- Chat: `GET/POST /api/chat`, `POST /api/chat/{id}/react` → upstream `/chat`
+- Support: `/api/support/*` → upstream `/support/*` (SSE passthrough for `/stream`)
+- Vault: `/api/wallet/vault*` → upstream `/wallet/vault*`
+- Social/Profile/Friends: profile page & actions → upstream `/users/*`, `/social/*`, `/friends/*`
+- Bonuses/Promos: `/api/bonuses/app`, `/api/user/bonuses`, `/api/promos/apply` → upstream `/bonuses/app`, `/users/me/bonuses`, `/promos/apply`
+- Guilds: pages & actions → upstream `/guilds*`
+- Wallet/VIP: pages/actions → upstream `/wallet`, `/vip-levels*`
+- Admin: pages/actions → upstream `/admin/*`
+
+## Frontend Contract Notes
+
+- Internal routes (`/api/...` or page routes) remain stable. Controllers may reshape upstream JSON minimally to the shapes already expected by Vue components.
+- Example: Chat GET maps upstream `{ messages: [...] }` to `{ data: [...], last_id }` and flattens user + reactions.
+
+## Example: Faking Upstream in Tests
+
+All proxy feature tests use `Http::fake()` to simulate the external API.
+
+```php
+use Illuminate\Support\Facades\Http;
+
+Http::fake([
+    config('services.backend.base') . '/chat*' => Http::response([
+        'messages' => [ ['id'=>1,'user_id'=>2,'username'=>'dolo','avatar'=>null,'message'=>'hi','reactions'=>[],'created_at'=>now()->toIso8601String()] ],
+    ], 200),
+]);
+
+$res = $this->actingAs($user)->get('/api/chat?limit=50');
+$res->assertStatus(200)->assertJsonStructure(['data','last_id']);
+```
+
+## Running Tests
+
+- Ensure `.env.testing` sets `BACKEND_API_BASE` (any value is fine) and no real external calls are required (we fake all with `Http::fake()`).
+- Run: `php artisan test` or `vendor\bin\phpunit`.
+
+## SSE Support (Support Chat)
+
+- `GET /api/support/stream` passes through `text/event-stream` from upstream. If upstream is not OK or stream fails to start, the Gateway returns `503 service_unavailable` JSON.
+
+## Extending
+
+- Add new upstream endpoints by injecting `BackendHttpClient` into your controller and using `get/post/patch/delete/postMultipart`.
+- Always use `ProxiesBackend` helpers to map errors consistently.