Přeskočit na hlavní obsah

Frontend - Klientská část

Dokumentace frontendové části modulu Banking - views, handlery, komponenty a uživatelské rozhraní.

Architektura​

Frontend modul Banking je postaven na frameworku EspoCRM a používá:

  • TypeScript/JavaScript - Pro logiku
  • Backbone.js - Model-View architektura
  • Handlebars - Templating engine
  • Bull - Frontend view framework

Struktura​

client/src/
├── handlers/          # Event handlery a custom logika
│   ├── bank-account/
│   └── bank-transaction/
└── views/            # Custom views a komponenty
    ├── bank/
    ├── bank-account/
    │   └── fields/
    │       └── credential.ts
    └── bank-transaction/

Views (Pohledy)​

Bank Views​

BankAccount Fields - Credential​

Soubor: client/src/views/bank-account/fields/credential.ts Typ: Custom field view

Účel: Speciální zobrazení a editace credentials pro bankovní účty

Funkce:

  • Výběr typu credentials (UniCredit, ČSOB, atd.)
  • Dynamické načítání formuláře podle typu banky
  • Validace přihlašovacích údajů
  • Zobrazení stavu připojení k API

Použití:

// Registrace v metadata
{
  "credential": {
    "type": "linkParent",
    "view": "banking:views/bank-account/fields/credential"
  }
}

Vlastnosti:

  • Podporuje všechny typy credentials (UniCredit, ČSOB, Česká spořitelna, VÚB)
  • Real-time validace
  • Indikace aktivního/neaktivního připojení
  • Tooltip s nápovědou

Bank Views​

Cesta: client/src/views/bank/

Custom views pro entitu Bank:

  • Speciální zobrazení kontaktních údajů
  • Správa notifikací
  • Seznam účtů a transakcí

BankAccount Views​

Cesta: client/src/views/bank-account/

Custom views pro entitu BankAccount:

  • Zobrazení zůstatku s formátováním
  • Status indikátor připojení k API
  • Tlačítko pro manuální stažení transakcí

BankTransaction Views​

Cesta: client/src/views/bank-transaction/

Custom views pro entitu BankTransaction:

  • Barevné označení typu (příchozí/odchozí)
  • Indikátor spárování s fakturou
  • Zobrazení detailu protiúčtu

Handlers (Event handlery)​

BankAccount Handlers​

Cesta: client/src/handlers/bank-account/

Event handlery pro BankAccount:

  • Validace formátu čísla účtu
  • Automatické doplnění IBAN
  • Kontrola dostupnosti API

Příklad: Validace čísla účtu​

export default class BankAccountNumberHandler {
    onFieldChange(field: string, value: any) {
        if (field === 'bankAccountNumber') {
            this.validateBankAccountNumber(value);
        }
    }

    validateBankAccountNumber(value: string) {
        // Validační logika
        const pattern = /^\d{6}-\d{10}\/\d{4}$/;
        return pattern.test(value);
    }
}

BankTransaction Handlers​

Cesta: client/src/handlers/bank-transaction/

Event handlery pro BankTransaction:

  • Automatické párování při změně VS
  • Aktualizace statusu faktury
  • Notifikace při nepárované transakci

Příklad: Párování s fakturou​

export default class InvoiceMatchingHandler {
    onFieldChange(field: string, value: any) {
        if (field === 'variableSymbol') {
            this.findMatchingInvoice(value);
        }
    }

    async findMatchingInvoice(vs: string) {
        // Logika hledání faktury
        const invoices = await this.findInvoices(vs);
        if (invoices.length === 1) {
            this.model.set('invoice', invoices[0]);
        }
    }
}

Komponenty​

BankAccountNumber Field​

Speciální field pro zobrazení a editaci čísla bankovního účtu

Features:

  • Formátování: prefix-number/bankCode
  • Validace formátu
  • Automatické doplnění banky podle kódu
  • Tooltip s plným IBAN

Currency Display​

Zobrazení finančních částek s formátováním

Features:

  • Správné zobrazení měny
  • Zaokrouhlení podle nastavení
  • Barevné označení (příjem zelená, výdaj červená)
  • Převod měn

Dynamic Logic​

BankAccount Dynamic Logic​

{
  "fields": {
    "iban": {
      "visible": {
        "conditionGroup": [
          {
            "type": "equals",
            "attribute": "type",
            "value": "foreign"
          }
        ]
      }
    },
    "swift": {
      "visible": {
        "conditionGroup": [
          {
            "type": "equals",
            "attribute": "type",
            "value": "foreign"
          }
        ]
      }
    }
  }
}

Logika:

  • IBAN a SWIFT se zobrazí pouze pro zahraniční účty
  • Credential field se aktivuje, když je vybrána banka s API

BankTransaction Dynamic Logic​

{
  "fields": {
    "cardNumber": {
      "visible": {
        "conditionGroup": [
          {
            "type": "equals",
            "attribute": "transactionType",
            "value": "Card"
          }
        ]
      }
    },
    "cardHolder": {
      "visible": {
        "conditionGroup": [
          {
            "type": "equals",
            "attribute": "transactionType",
            "value": "Card"
          }
        ]
      }
    }
  }
}

Logika:

  • Pole pro karty se zobrazí pouze pro kartové transakce
  • Pole pro faktury se zobrazí podle typu transakce (příchozí/odchozí)

Action Buttons​

BankAccount Actions​

Download Transactions​

Label: "Stáhnout transakce" Action: Manuální stažení transakcí z API

actionDownloadTransactions() {
    this.ajaxPostRequest(`BankAccount/action/downloadTransactions`, {
        id: this.model.id
    }).then(() => {
        Espo.Ui.success(this.translate('Downloaded', 'labels', 'Banking'));
        this.model.fetch();
    });
}

Test Connection​

Label: "Test připojení" Action: Otestování připojení k bankovnímu API

actionTestConnection() {
    this.ajaxPostRequest(`BankAccount/action/testConnection`, {
        id: this.model.id
    }).then((result) => {
        if (result.success) {
            Espo.Ui.success('Connection successful');
        } else {
            Espo.Ui.error('Connection failed: ' + result.message);
        }
    });
}

BankTransaction Actions​

Pair with Invoice​

Label: "Spárovat s fakturou" Action: Manuální spárování s fakturou

actionPairWithInvoice() {
    this.createView('dialog', 'banking:views/modals/select-invoice', {
        scope: 'Invoice',
        filters: {
            variableSymbol: this.model.get('variableSymbol')
        }
    }, (view) => {
        view.render();
    });
}

List Views​

Bank List​

  • Zobrazení názvu, kódu a API statusu
  • Filtr podle API podpory
  • Rychlé akce: Editace, Smazání

BankAccount List​

  • Zobrazení čísla účtu, banky a zůstatku
  • Filtr podle typu (domácí/zahraniční)
  • Filtr podle aktivního stavu
  • Barevné označení neaktivních účtů
  • Rychlé akce: Stáhnout transakce, Editace

BankTransaction List​

  • Zobrazení data, typu, částky a protiúčtu
  • Filtr podle typu (příchozí/odchozí)
  • Filtr podle spárování s fakturou
  • Filtr "Faktura nenalezena"
  • Barevné označení:
    • Zelená: Příchozí
    • Červená: Odchozí
    • Oranžová: Nepárováno
  • Rychlé akce: Spárovat s fakturou, Detail

Detail Views​

Bank Detail​

Panels:

  • Přehled - Základní informace, kontakty
  • Notifikace - Nastavení upozornění
  • Adresy - Fakturační a doručovací adresa
  • Bankovní účty - Panel se seznamem účtů
  • Aktivity - CRM aktivity

BankAccount Detail​

Panels:

  • Přehled - Číslo účtu, IBAN, typ, zůstatek
  • API přístup - Credentials, status připojení
  • Banka - Detail banky
  • Transakce - Panel se seznamem transakcí
  • Historie - Změny a aktualizace

Special Features:

  • Real-time aktualizace zůstatku
  • Indikátor poslední synchronizace
  • Graf vývoje zůstatku (pokud je aktivní)

BankTransaction Detail​

Panels:

  • Přehled - Částka, datum, typ, účet
  • Protiúčet - Detail protistrany
  • Symboly - VS, KS, SS
  • Faktury - Propojené faktury
  • Karta - Detail karty (pokud je kartová transakce)
  • Zdrojový e-mail - Pokud importováno z mailu

Special Features:

  • Barevné označení typu
  • Status indikátor párování
  • Link na fakturu
  • Historie změn

Modals (Dialogy)​

Select Invoice Modal​

Dialog pro výběr faktury k transakci

Features:

  • Filtrování podle VS
  • Zobrazení částky a splatnosti
  • Preview faktury
  • Možnost odpojit stávající fakturu

Credential Setup Modal​

Dialog pro nastavení credentials

Features:

  • Formulář podle typu banky
  • Validace přihlašovacích údajů
  • Test připojení
  • Nápověda a dokumentace

Notifications​

Toast Notifikace​

Success​

Espo.Ui.success(this.translate('transactionDownloaded', 'messages', 'Banking'));

Error​

Espo.Ui.error(this.translate('downloadFailed', 'messages', 'Banking'));

Warning​

Espo.Ui.warning(this.translate('invoiceNotFound', 'messages', 'Banking'));

Desktop Notifikace​

Pokud je povoleno v nastavení, zobrazí se desktop notifikace při:

  • Nové transakci
  • Spárování s fakturou
  • Chybě stahování

Rozšiřitelnost​

Custom Field View​

import BaseFieldView from 'views/fields/base';

export default class CustomBankingField extends BaseFieldView {
    setup() {
        super.setup();
        // Custom setup
    }

    afterRender() {
        super.afterRender();
        // Custom rendering
    }
}

Custom Handler​

export default class CustomHandler {
    constructor(view) {
        this.view = view;
    }

    onFieldChange(field, value) {
        // Custom logic
    }
}

Rozšíření existující view​

import Original from 'banking:views/bank-account/detail';

export default class Extended extends Original {
    setup() {
        super.setup();
        // Přidat vlastní logiku
    }
}

Styling​

CSS Classes​

Bank Transaction Types​

.badge-incoming {
    background-color: #28a745;
}

.badge-outgoing {
    background-color: #dc3545;
}

.badge-unpaired {
    background-color: #fd7e14;
}

Bank Account Status​

.bank-account-active {
    color: #28a745;
}

.bank-account-inactive {
    color: #6c757d;
}

Performance​

Optimalizace​

  • Lazy loading pro velké seznamy transakcí
  • Debounce pro validaci polí
  • Cache pro často používané entity
  • Batch loading pro related records

Best Practices​

  • Používejte noLoad: true pro large collections
  • Implementujte pagination pro seznamy
  • Cache API responses kde je to možné
  • Minimize re-renders

Testování​

Unit testy​

describe('BankAccountNumberField', () => {
    it('should validate correct format', () => {
        const field = new BankAccountNumberField();
        expect(field.validate('123456-1234567890/0800')).toBe(true);
    });
});

Integration testy​

describe('Invoice Pairing', () => {
    it('should pair transaction with invoice', async () => {
        // Test logika
    });
});

Poznámky​

  • Všechny custom views by měly extendovat příslušné base views
  • Type annotations jsou důležité pro TypeScript files
  • Používejte translation keys místo hardcoded textů
  • Event handlers by měly být debounced pro performance