Přeskočit na hlavní obsah

Bank - Services

Dokumentace business logiky a služeb pro práci s entitou Bank.

Bank Service​

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

Účel​

Bank Service poskytuje business logiku pro:

  • Validaci dat při vytváření/úpravě bank
  • Správu notifikací
  • Zpracování událostí
  • Propojení s účty a transakcemi

Metody​

create()​

Vytvoření nové banky.

Parametry:

  • $data (stdClass) - Data nové banky

Vrací:

  • Entity Bank

Validace:

  • Kontrola povinných polí
  • Validace kódu banky
  • Ověření duplicit

Příklad:

$service = $this->getServiceFactory()->create('Bank');
$bank = $service->create((object)[
    'name' => 'Česká spořitelna, a.s.',
    'code' => '0800',
    'usesApi' => true
]);

update()​

Aktualizace existující banky.

Parametry:

  • $id (string) - ID banky
  • $data (stdClass) - Aktualizovaná data

Vrací:

  • Entity Bank

Validace:

  • Kontrola existence
  • Validace změn
  • Ochrana proti konfliktům

read()​

Načtení detailu banky.

Parametry:

  • $id (string) - ID banky

Vrací:

  • Entity Bank

Načítá:

  • Základní údaje
  • Related entities (podle ACL)
  • Počet účtů a transakcí

delete()​

Smazání banky (soft-delete).

Parametry:

  • $id (string) - ID banky

Kontroly:

  • Zda má banka přiřazené účty
  • Zda má banka transakce
  • ACL oprávnění

Vyvolává:

  • Forbidden - pokud má banka závislosti
  • ForbiddenException - pokud nemá uživatel oprávnění

Notifikační logika​

sendNotification()​

Odeslání notifikace o nové transakci.

Parametry:

  • $bankId (string) - ID banky
  • $transactionId (string) - ID transakce

Proces:

  1. Načte nastavení banky
  2. Kontroluje enableAlertUsers
  3. Získá seznam uživatelů a týmů
  4. Odešle notifikace

Příklad:

$service->sendNotification($bankId, $transactionId);

getNotificationRecipients()​

Získání příjemců notifikací.

Parametry:

  • $bankId (string) - ID banky

Vrací:

  • Array uživatelských ID

Zahrnuje:

  • Uživatele z pole users
  • Členy týmů z notificationTeams
  • Přiřazeného uživatele

Validační metody​

validateBankCode()​

Validace kódu banky.

Parametry:

  • $code (string) - Kód banky

Validuje:

  • Formát kódu (4 číslice)
  • Existence v seznamu známých bank
  • Duplicita

Vrací:

  • bool

checkForDuplicates()​

Kontrola duplicitních bank.

Parametry:

  • $name (string) - Název banky
  • $excludeId (string|null) - ID k vyloučení

Vrací:

  • bool - true pokud existuje duplicita

Statistické metody​

getAccountsCount()​

Počet účtů u banky.

Parametry:

  • $bankId (string) - ID banky

Vrací:

  • int - Počet aktivních účtů

getTransactionsCount()​

Počet transakcí spojených s bankou.

Parametry:

  • $bankId (string) - ID banky
  • $dateFrom (string|null) - Od data
  • $dateTo (string|null) - Do data

Vrací:

  • int - Počet transakcí

getTotalVolume()​

Celkový objem transakcí.

Parametry:

  • $bankId (string) - ID banky
  • $type (string) - 'incoming' nebo 'outgoing'
  • $period (string) - Časové období

Vrací:

  • float - Celkový objem v CZK

Bank Repository​

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

Účel​

Repository poskytuje databázové operace a custom queries.

Metody​

findWithAccounts()​

Načtení bank s počtem účtů.

Vrací:

  • Collection bank s připojeným počtem účtů

SQL Optimization:

  • Left join na BankAccount
  • Group by pro agregaci
  • Eager loading related dat

findActive()​

Banky s aktivními účty.

Vrací:

  • Collection aktivních bank

getByCode()​

Najít banku podle kódu.

Parametry:

  • $code (string) - Kód banky

Vrací:

  • Entity|null

Hooks​

Bank Hooks​

Cesta: backend/Hooks/Bank/

BeforeSave​

Soubor: BeforeSave.php

Akce:

  • Validace kódu banky
  • Trim whitespace
  • Kontrola duplicit

AfterSave​

Soubor: AfterSave.php

Akce:

  • Aktualizace related entities
  • Flush cache
  • Logování změn

BeforeRemove​

Soubor: BeforeRemove.php

Akce:

  • Kontrola závislých účtů
  • Kontrola transakcí
  • Prevent delete pokud má závislosti

AfterRemove​

Soubor: AfterRemove.php

Akce:

  • Cleanup orphaned records
  • Aktualizace statistik

Events​

Podporované události​

bank.created​

Vyvoláno po vytvoření banky.

Payload:

[
    'bankId' => 'xxx',
    'name' => 'Bank Name',
    'userId' => 'yyy'
]

bank.updated​

Vyvoláno po aktualizaci banky.

Payload:

[
    'bankId' => 'xxx',
    'changes' => [...],
    'userId' => 'yyy'
]

bank.deleted​

Vyvoláno po smazání banky.

Payload:

[
    'bankId' => 'xxx',
    'userId' => 'yyy'
]

Integrace​

Email Service​

Pro odesílání notifikací:

$emailService = $this->getServiceFactory()->create('Email');
$emailService->send([
    'to' => $recipients,
    'subject' => 'New Bank Transaction',
    'body' => $body
]);

Notification Service​

Pro in-app notifikace:

$notificationService = $this->getServiceFactory()->create('Notification');
$notificationService->notifyAbout($entity, $userIdList);

Rozšíření​

Custom Service​

Vytvoření vlastní služby:

namespace Espo\Custom\Modules\Banking\Services;

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

class Bank extends Original
{
    public function create($data)
    {
        // Custom pre-processing
        $data = $this->customValidation($data);

        // Volání původní metody
        $bank = parent::create($data);

        // Custom post-processing
        $this->sendWelcomeEmail($bank);

        return $bank;
    }

    protected function customValidation($data)
    {
        // Custom validace
        return $data;
    }

    protected function sendWelcomeEmail($bank)
    {
        // Odeslání welcome e-mailu
    }
}

Custom Hook​

Přidání vlastního hooku:

namespace Espo\Custom\Hooks\Bank;

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

class CustomNotification implements AfterSave
{
    public function afterSave(Entity $entity, array $options): void
    {
        if (!$entity->isNew()) {
            return;
        }

        // Custom notifikační logika
        $this->notifyAdmins($entity);
    }

    private function notifyAdmins(Entity $bank): void
    {
        // Implementace notifikace
    }
}

Testing​

Unit Test Example​

namespace Test\Unit\Espo\Modules\Banking\Services;

use Espo\Modules\Banking\Services\Bank;

class BankTest extends \PHPUnit\Framework\TestCase
{
    private $service;

    protected function setUp(): void
    {
        $this->service = $this->createService();
    }

    public function testCreate(): void
    {
        $data = (object)[
            'name' => 'Test Bank',
            'code' => '9999'
        ];

        $bank = $this->service->create($data);

        $this->assertNotNull($bank->getId());
        $this->assertEquals('Test Bank', $bank->get('name'));
    }

    public function testValidateBankCode(): void
    {
        $this->assertTrue($this->service->validateBankCode('0800'));
        $this->assertFalse($this->service->validateBankCode('invalid'));
    }
}

Best Practices​

  1. Vždy používejte Service layer místo přímého přístupu k repository
  2. Validujte data před uložením do databáze
  3. Logujte důležité operace pro audit trail
  4. Používejte transakce pro komplexní operace
  5. Cachujte často používaná data (seznam bank, kódy)
  6. Handleujte exceptions a poskytujte smysluplné chybové zprávy
  7. Testujte business logiku unit testy

Poznámky​

  • Service je singleton per request
  • Všechny metody respektují ACL
  • Hooks jsou spouštěny v definovaném pořadí
  • Events jsou asynchronní (pokud je enabled message queue)