Česká spořitelna Premium API - Data Synchronization Service

Aplikace pro pravidelné stahování a ukládání kompletní historie transakcí a stavu bankovních účtů z Česká spořitelna Premium Accounts API v3 do databáze PostgreSQL, vybavená webovou administrací v Reactu a běžící v Dockeru.

---

🚀 Klíčové funkce

• Automatická hodinová synchronizace: Na pozadí běží cron plánovač (0 * * * *), který každou hodinu automaticky stahuje transakce za předchozí období.
• Kompletní ukládání dat (Lossless):
  • Ukládá klíčové strukturované sloupce pro rychlé vyhledávání a filtrování (datum zaúčtování, částka, měna, CRDT/DBIT, variabilní symbol, specifický symbol, konstantní symbol, název a číslo účtu protistrany, zpráva pro příjemce).
  • Všechna surová data z bankovního API jsou zachována v databázovém sloupci raw_data JSONB.
• Prevence duplicit (Idempotence): Každá transakce je identifikována podle unikátního bankovního klíče (account_id, entry_reference) s podporou UPSERT logiky.
• Jednoduchý React konfigurační web:
  • Přehled (Dashboard): Souhrnné statistiky, zůstatky, stav plánovače, rychlé manuální spuštění.
  • Účty: Přehled bankovních účtů s účetním i disponibilním zůstatkem.
  • Transakce: Vyhledávání podle VS, příjemce, zprávy; filtrování podle účtu, data a směru; inspekce surového JSONu.
  • Konfigurace: Nastavení Base URL (Sandbox / Produkce), WEB-API-key, Bearer token, intervalu cronu a okamžitý test spojení.
  • Mock režim (Simulátor): Možnost provozu s vestavěnými simulovanými daty ČS API pro snadné testování bez nutnosti aktivního bankovního certifikátu/tokenu.
  • Historie synchronizací: Auditní log všech plánovaných i ručních běhů včetně počtu stažených transakcí a chybových hlášení.

---

🛠️ Spuštění v Dockeru (Doporučeno)

Pro spuštění celé aplikace (PostgreSQL + Backend + Frontend s Nginx proxy) stačí mít nainstalovaný Docker a spustit:

docker compose up -d

Aplikace bude ihned dostupná na:

• Webové rozhraní (Frontend): http://localhost:5050
• Backend API: http://localhost:3001
• PostgreSQL Databáze: localhost:5432 (uživatel: postgres, heslo: postgres_secure_pass, databáze: csas_data_sync)

Pro zastavení:

docker compose down

---

💻 Lokální spuštění bez Dockeru (Vývoj)

1. Příprava databáze PostgreSQL

Ujistěte se, že máte spuštěný PostgreSQL a vytvořenou databázi csas_data_sync.

2. Spuštění backendu

cd backend
npm install
npm run dev

Backend automaticky provede databázové migrace, inicializuje plánovač a naslouchá na portu 3001.

3. Spuštění frontendu

cd frontend
npm install
npm run dev

Frontend se spustí na http://localhost:5050 a automaticky směruje volání /api na backend.

---

⚙️ Konfigurace API Česká spořitelna

V konfiguračním webu (nebo v .env) můžete nastavit:

Parametr	Popis
CSAS_BASE_URL	https://webapi.developers.erstegroup.com/api/csas/public/sandbox/v3/accounts (Sandbox) nebo https://www.csas.cz/webapi/api/v3/accounts (Produkce)
CSAS_WEB_API_KEY	Klíč vygenerovaný na Developer portálu ČS (posílaný v hlavičce WEB-API-key)
CSAS_BEARER_TOKEN	OAuth 2.0 Access token (posílaný v hlavičce Authorization: Bearer <token>)
SYNC_CRON	Cron výraz plánovače (výchozí: 0 * * * * = každou celou hodinu)
MOCK_MODE	true / false - přepínač do simulátoru pro testování

---

🗄️ Databázové schéma

1. app_config: Ukládá parametry konfigurace, API klíče a stav plánovače.
2. accounts: Seznam účtů klienta (ID, IBAN, měna, název produktu, jméno majitele, surová data v raw_data JSONB).
3. account_balances: Aktuální zůstatky účtů (closingAvailable, closingBooked).
4. transactions: Kompletní historie transakcí s unikátním indexem (account_id, entry_reference), indexovaným datem zaúčtování a variabilním symbolem.
5. sync_logs: Záznamy o každém proběhlém synchronizačním běhu.