FX Modul

modules/fx-rates/src/Api/Router.php

@@ -0,0 +1,145 @@
+<?php
+declare(strict_types=1);
+
+namespace Modules\FxRates\Api;
+
+use Modules\FxRates\Domain\FxRatesService;
+
+final class Router
+{
+    public function __construct(
+        private FxRatesService $service
+    ) {
+    }
+
+    public function handle(string $relativePath): never
+    {
+        $method = strtoupper((string) ($_SERVER['REQUEST_METHOD'] ?? 'GET'));
+        $path = trim($relativePath, '/');
+
+        try {
+            if ($path === 'v1/health' && $method === 'GET') {
+                $this->respond(['ok' => true, 'module' => 'fx-rates']);
+            }
+
+            if ($path === 'v1/status' && $method === 'GET') {
+                $this->respond(['data' => $this->service->latestStatuses()]);
+            }
+
+            if ($path === 'v1/latest' && $method === 'GET') {
+                $symbols = $this->parseCsv($_GET['symbols'] ?? null);
+                $base = $this->stringOrNull($_GET['base'] ?? null);
+                $snapshot = $this->service->snapshot($base, null, $symbols, null);
+                $this->respond(['data' => $snapshot]);
+            }
+
+            if ($path === 'v1/snapshot' && $method === 'GET') {
+                $symbols = $this->parseCsv($_GET['symbols'] ?? null);
+                $base = $this->stringOrNull($_GET['base'] ?? null);
+                $at = $this->stringOrNull($_GET['at'] ?? null);
+                $windowMinutes = $this->intOrNull($_GET['window_minutes'] ?? null);
+                $snapshot = $this->service->snapshot($base, $at, $symbols, $windowMinutes);
+                $this->respond(['data' => $snapshot]);
+            }
+
+            if ($path === 'v1/rate' && $method === 'GET') {
+                $from = $this->stringOrNull($_GET['from'] ?? null);
+                $to = $this->stringOrNull($_GET['to'] ?? null);
+                $at = $this->stringOrNull($_GET['at'] ?? null);
+                $windowMinutes = $this->intOrNull($_GET['window_minutes'] ?? null);
+                $rate = $this->service->findRate($from, $to, $at, $windowMinutes);
+                $this->respond(['data' => $rate]);
+            }
+
+            if ($path === 'v1/history' && $method === 'GET') {
+                $from = $this->stringOrNull($_GET['from'] ?? null);
+                $to = $this->stringOrNull($_GET['to'] ?? null);
+                $fromAt = $this->stringOrNull($_GET['from_at'] ?? null);
+                $toAt = $this->stringOrNull($_GET['to_at'] ?? null);
+                $limit = max(1, min(1000, (int) ($_GET['limit'] ?? 200)));
+                $history = $this->service->history((string) $from, (string) $to, $fromAt, $toAt, $limit);
+                $this->respond(['data' => $history]);
+            }
+
+            if ($path === 'v1/refresh' && $method === 'POST') {
+                $input = $this->input();
+                $base = $this->stringOrNull($input['base'] ?? null);
+                $currencies = $this->parseCsv($input['currencies'] ?? null);
+                $force = !empty($input['force']);
+                $maxAgeHours = is_numeric($input['max_age_hours'] ?? null) ? (float) $input['max_age_hours'] : 24.0;
+
+                $result = $force
+                    ? $this->service->refreshLatestRates($currencies, $base)
+                    : $this->service->ensureFreshLatestRates($maxAgeHours, $base, $currencies);
+
+                $this->respond(['data' => $result], 201);
+            }
+
+            if ($path === 'v1/probe' && $method === 'GET') {
+                $base = $this->stringOrNull($_GET['base'] ?? null);
+                $this->respond(['data' => $this->service->probeLatestRates($base)]);
+            }
+
+            if ($path === 'v1/currencies-probe' && $method === 'GET') {
+                $this->respond(['data' => $this->service->probeCurrencyCatalog()]);
+            }
+
+            $this->respond(['error' => 'Unbekannter API-Pfad.'], 404);
+        } catch (\Throwable $exception) {
+            $this->respond([
+                'error' => 'FX-API Fehler.',
+                'context' => ['message' => $exception->getMessage()],
+            ], 500);
+        }
+    }
+
+    private function respond(array $payload, int $statusCode = 200): never
+    {
+        http_response_code($statusCode);
+        header('Content-Type: application/json; charset=utf-8');
+        echo json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
+        exit;
+    }
+
+    private function input(): array
+    {
+        $raw = file_get_contents('php://input');
+        $decoded = json_decode((string) $raw, true);
+        return is_array($decoded) ? $decoded : [];
+    }
+
+    private function parseCsv(mixed $value): ?array
+    {
+        if (is_array($value)) {
+            $items = $value;
+        } else {
+            $value = trim((string) $value);
+            if ($value === '') {
+                return null;
+            }
+            $items = explode(',', $value);
+        }
+
+        $result = [];
+        foreach ($items as $item) {
+            $item = strtoupper(trim((string) $item));
+            if ($item !== '') {
+                $result[] = $item;
+            }
+        }
+
+        $result = array_values(array_unique($result));
+        return $result !== [] ? $result : null;
+    }
+
+    private function stringOrNull(mixed $value): ?string
+    {
+        $value = trim((string) $value);
+        return $value !== '' ? $value : null;
+    }
+
+    private function intOrNull(mixed $value): ?int
+    {
+        return is_numeric($value) ? (int) $value : null;
+    }
+}

modules/fx-rates/src/Domain/FxRatesService.php

@@ -0,0 +1,576 @@
+<?php
+declare(strict_types=1);
+
+namespace Modules\FxRates\Domain;
+
+use DateTimeImmutable;
+use DateTimeZone;
+use Modules\FxRates\Infrastructure\FxRatesRepository;
+
+final class FxRatesService
+{
+    private array $memoryCache = [];
+
+    public function __construct(
+        private FxRatesRepository $repository,
+        private array $settings = []
+    ) {
+    }
+
+    public function latestStatus(): ?array
+    {
+        return $this->repository->getLatestFetch($this->defaultBaseCurrency());
+    }
+
+    public function latestStatuses(): array
+    {
+        return $this->repository->listLatestFetches();
+    }
+
+    public function snapshot(?string $baseCurrency = null, ?string $at = null, ?array $symbols = null, ?int $windowMinutes = null): ?array
+    {
+        $base = $this->normalizeCurrency($baseCurrency ?: $this->defaultBaseCurrency());
+        if ($base === '') {
+            return null;
+        }
+
+        if ($at === null || trim($at) === '') {
+            $latest = $this->repository->getLatestFetch($base);
+            if ($latest === null) {
+                return null;
+            }
+
+            return $this->repository->getSnapshotByFetchId((int) $latest['id'], $symbols);
+        }
+
+        $atUtc = $this->normalizeTimestamp($at);
+        if ($atUtc === null) {
+            return null;
+        }
+
+        $nearest = $this->repository->getNearestFetch($base, $atUtc, $windowMinutes);
+        if ($nearest === null) {
+            return null;
+        }
+
+        $snapshot = $this->repository->getSnapshotByFetchId((int) $nearest['id'], $symbols);
+        if ($snapshot === null) {
+            return null;
+        }
+
+        return $snapshot + [
+            'requested_at' => $atUtc,
+            'distance_seconds' => $nearest['distance_seconds'] ?? null,
+        ];
+    }
+
+    public function findRate(?string $fromCurrency, ?string $toCurrency, ?string $at = null, ?int $windowMinutes = null): ?array
+    {
+        $from = $this->normalizeCurrency($fromCurrency);
+        $to = $this->normalizeCurrency($toCurrency);
+        if ($from === '' || $to === '') {
+            return null;
+        }
+
+        if ($from === $to) {
+            return [
+                'base_currency' => $from,
+                'target_currency' => $to,
+                'rate' => 1.0,
+                'provider' => 'identity',
+                'fetched_at' => $at ? $this->normalizeTimestamp($at) : null,
+                'rate_date' => $at ? substr((string) $this->normalizeTimestamp($at), 0, 10) : gmdate('Y-m-d'),
+                'is_exact_pair' => true,
+            ];
+        }
+
+        $cacheKey = implode(':', [$from, $to, $at ?? '', (string) ($windowMinutes ?? 0)]);
+        if (array_key_exists($cacheKey, $this->memoryCache)) {
+            return $this->memoryCache[$cacheKey];
+        }
+
+        $candidates = array_values(array_unique(array_filter([
+            $this->defaultBaseCurrency(),
+            'EUR',
+            'USD',
+            $from,
+            $to,
+        ], static fn (?string $value): bool => is_string($value) && trim($value) !== '')));
+
+        foreach ($candidates as $snapshotBase) {
+            $snapshot = $this->snapshot($snapshotBase, $at, [$from, $to], $windowMinutes);
+            if (!is_array($snapshot)) {
+                continue;
+            }
+
+            $rates = is_array($snapshot['rates'] ?? null) ? $snapshot['rates'] : [];
+            $resolved = $this->resolveRateFromSnapshot($snapshot, $rates, $from, $to);
+            if ($resolved !== null) {
+                return $this->memoryCache[$cacheKey] = $resolved;
+            }
+        }
+
+        return $this->memoryCache[$cacheKey] = null;
+    }
+
+    public function convert(?float $amount, ?string $fromCurrency, ?string $toCurrency, ?string $at = null, ?int $windowMinutes = null): ?float
+    {
+        if ($amount === null) {
+            return null;
+        }
+
+        $rate = $this->findRate($fromCurrency, $toCurrency, $at, $windowMinutes);
+        if (!is_numeric($rate['rate'] ?? null)) {
+            return null;
+        }
+
+        return $amount * (float) $rate['rate'];
+    }
+
+    public function refreshLatestRates(?array $currencies = null, ?string $baseCurrency = null): array
+    {
+        $base = $this->normalizeCurrency($baseCurrency ?: $this->defaultBaseCurrency());
+        $payload = $this->fetchLatestPayload($base, $currencies);
+        $rates = is_array($payload['rates'] ?? null) ? $payload['rates'] : [];
+        $rateDate = $this->normalizeRateDate($payload['date'] ?? null);
+        $saved = $this->repository->saveFetch(
+            $base,
+            $this->provider(),
+            $rateDate,
+            $rates,
+            gmdate('Y-m-d H:i:s')
+        );
+
+        return [
+            'base' => $base,
+            'rate_date' => $rateDate,
+            'updated_count' => count($saved['rates'] ?? []),
+            'rates' => $saved['rates'] ?? [],
+            'fetch' => $saved['fetch'] ?? null,
+        ];
+    }
+
+    public function ensureFreshLatestRates(float $maxAgeHours = 24.0, ?string $baseCurrency = null, ?array $currencies = null): array
+    {
+        $base = $this->normalizeCurrency($baseCurrency ?: $this->defaultBaseCurrency());
+        $latest = $this->repository->getLatestFetch($base);
+        $maxAgeSeconds = (int) round(max(1.0, $maxAgeHours) * 3600);
+        $fetchedAt = is_array($latest) ? strtotime((string) ($latest['fetched_at'] ?? '')) : false;
+
+        if ($fetchedAt !== false && (time() - $fetchedAt) <= $maxAgeSeconds) {
+            return [
+                'base' => $base,
+                'rate_date' => $latest['rate_date'] ?? null,
+                'updated_count' => 0,
+                'rates' => [],
+                'fetch' => $latest,
+                'reused' => true,
+            ];
+        }
+
+        $result = $this->refreshLatestRates($currencies, $base);
+        $result['reused'] = false;
+        return $result;
+    }
+
+    public function history(string $fromCurrency, string $toCurrency, ?string $from = null, ?string $to = null, int $limit = 200): array
+    {
+        $fromCurrency = $this->normalizeCurrency($fromCurrency);
+        $toCurrency = $this->normalizeCurrency($toCurrency);
+        if ($fromCurrency === '' || $toCurrency === '') {
+            return [];
+        }
+
+        if ($fromCurrency === $toCurrency) {
+            return [];
+        }
+
+        $direct = $this->repository->listDirectHistory($fromCurrency, $toCurrency, $this->normalizeTimestamp($from), $this->normalizeTimestamp($to), $limit);
+        if ($direct !== []) {
+            return $direct;
+        }
+
+        $inverse = $this->repository->listDirectHistory($toCurrency, $fromCurrency, $this->normalizeTimestamp($from), $this->normalizeTimestamp($to), $limit);
+        if ($inverse === []) {
+            return [];
+        }
+
+        $result = [];
+        foreach ($inverse as $row) {
+            $inverseRate = is_numeric($row['rate'] ?? null) ? (float) $row['rate'] : null;
+            if ($inverseRate === null || $inverseRate <= 0) {
+                continue;
+            }
+
+            $result[] = [
+                'fetch_id' => $row['fetch_id'] ?? null,
+                'base_currency' => $fromCurrency,
+                'target_currency' => $toCurrency,
+                'rate' => 1 / $inverseRate,
+                'rate_date' => $row['rate_date'] ?? null,
+                'provider' => $row['provider'] ?? null,
+                'fetched_at' => $row['fetched_at'] ?? null,
+                'is_exact_pair' => false,
+            ];
+        }
+
+        return $result;
+    }
+
+    public function runScheduledRefresh(array $context = []): array
+    {
+        if (!$this->dailyRefreshEnabled()) {
+            return ['ok' => true, 'message' => 'Taeglicher FX-Abruf ist deaktiviert.', 'skipped' => true];
+        }
+
+        $timezone = $this->scheduleTimezone();
+        $nowLocal = new DateTimeImmutable('now', $timezone);
+        $targetHour = $this->dailyRefreshHour();
+
+        if ((int) $nowLocal->format('G') !== $targetHour) {
+            return [
+                'ok' => true,
+                'message' => 'Kein FX-Abruf: aktuelles Zeitfenster ist ' . $nowLocal->format('H:i') . ', Ziel ist ' . str_pad((string) $targetHour, 2, '0', STR_PAD_LEFT) . ':00.',
+                'skipped' => true,
+                'context' => $context,
+            ];
+        }
+
+        $latest = $this->repository->getLatestFetch($this->defaultBaseCurrency());
+        if (is_array($latest) && trim((string) ($latest['fetched_at'] ?? '')) !== '') {
+            $latestLocal = new DateTimeImmutable((string) $latest['fetched_at'], new DateTimeZone('UTC'));
+            $latestLocal = $latestLocal->setTimezone($timezone);
+            if ($latestLocal->format('Y-m-d') === $nowLocal->format('Y-m-d') && (int) $latestLocal->format('G') >= $targetHour) {
+                return [
+                    'ok' => true,
+                    'message' => 'Kein FX-Abruf: fuer heute existiert bereits ein Snapshot nach ' . str_pad((string) $targetHour, 2, '0', STR_PAD_LEFT) . ':00.',
+                    'skipped' => true,
+                    'fetch' => $latest,
+                    'context' => $context,
+                ];
+            }
+        }
+
+        $result = $this->refreshLatestRates(null, $this->defaultBaseCurrency());
+        return [
+            'ok' => true,
+            'message' => 'Taeglicher FX-Abruf ausgefuehrt: ' . (int) ($result['updated_count'] ?? 0) . ' Kurse gespeichert.',
+            'result' => $result,
+            'context' => $context,
+        ];
+    }
+
+    public function refreshCurrencyCatalog(): array
+    {
+        $payload = $this->fetchCurrenciesPayload();
+        $currencies = is_array($payload['currencies'] ?? null) ? $payload['currencies'] : [];
+        $items = [];
+        foreach ($currencies as $code => $name) {
+            $code = $this->normalizeCurrency((string) $code);
+            $name = trim((string) $name);
+            if ($code === '' || $name === '') {
+                continue;
+            }
+            $items[] = [
+                'code' => $code,
+                'name' => $name,
+            ];
+        }
+
+        return [
+            'synced_count' => count($items),
+            'currencies' => $items,
+        ];
+    }
+
+    public function probeCurrencyCatalog(): array
+    {
+        $payload = $this->fetchCurrenciesPayload();
+        return [
+            'ok' => !empty($payload['currencies']),
+            'provider' => $this->provider(),
+            'currencies_count' => is_array($payload['currencies'] ?? null) ? count($payload['currencies']) : 0,
+        ];
+    }
+
+    public function probeLatestRates(?string $baseCurrency = null): array
+    {
+        $base = $this->normalizeCurrency($baseCurrency ?: $this->defaultBaseCurrency());
+        $payload = $this->fetchLatestPayload($base, null);
+        return [
+            'ok' => !empty($payload['rates']),
+            'provider' => $this->provider(),
+            'base' => $base,
+            'rate_count' => is_array($payload['rates'] ?? null) ? count($payload['rates']) : 0,
+            'date' => $payload['date'] ?? null,
+        ];
+    }
+
+    private function resolveRateFromSnapshot(array $snapshot, array $rates, string $from, string $to): ?array
+    {
+        $base = strtoupper((string) ($snapshot['base_currency'] ?? ''));
+        $rate = null;
+        $isExactPair = false;
+
+        if ($base === $from && is_numeric($rates[$to] ?? null)) {
+            $rate = (float) $rates[$to];
+            $isExactPair = true;
+        } elseif ($base === $to && is_numeric($rates[$from] ?? null) && (float) $rates[$from] > 0) {
+            $rate = 1 / (float) $rates[$from];
+            $isExactPair = true;
+        } elseif (is_numeric($rates[$from] ?? null) && is_numeric($rates[$to] ?? null) && (float) $rates[$from] > 0) {
+            $rate = (float) $rates[$to] / (float) $rates[$from];
+        }
+
+        if ($rate === null || $rate <= 0) {
+            return null;
+        }
+
+        return [
+            'base_currency' => $from,
+            'target_currency' => $to,
+            'rate' => $rate,
+            'provider' => $snapshot['provider'] ?? null,
+            'fetched_at' => $snapshot['fetched_at'] ?? null,
+            'rate_date' => $snapshot['rate_date'] ?? null,
+            'snapshot_base_currency' => $base,
+            'distance_seconds' => $snapshot['distance_seconds'] ?? null,
+            'requested_at' => $snapshot['requested_at'] ?? null,
+            'is_exact_pair' => $isExactPair,
+        ];
+    }
+
+    private function fetchLatestPayload(string $baseCurrency, ?array $currencies = null): array
+    {
+        if (!function_exists('curl_init')) {
+            throw new \RuntimeException('curl_init ist nicht verfuegbar.');
+        }
+
+        $url = $this->buildLatestUrl($baseCurrency);
+        if ($url === null) {
+            throw new \RuntimeException('FX-URL oder API-Key fehlt.');
+        }
+
+        $ch = curl_init();
+        curl_setopt_array($ch, [
+            CURLOPT_URL => $url,
+            CURLOPT_RETURNTRANSFER => true,
+            CURLOPT_FOLLOWLOCATION => true,
+            CURLOPT_TIMEOUT => $this->timeoutSeconds(),
+            CURLOPT_HTTPHEADER => ['Accept: application/json'],
+        ]);
+        $response = curl_exec($ch);
+        $httpStatus = (int) curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
+        $curlError = curl_error($ch);
+        curl_close($ch);
+
+        if ($response === false || $curlError !== '' || $httpStatus >= 400) {
+            throw new \RuntimeException('FX-Kurse konnten nicht geladen werden.');
+        }
+
+        $payload = json_decode((string) $response, true);
+        if (!is_array($payload)) {
+            throw new \RuntimeException('FX-Antwort ist kein gueltiges JSON.');
+        }
+
+        $rates = [];
+        if ($this->provider() === 'currencyapi') {
+            if (($payload['valid'] ?? false) !== true || !is_array($payload['rates'] ?? null)) {
+                throw new \RuntimeException($this->extractProviderError($payload, 'FX-Kurse konnten nicht geladen werden.'));
+            }
+            foreach ($payload['rates'] as $code => $rate) {
+                $code = $this->normalizeCurrency((string) $code);
+                if ($code === '' || $code === $baseCurrency || !is_numeric($rate)) {
+                    continue;
+                }
+                $rates[$code] = (float) $rate;
+            }
+        } else {
+            $rawRates = is_array($payload['rates'] ?? null) ? $payload['rates'] : [];
+            foreach ($rawRates as $code => $rate) {
+                $code = $this->normalizeCurrency((string) $code);
+                if ($code === '' || $code === $baseCurrency || !is_numeric($rate)) {
+                    continue;
+                }
+                $rates[$code] = (float) $rate;
+            }
+        }
+
+        if (is_array($currencies) && $currencies !== []) {
+            $wanted = [];
+            foreach ($currencies as $currency) {
+                $currency = $this->normalizeCurrency((string) $currency);
+                if ($currency !== '' && isset($rates[$currency])) {
+                    $wanted[$currency] = $rates[$currency];
+                }
+            }
+            $rates = $wanted;
+        }
+
+        return [
+            'base' => $baseCurrency,
+            'date' => $payload['updated'] ?? $payload['date'] ?? null,
+            'rates' => $rates,
+        ];
+    }
+
+    private function fetchCurrenciesPayload(): array
+    {
+        if (!function_exists('curl_init')) {
+            throw new \RuntimeException('curl_init ist nicht verfuegbar.');
+        }
+
+        $apiKey = $this->apiKey();
+        if ($apiKey === '') {
+            throw new \RuntimeException('FX-API-Key fehlt.');
+        }
+
+        $url = sprintf(
+            '%s/api/v2/currencies?output=json&key=%s',
+            $this->currenciesApiUrl(),
+            rawurlencode($apiKey)
+        );
+
+        $ch = curl_init();
+        curl_setopt_array($ch, [
+            CURLOPT_URL => $url,
+            CURLOPT_RETURNTRANSFER => true,
+            CURLOPT_FOLLOWLOCATION => true,
+            CURLOPT_TIMEOUT => $this->timeoutSeconds(),
+            CURLOPT_HTTPHEADER => ['Accept: application/json'],
+        ]);
+        $response = curl_exec($ch);
+        $httpStatus = (int) curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
+        $curlError = curl_error($ch);
+        curl_close($ch);
+
+        if ($response === false || $curlError !== '' || $httpStatus >= 400) {
+            throw new \RuntimeException('Waehrungskatalog konnte nicht geladen werden.');
+        }
+
+        $payload = json_decode((string) $response, true);
+        if (!is_array($payload) || ($payload['valid'] ?? false) !== true) {
+            throw new \RuntimeException($this->extractProviderError(is_array($payload) ? $payload : [], 'Waehrungskatalog konnte nicht geladen werden.'));
+        }
+
+        return $payload;
+    }
+
+    private function buildLatestUrl(string $baseCurrency): ?string
+    {
+        $apiKey = $this->apiKey();
+        if ($this->provider() === 'currencyapi') {
+            if ($apiKey === '') {
+                return null;
+            }
+
+            return sprintf(
+                '%s/api/v2/rates?base=%s&output=json&key=%s',
+                $this->apiUrl(),
+                rawurlencode($baseCurrency),
+                rawurlencode($apiKey)
+            );
+        }
+
+        return sprintf('%s/latest?base=%s', $this->apiUrl(), rawurlencode($baseCurrency));
+    }
+
+    private function extractProviderError(array $payload, string $fallback): string
+    {
+        foreach (['error', 'message', 'msg'] as $field) {
+            $value = $payload[$field] ?? null;
+            if (is_string($value) && trim($value) !== '') {
+                return trim($value);
+            }
+        }
+
+        return $fallback;
+    }
+
+    private function normalizeCurrency(?string $currency): string
+    {
+        return strtoupper(trim((string) $currency));
+    }
+
+    private function normalizeTimestamp(?string $value): ?string
+    {
+        $value = trim((string) $value);
+        if ($value === '') {
+            return null;
+        }
+
+        try {
+            $date = new DateTimeImmutable($value);
+            return $date->setTimezone(new DateTimeZone('UTC'))->format('Y-m-d H:i:s');
+        } catch (\Throwable) {
+            return null;
+        }
+    }
+
+    private function normalizeRateDate(mixed $value): string
+    {
+        if (is_string($value) && trim($value) !== '') {
+            $timestamp = strtotime($value);
+            if ($timestamp !== false) {
+                return gmdate('Y-m-d', $timestamp);
+            }
+        }
+
+        if (is_int($value) || is_float($value)) {
+            return gmdate('Y-m-d', (int) $value);
+        }
+
+        return gmdate('Y-m-d');
+    }
+
+    private function provider(): string
+    {
+        $provider = strtolower(trim((string) ($this->settings['provider'] ?? 'currencyapi')));
+        return $provider !== '' ? $provider : 'currencyapi';
+    }
+
+    private function apiUrl(): string
+    {
+        return rtrim((string) ($this->settings['api_url'] ?? 'https://currencyapi.net'), '/');
+    }
+
+    private function currenciesApiUrl(): string
+    {
+        return rtrim((string) ($this->settings['currencies_url'] ?? $this->apiUrl()), '/');
+    }
+
+    private function apiKey(): string
+    {
+        return trim((string) ($this->settings['api_key'] ?? ''));
+    }
+
+    private function timeoutSeconds(): int
+    {
+        return max(2, (int) ($this->settings['timeout_sec'] ?? 10));
+    }
+
+    private function defaultBaseCurrency(): string
+    {
+        return $this->normalizeCurrency((string) ($this->settings['default_base_currency'] ?? 'EUR')) ?: 'EUR';
+    }
+
+    private function dailyRefreshEnabled(): bool
+    {
+        return !empty($this->settings['daily_refresh_enabled']);
+    }
+
+    private function dailyRefreshHour(): int
+    {
+        return max(0, min(23, (int) ($this->settings['daily_refresh_hour'] ?? 18)));
+    }
+
+    private function scheduleTimezone(): DateTimeZone
+    {
+        $timezone = trim((string) ($this->settings['schedule_timezone'] ?? 'Europe/Berlin'));
+        try {
+            return new DateTimeZone($timezone);
+        } catch (\Throwable) {
+            return new DateTimeZone('Europe/Berlin');
+        }
+    }
+}

modules/fx-rates/src/Infrastructure/FxRatesRepository.php

@@ -0,0 +1,418 @@
+<?php
+declare(strict_types=1);
+
+namespace Modules\FxRates\Infrastructure;
+
+use PDO;
+
+final class FxRatesRepository
+{
+    private string $driver;
+
+    public function __construct(
+        private PDO $pdo,
+        private string $tablePrefix = 'fxrate_'
+    ) {
+        $this->driver = strtolower((string) $this->pdo->getAttribute(PDO::ATTR_DRIVER_NAME));
+    }
+
+    public function ensureSchema(): void
+    {
+        $fetchTable = $this->table('fetches');
+        $rateTable = $this->table('rates');
+
+        if ($this->driver === 'pgsql') {
+            $this->pdo->exec("CREATE TABLE IF NOT EXISTS {$fetchTable} (
+                id SERIAL PRIMARY KEY,
+                provider VARCHAR(64) NOT NULL,
+                base_currency VARCHAR(10) NOT NULL,
+                rate_date DATE NOT NULL,
+                fetched_at TIMESTAMP NOT NULL,
+                created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
+            )");
+            $this->pdo->exec("CREATE TABLE IF NOT EXISTS {$rateTable} (
+                id SERIAL PRIMARY KEY,
+                fetch_id INTEGER NOT NULL REFERENCES {$fetchTable}(id) ON DELETE CASCADE,
+                currency_code VARCHAR(10) NOT NULL,
+                current_value NUMERIC(20,10) NOT NULL
+            )");
+            $this->pdo->exec("CREATE INDEX IF NOT EXISTS {$fetchTable}_base_fetch_idx ON {$fetchTable} (base_currency, fetched_at DESC, id DESC)");
+            $this->pdo->exec("CREATE INDEX IF NOT EXISTS {$fetchTable}_rate_date_idx ON {$fetchTable} (rate_date DESC)");
+            $this->pdo->exec("CREATE INDEX IF NOT EXISTS {$rateTable}_fetch_idx ON {$rateTable} (fetch_id)");
+            $this->pdo->exec("CREATE INDEX IF NOT EXISTS {$rateTable}_currency_idx ON {$rateTable} (currency_code)");
+        } elseif ($this->driver === 'mysql') {
+            $this->pdo->exec("CREATE TABLE IF NOT EXISTS {$fetchTable} (
+                id INTEGER PRIMARY KEY AUTO_INCREMENT,
+                provider VARCHAR(64) NOT NULL,
+                base_currency VARCHAR(10) NOT NULL,
+                rate_date DATE NOT NULL,
+                fetched_at DATETIME NOT NULL,
+                created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+                KEY {$fetchTable}_base_fetch_idx (base_currency, fetched_at, id),
+                KEY {$fetchTable}_rate_date_idx (rate_date)
+            )");
+            $this->pdo->exec("CREATE TABLE IF NOT EXISTS {$rateTable} (
+                id INTEGER PRIMARY KEY AUTO_INCREMENT,
+                fetch_id INTEGER NOT NULL,
+                currency_code VARCHAR(10) NOT NULL,
+                current_value DECIMAL(20,10) NOT NULL,
+                KEY {$rateTable}_fetch_idx (fetch_id),
+                KEY {$rateTable}_currency_idx (currency_code)
+            )");
+        } else {
+            $this->pdo->exec("CREATE TABLE IF NOT EXISTS {$fetchTable} (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                provider VARCHAR(64) NOT NULL,
+                base_currency VARCHAR(10) NOT NULL,
+                rate_date DATE NOT NULL,
+                fetched_at DATETIME NOT NULL,
+                created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
+            )");
+            $this->pdo->exec("CREATE TABLE IF NOT EXISTS {$rateTable} (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                fetch_id INTEGER NOT NULL,
+                currency_code VARCHAR(10) NOT NULL,
+                current_value DECIMAL(20,10) NOT NULL
+            )");
+            $this->pdo->exec("CREATE INDEX IF NOT EXISTS {$fetchTable}_base_fetch_idx ON {$fetchTable} (base_currency, fetched_at DESC, id DESC)");
+            $this->pdo->exec("CREATE INDEX IF NOT EXISTS {$fetchTable}_rate_date_idx ON {$fetchTable} (rate_date DESC)");
+            $this->pdo->exec("CREATE INDEX IF NOT EXISTS {$rateTable}_fetch_idx ON {$rateTable} (fetch_id)");
+            $this->pdo->exec("CREATE INDEX IF NOT EXISTS {$rateTable}_currency_idx ON {$rateTable} (currency_code)");
+        }
+    }
+
+    public function getLatestFetch(?string $baseCurrency = null): ?array
+    {
+        $sql = 'SELECT id, provider, base_currency, rate_date, fetched_at, created_at FROM ' . $this->table('fetches');
+        $params = [];
+        if ($baseCurrency !== null && trim($baseCurrency) !== '') {
+            $sql .= ' WHERE base_currency = :base_currency';
+            $params['base_currency'] = strtoupper(trim($baseCurrency));
+        }
+        $sql .= ' ORDER BY fetched_at DESC, id DESC LIMIT 1';
+        $stmt = $this->pdo->prepare($sql);
+        $stmt->execute($params);
+        $row = $stmt->fetch(PDO::FETCH_ASSOC);
+        return is_array($row) ? $this->normalizeFetch($row) : null;
+    }
+
+    public function listLatestFetches(): array
+    {
+        $stmt = $this->pdo->query(
+            'SELECT id, provider, base_currency, rate_date, fetched_at, created_at
+             FROM ' . $this->table('fetches') . '
+             ORDER BY fetched_at DESC, id DESC'
+        );
+
+        $latestByBase = [];
+        foreach ($stmt->fetchAll(PDO::FETCH_ASSOC) ?: [] as $row) {
+            $base = strtoupper(trim((string) ($row['base_currency'] ?? '')));
+            if ($base === '' || isset($latestByBase[$base])) {
+                continue;
+            }
+            $latestByBase[$base] = $this->normalizeFetch($row);
+        }
+
+        ksort($latestByBase);
+        return array_values($latestByBase);
+    }
+
+    public function getSnapshotByFetchId(int $fetchId, ?array $symbols = null): ?array
+    {
+        $fetch = $this->getFetchById($fetchId);
+        if ($fetch === null) {
+            return null;
+        }
+
+        return $fetch + [
+            'rates' => $this->ratesForFetch($fetchId, $symbols),
+        ];
+    }
+
+    public function getNearestFetch(string $baseCurrency, string $timestamp, ?int $windowMinutes = null): ?array
+    {
+        $baseCurrency = strtoupper(trim($baseCurrency));
+        if ($baseCurrency === '') {
+            return null;
+        }
+
+        $before = $this->findNeighborFetch($baseCurrency, $timestamp, '<=');
+        $after = $this->findNeighborFetch($baseCurrency, $timestamp, '>=');
+        $targetTs = strtotime($timestamp);
+        if ($targetTs === false) {
+            return null;
+        }
+
+        $selected = null;
+        $selectedDiff = null;
+        foreach ([$before, $after] as $candidate) {
+            if (!is_array($candidate)) {
+                continue;
+            }
+            $candidateTs = strtotime((string) ($candidate['fetched_at'] ?? ''));
+            if ($candidateTs === false) {
+                continue;
+            }
+            $diffSeconds = abs($candidateTs - $targetTs);
+            if ($selected === null || $diffSeconds < (int) $selectedDiff) {
+                $selected = $candidate;
+                $selectedDiff = $diffSeconds;
+            }
+        }
+
+        if ($selected === null) {
+            return null;
+        }
+
+        if ($windowMinutes !== null && $windowMinutes > 0 && $selectedDiff !== null && $selectedDiff > ($windowMinutes * 60)) {
+            return null;
+        }
+
+        return $selected + ['distance_seconds' => $selectedDiff];
+    }
+
+    public function listDirectHistory(string $baseCurrency, string $targetCurrency, ?string $from = null, ?string $to = null, int $limit = 200): array
+    {
+        $sql = 'SELECT
+                    r.id,
+                    f.id AS fetch_id,
+                    f.base_currency,
+                    r.currency_code AS target_currency,
+                    r.current_value AS rate,
+                    f.rate_date,
+                    f.provider,
+                    f.fetched_at
+                FROM ' . $this->table('rates') . ' r
+                INNER JOIN ' . $this->table('fetches') . ' f ON f.id = r.fetch_id
+                WHERE f.base_currency = :base_currency
+                  AND r.currency_code = :target_currency';
+        $params = [
+            'base_currency' => strtoupper(trim($baseCurrency)),
+            'target_currency' => strtoupper(trim($targetCurrency)),
+        ];
+
+        if ($from !== null && trim($from) !== '') {
+            $sql .= ' AND f.fetched_at >= :from_at';
+            $params['from_at'] = $from;
+        }
+        if ($to !== null && trim($to) !== '') {
+            $sql .= ' AND f.fetched_at <= :to_at';
+            $params['to_at'] = $to;
+        }
+
+        $sql .= ' ORDER BY f.fetched_at ASC, r.id ASC LIMIT :limit';
+        $stmt = $this->pdo->prepare($sql);
+        foreach ($params as $key => $value) {
+            $stmt->bindValue(':' . $key, $value);
+        }
+        $stmt->bindValue(':limit', max(1, $limit), PDO::PARAM_INT);
+        $stmt->execute();
+
+        return array_map(fn (array $row): array => $this->normalizeRate($row), $stmt->fetchAll(PDO::FETCH_ASSOC) ?: []);
+    }
+
+    public function saveFetch(string $baseCurrency, string $provider, string $rateDate, array $rates, ?string $fetchedAt = null): array
+    {
+        $baseCurrency = strtoupper(trim($baseCurrency));
+        $provider = trim($provider) !== '' ? trim($provider) : 'currencyapi';
+        $fetchedAt = trim((string) $fetchedAt) !== '' ? trim((string) $fetchedAt) : gmdate('Y-m-d H:i:s');
+        $normalizedRates = [];
+        foreach ($rates as $currencyCode => $rate) {
+            $currencyCode = strtoupper(trim((string) $currencyCode));
+            if ($currencyCode === '' || $currencyCode === $baseCurrency || !is_numeric($rate)) {
+                continue;
+            }
+            $normalizedRates[$currencyCode] = (float) $rate;
+        }
+
+        $startedTransaction = false;
+        if (!$this->pdo->inTransaction()) {
+            $this->pdo->beginTransaction();
+            $startedTransaction = true;
+        }
+
+        try {
+            if ($this->driver === 'pgsql') {
+                $fetchStmt = $this->pdo->prepare(
+                    'INSERT INTO ' . $this->table('fetches') . ' (
+                        provider, base_currency, rate_date, fetched_at
+                     ) VALUES (
+                        :provider, :base_currency, :rate_date, :fetched_at
+                     )
+                     RETURNING *'
+                );
+                $fetchStmt->execute([
+                    'provider' => $provider,
+                    'base_currency' => $baseCurrency,
+                    'rate_date' => $rateDate,
+                    'fetched_at' => $fetchedAt,
+                ]);
+                $fetch = $this->normalizeFetch($fetchStmt->fetch(PDO::FETCH_ASSOC) ?: []);
+            } else {
+                $fetchStmt = $this->pdo->prepare(
+                    'INSERT INTO ' . $this->table('fetches') . ' (
+                        provider, base_currency, rate_date, fetched_at
+                     ) VALUES (
+                        :provider, :base_currency, :rate_date, :fetched_at
+                     )'
+                );
+                $fetchStmt->execute([
+                    'provider' => $provider,
+                    'base_currency' => $baseCurrency,
+                    'rate_date' => $rateDate,
+                    'fetched_at' => $fetchedAt,
+                ]);
+                $fetch = $this->getFetchById((int) $this->pdo->lastInsertId()) ?? [];
+            }
+
+            $savedRates = [];
+            if ($normalizedRates !== []) {
+                $placeholders = [];
+                $params = ['fetch_id' => (int) ($fetch['id'] ?? 0)];
+                $index = 0;
+                foreach ($normalizedRates as $currencyCode => $rate) {
+                    $codeKey = 'currency_code_' . $index;
+                    $valueKey = 'current_value_' . $index;
+                    $placeholders[] = "(:fetch_id, :{$codeKey}, :{$valueKey})";
+                    $params[$codeKey] = $currencyCode;
+                    $params[$valueKey] = $rate;
+                    $savedRates[] = [
+                        'fetch_id' => $fetch['id'] ?? null,
+                        'base_currency' => $baseCurrency,
+                        'target_currency' => $currencyCode,
+                        'rate' => $rate,
+                        'rate_date' => $rateDate,
+                        'provider' => $provider,
+                        'fetched_at' => $fetchedAt,
+                    ];
+                    $index++;
+                }
+
+                $insert = $this->pdo->prepare(
+                    'INSERT INTO ' . $this->table('rates') . ' (fetch_id, currency_code, current_value) VALUES ' . implode(', ', $placeholders)
+                );
+                $insert->execute($params);
+            }
+
+            if ($startedTransaction) {
+                $this->pdo->commit();
+            }
+
+            return [
+                'fetch' => $fetch,
+                'rates' => $savedRates,
+            ];
+        } catch (\Throwable $exception) {
+            if ($startedTransaction && $this->pdo->inTransaction()) {
+                $this->pdo->rollBack();
+            }
+            throw $exception;
+        }
+    }
+
+    private function getFetchById(int $fetchId): ?array
+    {
+        $stmt = $this->pdo->prepare(
+            'SELECT id, provider, base_currency, rate_date, fetched_at, created_at
+             FROM ' . $this->table('fetches') . '
+             WHERE id = :id
+             LIMIT 1'
+        );
+        $stmt->execute(['id' => $fetchId]);
+        $row = $stmt->fetch(PDO::FETCH_ASSOC);
+        return is_array($row) ? $this->normalizeFetch($row) : null;
+    }
+
+    private function findNeighborFetch(string $baseCurrency, string $timestamp, string $operator): ?array
+    {
+        $order = $operator === '<=' ? 'DESC' : 'ASC';
+        $stmt = $this->pdo->prepare(
+            'SELECT id, provider, base_currency, rate_date, fetched_at, created_at
+             FROM ' . $this->table('fetches') . '
+             WHERE base_currency = :base_currency
+               AND fetched_at ' . $operator . ' :target_at
+             ORDER BY fetched_at ' . $order . ', id ' . $order . '
+             LIMIT 1'
+        );
+        $stmt->execute([
+            'base_currency' => $baseCurrency,
+            'target_at' => $timestamp,
+        ]);
+        $row = $stmt->fetch(PDO::FETCH_ASSOC);
+        return is_array($row) ? $this->normalizeFetch($row) : null;
+    }
+
+    private function ratesForFetch(int $fetchId, ?array $symbols = null): array
+    {
+        $sql = 'SELECT currency_code, current_value FROM ' . $this->table('rates') . ' WHERE fetch_id = :fetch_id';
+        $params = ['fetch_id' => $fetchId];
+
+        $normalizedSymbols = [];
+        if (is_array($symbols)) {
+            foreach ($symbols as $symbol) {
+                $symbol = strtoupper(trim((string) $symbol));
+                if ($symbol !== '') {
+                    $normalizedSymbols[] = $symbol;
+                }
+            }
+            $normalizedSymbols = array_values(array_unique($normalizedSymbols));
+        }
+
+        if ($normalizedSymbols !== []) {
+            $placeholders = [];
+            foreach ($normalizedSymbols as $index => $symbol) {
+                $key = 'symbol_' . $index;
+                $placeholders[] = ':' . $key;
+                $params[$key] = $symbol;
+            }
+            $sql .= ' AND currency_code IN (' . implode(', ', $placeholders) . ')';
+        }
+
+        $sql .= ' ORDER BY currency_code ASC';
+        $stmt = $this->pdo->prepare($sql);
+        $stmt->execute($params);
+
+        $rates = [];
+        foreach ($stmt->fetchAll(PDO::FETCH_ASSOC) ?: [] as $row) {
+            $code = strtoupper(trim((string) ($row['currency_code'] ?? '')));
+            $rate = $row['current_value'] ?? null;
+            if ($code === '' || !is_numeric($rate)) {
+                continue;
+            }
+            $rates[$code] = (float) $rate;
+        }
+
+        return $rates;
+    }
+
+    private function normalizeFetch(array $row): array
+    {
+        return [
+            'id' => isset($row['id']) ? (int) $row['id'] : null,
+            'provider' => (string) ($row['provider'] ?? ''),
+            'base_currency' => strtoupper((string) ($row['base_currency'] ?? '')),
+            'rate_date' => (string) ($row['rate_date'] ?? ''),
+            'fetched_at' => (string) ($row['fetched_at'] ?? ''),
+            'created_at' => (string) ($row['created_at'] ?? ''),
+        ];
+    }
+
+    private function normalizeRate(array $row): array
+    {
+        return [
+            'id' => isset($row['id']) ? (int) $row['id'] : null,
+            'fetch_id' => isset($row['fetch_id']) ? (int) $row['fetch_id'] : null,
+            'base_currency' => strtoupper((string) ($row['base_currency'] ?? '')),
+            'target_currency' => strtoupper((string) ($row['target_currency'] ?? '')),
+            'rate' => is_numeric($row['rate'] ?? null) ? (float) $row['rate'] : null,
+            'rate_date' => (string) ($row['rate_date'] ?? ''),
+            'provider' => (string) ($row['provider'] ?? ''),
+            'fetched_at' => (string) ($row['fetched_at'] ?? ''),
+        ];
+    }
+
+    private function table(string $logicalName): string
+    {
+        return $this->tablePrefix . preg_replace('/[^a-zA-Z0-9_]/', '', $logicalName);
+    }
+}