Ledger Service

Microsluzba pro spravu ucetnich transakci, uctu a identifikatoru. Postavena na Cloudflare Workers s D1 databazi.

Obsah

• Architektura
• Zivotni cyklus transakce
• Refund flow
• Ucty a identifikatory
• RPC akce
• Event system
• Databazove schema
• Error Codes

Architektura

Sluzba se sklada z:

• Akce (Actions) - RPC endpointy pro spravu transakci, uctu a identifikatoru
• Database commands - Atomicke zapisy (INSERT, UPDATE, DELETE) s podporou batchovani
• Database queries - Cteni dat s paginaci, filtrovanim a razenim

Bindings:

• LEDGER_D1 - Cloudflare D1 databaze
• QUEUE_BUS_QUEUE - Event bus pro ledger eventy
• PAYMENTS_READY_TO_BATCH_QUEUE - Fronta pro platby k batchovani
• NOTIFICATIONS_QUEUE - Fronta pro notifikace
• SECRETS_STORE - Service binding na secrets store

Zivotni cyklus transakce

Hlavni flow

WAITING_FOR_PAYMENT ──► MATCHED     (banka potvrdila platbu, VS match)
WAITING_FOR_PAYMENT ──► FAILED      (platba selhala)
WAITING_FOR_PAYMENT ──► CANCELLED   (zrusena manualne)

Pokud platba neni sparovana, vytvori se UNMATCHED transakce:

WAITING_FOR_MANUAL_PROCESSING ──► RETURNING ──► RETURNED   (refund flow)
WAITING_FOR_MANUAL_PROCESSING ──► CANCELLED                (manualni zruseni)

Stavy transakce

| Status | Popis | |--------|-------| | WAITING_FOR_PAYMENT | Ceka na bankovni platbu | | WAITING_FOR_MANUAL_PROCESSING | Vyzaduje manualni zpracovani | | MATCHED | Sparovana s platbou | | RETURNING | Probiha refund | | RETURNED | Refund dokoncen | | FAILED | Selhala | | CANCELLED | Zrusena | | SETTLED | Finalne vyporadana (zatim nepouzivano) |

Typy transakci

| Typ | Popis | |-----|-------| | CLIENT_FUND_IN | Prichozi platba od klienta | | CLIENT_FUND_OUT | Odchozi platba klientovi | | PROVIDER_FUND_IN | Prichozi platba od providera | | PROVIDER_FUND_OUT | Odchozi platba providerovi | | COLLATERAL_FUND_IN | Prichozi kolateralni platba | | COLLATERAL_FUND_OUT | Odchozi kolateralni platba | | EXCHANGE | Smena (budouci) | | UNMATCHED | Nesparovana platba | | ADJUSTMENT | Manualni korekce (budouci) | | TRANSFER | Interni prevod mezi ucty | | REFUND | Vraceni platby |

Reference typy

Vazba transakce na business kontext:

| Typ | Popis | |-----|-------| | PAYMENT | Bankovni platba | | EXCHANGE | Smena | | ORDER | Objednavka | | INTERNAL-TRANSFER | Interni prevod | | FORWARD | Forward kontrakt | | TRANSACTION | Jina ledger transakce (pouziva se u refundu) |

Refund flow

Refund je atomicka operace na urovni ledger service - gateway vola jedinou metodu refundTransaction().

┌─────────────────────────────────────────────────────────┐
│ 1. refundTransaction({ transactionId, amount?, reason })│
│    - Validace statusu, castky, payment metadat          │
│    - Atomicky batch:                                    │
│      a) INSERT nova REFUND transakce                    │
│         (obraceny debtor/creditor, VS zachovan)         │
│      b) UPDATE original na RETURNING                    │
│    - Emit: LEDGER_TRANSACTION created + refunding       │
└──────────────────────────┬──────────────────────────────┘
                           ▼
┌─────────────────────────────────────────────────────────┐
│ 2. Queue Bus reaguje na REFUND TX (created)             │
│    → vytvori odchozi platbu v bance                     │
└──────────────────────────┬──────────────────────────────┘
                           │  banka provede platbu
                           ▼
┌─────────────────────────────────────────────────────────┐
│ 3. Sync flow nacte completed platbu z banky             │
│    → emituje BANK_PAYMENT event do busu                 │
│    → Bus sparuje platbu s REFUND TX (VS + IBAN match)   │
│    → Bus vola ledger matchTransaction() na REFUND TX    │
│    → Emit: LEDGER_TRANSACTION matched                   │
└──────────────────────────┬──────────────────────────────┘
                           ▼
┌─────────────────────────────────────────────────────────┐
│ 4. Queue Bus reaguje na matched REFUND TX               │
│    → oznaci original TX jako RETURNED                   │
└─────────────────────────────────────────────────────────┘

Refundovatelne statusy: WAITING_FOR_MANUAL_PROCESSING.

Podporuje partial refund (castka < original). Metadata obsahuje refund.isPartialRefund boolean.

Ucty a identifikatory

Pozn.: ⚠️ Ucty, identifikatory ani entries se zatim v produkcnim kodu nepouzivaji. Schema a akce existuji, ale zadna jina sluzba je aktualne nevola. ⚠️

Hierarchicky system uctu s vice identifikatory (IBAN, cislo uctu, crypto adresa).

Typy uctu

| Typ | Popis | |-----|-------| | INTERNAL | Interni ucet spravovany v systemu | | EXTERNAL | Externi klientsky ucet | | NOSTRO | Mirror ucet u treti strany (napr. Creditas) | | TECHNICAL | Systemovy ucet (AML, poplatky) | | SETTLEMENT | Ucet pro settlement obchodu | | FX | Ucet pro menovou konverzi | | FEE | Ucet pro sber poplatku | | REVENUE | Ucet pro prijem (z poplatku, FX) | | LOSS | Ztratovy ucet (FX spread, refundy) | | TRANSPORT | Docasne parkovani prostredku "in transit" | | HOLD | Blokovane prostredky (AML hold, pending settlement) | | SYSTEM | Interni systemovy ucet | | TEST | Sandbox / testovaci ucty |

Typy aktiv

• FIAT - CZK, EUR, USD...
• CRYPTO - BTC, ETH, USDT...
• TOKEN - Tokenizovana aktiva
• STOCK - Cenné papiry
• COMMODITY - Fyzicka aktiva (zlato, stribro)
• OTHER - Specificke pripady

Identifikatory uctu

| Typ | Pole | |-----|------| | IBAN | iban, swift | | LOCAL_CZ | accountNumber, bankCode, prefix | | SWIFT | swift | | CRYPTO_ADDRESS | cryptoAddress, network |

Ucet muze mit vice identifikatoru (M:N vazba pres accountIdentifierMapping).

RPC akce

Ledger service je RPC worker - nema vlastni verejne HTTP endpointy. Vsechny akce jsou dostupne pouze pres Cloudflare Worker binding.

Transakce

| Akce | Popis | |------|-------| | create-transaction | Vytvori novou transakci (idempotence pres correlationId) | | get-transaction-by-id | Detail transakce | | get-transactions-by-reference-id | Transakce podle referenceType + referenceId | | get-transactions | Seznam transakci s paginaci, filtry a razenim | | update-transaction-status | Aktualizace statusu transakce | | match-transaction | Oznaci transakci jako MATCHED (sparovana s platbou) | | fail-transaction | Oznaci transakci jako FAILED | | cancel-transaction | Oznaci transakci jako CANCELLED | | refund-transaction | Vytvori REFUND transakci a oznaci original jako RETURNING (atomicky batch) | | update-transaction-confirmation-sent-at | Zaznam odeslani potvrzeni |

Filtry transakci

| Filtr | Popis | |-------|-------| | filterTransactionCorrelationId | Podle correlation ID | | filterTransactionReferenceType | Podle typu reference | | filterTransactionReferenceId | Podle ID reference | | filterTransactionType | Podle typu transakce | | filterTransactionDateFrom | Od data | | filterTransactionDateTo | Do data | | filterTransactionDescription | Fulltextove hledani v popisu | | filterTransactionCompletedAt | Podle data dokonceni | | filterTransactionStatus | Podle statusu |

Ucty

| Akce | Popis | |------|-------| | create-account | Vytvori ucet (volitelne s identifikatorem) | | get-account | Detail uctu vcetne identifikatoru | | get-accounts-by-owner | Ucty podle vlastnika | | list-accounts | Seznam uctu s filtry (owner, typ, asset, mena, parent) | | update-account | Aktualizace uctu | | delete-account | Smazani uctu a vazeb na identifikatory (batch) | | get-account-balance | Zustatek uctu |

Identifikatory uctu

| Akce | Popis | |------|-------| | get-account-identifier | Detail identifikatoru | | list-account-identifiers | Identifikatory pro ucet | | find-account-by-identifier | Hledani uctu podle IBAN/cisla uctu/crypto adresy |

Event system

Sluzba emituje LedgerTransactionEvent do QUEUE_BUS_QUEUE:

type LedgerTransactionEvent = BaseEvent & {
  eventType: 'LEDGER_TRANSACTION'
  eventSignal: 'created' | 'updated' | 'matched' | 'failed' | 'refunding'
  ledgerTransaction: TransactionSelectType
}

| Signal | Kdy se emituje | |--------|---------------| | created | Nova transakce vytvorena | | updated | Status transakce zmenen | | matched | Transakce sparovana s platbou | | failed | Transakce selhala | | refunding | Original TX oznacen jako RETURNING (refund zahajen) |

Databazove schema

transaction

Hlavni tabulka ucetnich transakci.

Klicove sloupce: correlationId, referenceType, referenceId, type, status, statusReason, description, value (real), currency, paymentId, metadata (JSON - TransactionMetadata), completedAt, confirmationSentAt.

Transaction metadata

{
  payment?: {
    vs?, ss?, ks?            // platebni symboly
    message?                 // zprava pro prijemce
    type: PaymentType        // DOMESTIC | SEPA | SWIFT | UNKNOWN
    paymentChargeType?       // SHA | OUR | BEN
    expressPayment?          // boolean
    reference?               // dalsi reference
    creditor?                // BankAccountMetadata (prijemce)
    debtor?                  // BankAccountMetadata (platce)
    executionDate?           // ISO 8601
    currency?                // CurrencyCode
    amount?                  // castka
    purpose?                 // ucel platby
    sendAsSinglePayment?     // odeslat jako samostatnou platbu (ne v batchi)
  }
  tags?: string[]            // kategorizace
  note?: string              // poznamka
  refund?: {                 // jen pro typ REFUND
    isPartialRefund: boolean
  }
}

account

Ucty s hierarchickou strukturou.

Klicove sloupce: name, ownerId, accountType, assetType, currency, balanceStrategy (SNAPSHOT | COMPUTED), parentAccountId, closedAt.

accountIdentifier

Identifikatory uctu (IBAN, cislo uctu, crypto adresa).

Klicove sloupce: kind, iban, accountNumber, bankCode, prefix, swift, cryptoAddress, holderName, network, countryCode, label.

accountIdentifierMapping

Vazebni tabulka M:N mezi account a accountIdentifier.

Sloupce: accountId (FK), identifierId (FK).

entry (planovano)

Tabulka pro budouci entry-based ucetnictvi (double-entry bookkeeping). Schema existuje, ale neni zatim pouzivano.

Sloupce: accountId, currency, creditAmount, debitAmount, correlationId, transactionId, status (PENDING | REALIZED | FAILED | CANCELED), isBalanced, metadata (JSON), timestamp.

Error Codes

Format: {CATEGORY}-L-{NUMBER}

| Code | Status | Description | |------|--------|-------------| | DB-L-01 | 500 | Failed to create transaction | | DB-L-02 | 500 | Failed to process refund transaction (batch write) | | DB-L-03 | 404 | Transaction not found (refund) | | VALID-L-01 | 400 | Transaction status does not allow refund | | VALID-L-02 | 400 | Invalid refund amount (zero or negative) | | VALID-L-03 | 400 | Refund amount exceeds original transaction value | | VALID-L-04 | 400 | Transaction missing payment metadata (debtor/creditor) | | VALID-L-05 | 400 | Transaction missing currency information |