Přeskočit na hlavní obsah

Backend - Serverová logika

Dokumentace backendové části modulu Banking - kontrolery, služby, API, hooky a naplánované úlohy.

Architektura​

Modul Banking následuje standardní EspoCRM architekturu:

  • Entities - Datové modely
  • Controllers - REST API endpointy
  • Services - Business logika
  • Repositories - Databázové operace
  • Hooks - Lifecycle události
  • Jobs - Naplánované úlohy
  • API - Custom API endpointy
  • Classes - Pomocné třídy

Kontrolery (Controllers)​

Bank Controller​

Cesta: backend/Controllers/Bank.php Namespace: Espo\Modules\Banking\Controllers

Zajišťuje REST API operace pro entitu Bank:

  • GET /api/v1/Bank - Získání seznamu bank
  • GET /api/v1/Bank/{id} - Získání detailu banky
  • POST /api/v1/Bank - Vytvoření nové banky
  • PUT /api/v1/Bank/{id} - Aktualizace banky
  • DELETE /api/v1/Bank/{id} - Smazání banky

BankAccount Controller​

Cesta: backend/Controllers/BankAccount.php Namespace: Espo\Modules\Banking\Controllers

Zajišťuje REST API operace pro entitu BankAccount:

  • GET /api/v1/BankAccount - Seznam účtů
  • GET /api/v1/BankAccount/{id} - Detail účtu
  • POST /api/v1/BankAccount - Vytvoření účtu
  • PUT /api/v1/BankAccount/{id} - Aktualizace účtu
  • DELETE /api/v1/BankAccount/{id} - Smazání účtu

BankTransaction Controller​

Cesta: backend/Controllers/BankTransaction.php Namespace: Espo\Modules\Banking\Controllers

Zajišťuje REST API operace pro entitu BankTransaction:

  • GET /api/v1/BankTransaction - Seznam transakcí
  • GET /api/v1/BankTransaction/{id} - Detail transakce
  • POST /api/v1/BankTransaction - Vytvoření transakce
  • PUT /api/v1/BankTransaction/{id} - Aktualizace transakce
  • DELETE /api/v1/BankTransaction/{id} - Smazání transakce

Služby (Services)​

Bank Service​

Cesta: backend/Services/Bank.php Namespace: Espo\Modules\Banking\Services

Business logika pro práci s bankami:

  • Validace dat při vytváření/úpravě
  • Správa notifikací
  • Propojení s účty a transakcemi

BankAccount Service​

Cesta: backend/Services/BankAccount.php Namespace: Espo\Modules\Banking\Services

Business logika pro práci s bankovními účty:

  • Validace bankovních údajů (IBAN, SWIFT)
  • Správa credentials
  • Stahování transakcí z API
  • Aktualizace zůstatku
  • Validace formátu čísla účtu

Klíčové metody:

  • downloadTransactions($accountId) - Stažení nových transakcí
  • validateBankAccountNumber($number) - Validace čísla účtu
  • updateBalance($accountId) - Aktualizace zůstatku

BankTransaction Service​

Cesta: backend/Services/BankTransaction.php Namespace: Espo\Modules\Banking\Services

Business logika pro práci s transakcemi:

  • Import transakcí z API
  • Párování s fakturami
  • Zpracování e-mailových výpisů
  • Prevence duplicit (foreign ID)

Klíčové metody:

  • pairWithInvoice($transactionId) - Párování s fakturou
  • importFromEmail($emailId) - Import z e-mailu
  • findMatchingInvoice($variableSymbol, $amount, $type) - Hledání faktury

Repozitáře (Repositories)​

Bank Repository​

Cesta: backend/Repositories/Bank.php Namespace: Espo\Modules\Banking\Repositories

Databázové operace pro entitu Bank:

  • Custom queries
  • Speciální loadery
  • Optimalizace dotazů

BankAccount Repository​

Cesta: backend/Repositories/BankAccount.php Namespace: Espo\Modules\Banking\Repositories

Databázové operace pro entitu BankAccount:

  • Načítání účtů s credentials
  • Filtrování aktivních účtů
  • Join s bankami

BankTransaction Repository​

Cesta: backend/Repositories/BankTransaction.php Namespace: Espo\Modules\Banking\Repositories

Databázové operace pro entitu BankTransaction:

  • Hledání podle foreign ID
  • Filtrování nepárovaných transakcí
  • Statistiky a agregace

Hooks​

Bank Hooks​

Cesta: backend/Hooks/Bank/

Lifecycle události pro entitu Bank:

  • beforeSave - Validace před uložením
  • afterSave - Akce po uložení
  • beforeRemove - Kontrola před smazáním
  • afterRemove - Cleanup po smazání

BankAccount Hooks​

Cesta: backend/Hooks/BankAccount/

Lifecycle události pro entitu BankAccount:

  • beforeSave - Validace čísla účtu, IBAN
  • afterSave - Aktualizace vazeb
  • beforeRemove - Kontrola transakcí

BankTransaction Hooks​

Cesta: backend/Hooks/BankTransaction/

Lifecycle události pro entitu BankTransaction:

  • afterCreate - Automatické párování s fakturou
  • afterSave - Aktualizace stavu faktury
  • beforeRemove - Odpojení od faktur

Naplánované úlohy (Jobs)​

CleanupCsobExportFiles​

Cesta: backend/Jobs/CleanupCsobExportFiles.php Namespace: Espo\Modules\Banking\Jobs

Účel: Pravidelné čištění dočasných exportních souborů ČSOB

Funkce:

  • Smaže soubory starší než X dní
  • Uvolní diskový prostor
  • Loguje smazané soubory

Konfigurace:

{
  "scheduling": "0 2 * * *",  // Každý den ve 2:00
  "maxAge": 7  // Smazat soubory starší než 7 dní
}

Poznámka: Job lze nakonfigurovat v Administration → Scheduled Jobs

BankTransactionDownload (příklad)​

Tento job není v současnosti v kódu, ale je doporučený pro implementaci

Účel: Pravidelné stahování transakcí z bank

Doporučená funkcionalita:

  • Projít všechny aktivní BankAccount
  • Pro účty s credentials stáhnout nové transakce
  • Aktualizovat zůstatky
  • Odeslat notifikace

API (Custom endpointy)​

EntryPoints​

Cesta: backend/EntryPoints/

Custom vstupní body pro speciální operace:

Export do ČSOB formátu​

  • Exportuje transakce ve formátu požadovaném ČSOB
  • Generuje soubory pro import do bank. systému
  • Podporuje různé formáty (XML, CSV)

Classes (Pomocné třídy)​

EmailParsing​

Cesta: backend/Classes/EmailParsing/

Zpracování e-mailových výpisů:

  • Parsování různých formátů výpisů
  • Extrakce transakcí z e-mailů
  • Podpora pro různé banky

Podporované formáty:

  • Textové výpisy
  • HTML výpisy
  • PDF přílohy (pokud jsou konvertovány)

FieldProcessing​

Cesta: backend/Classes/FieldProcessing/

Zpracování speciálních polí:

  • BankAccountNumberType - Validace a formátování čísla účtu
  • Custom field procesory

Jobs​

Cesta: backend/Classes/Jobs/

Pomocné třídy pro joby:

  • Společná logika pro naplánované úlohy
  • Utility funkce

MassAction​

Cesta: backend/Classes/MassAction/

Hromadné akce:

  • Export více transakcí
  • Hromadné párování s fakturami
  • Hromadná aktualizace

Select​

Cesta: backend/Classes/Select/

Custom select buildery:

  • Optimalizované dotazy
  • Speciální filtry
  • Agregace dat

Core​

Cesta: backend/Core/

Základní funkcionality modulu:

  • Konfigurace
  • Inicializace
  • Dependency injection

Resources​

metadata​

Cesta: backend/Resources/metadata/

Metadata definice:

  • entityDefs/ - Definice entit
  • clientDefs/ - Frontend konfigurace
  • recordDefs/ - Record metadata
  • aclDefs/ - ACL definice
  • selectDefs/ - Select definice

i18n​

Cesta: backend/Resources/i18n/

Překlady:

  • cs_CZ/ - České překlady
  • en_US/ - Anglické překlady
  • de_DE/ - Německé překlady
  • sk_SK/ - Slovenské překlady

layouts​

Cesta: backend/Resources/layouts/

Layout definice pro entity:

  • list.json - Seznam
  • detail.json - Detail
  • detailSmall.json - Malý detail
  • filters.json - Filtry
  • massUpdate.json - Hromadná aktualizace

Doporučené postupy​

Rozšiřování služeb​

namespace Espo\Custom\Modules\Banking\Services;

use Espo\Modules\Banking\Services\BankTransaction as Original;

class BankTransaction extends Original
{
    // Přepsat metodu pro vlastní logiku párování
    public function pairWithInvoice($transactionId)
    {
        // Custom logika
        return parent::pairWithInvoice($transactionId);
    }
}

Přidání custom hooku​

namespace Espo\Custom\Hooks\BankTransaction;

use Espo\Core\Hook\Hook\AfterSave;
use Espo\ORM\Entity;

class CustomHook implements AfterSave
{
    public function afterSave(Entity $entity, array $options): void
    {
        // Custom logika po uložení transakce
    }
}

Vytvoření vlastního jobu​

namespace Espo\Custom\Jobs;

use Espo\Core\Job\Job;

class CustomBankingJob implements Job
{
    public function run(): void
    {
        // Custom logika pro pravidelné spouštění
    }
}

API komunikace s bankami​

Modul podporuje různé bankovní API:

UniCredit API​

  • REST API
  • Autentizace přes OAuth2
  • Podporované operace: načtení transakcí, zůstatku

ČSOB API​

  • SOAP/REST API
  • Certifikátová autentizace
  • Export pro import do banky

Česká spořitelna API​

  • REST API
  • Token autentizace
  • Real-time dotazy

VÚB API​

  • REST API
  • Token autentizace
  • Slovenský standard

Bezpečnost​

Credentials storage​

  • Credentials jsou uloženy jako samostatné entity
  • Citlivá data (hesla, tokeny) jsou šifrována
  • Přístup je řízen ACL

API komunikace​

  • HTTPS only
  • Validace certifikátů
  • Rate limiting
  • Error handling bez odhalení citlivých dat

Audit​

  • Všechny změny na transakcích jsou logovány
  • Historie párování s fakturami
  • Sledování přístupu k bankovním údajům

Testování​

Unit testy​

Cesta: tests/unit/Espo/Modules/Banking/

Testy pro jednotlivé komponenty:

  • Services
  • Repositories
  • Utilities

Integration testy​

Cesta: tests/integration/Espo/Modules/Banking/

Testy integrace:

  • API endpointy
  • Párování transakcí
  • Import z e-mailů

Poznámky​

  • Všechny třídy následují PSR-12 coding standard
  • Dependency injection přes konstruktor
  • Type hints jsou povinné (PHP 8.1+)
  • PHPDoc komentáře pro všechny public metody