@develit-services/ledger 0.3.1 → 0.3.3

package/README.md

@@ -0,0 +1,318 @@
+# Ledger Service
+
+Microsluzba pro spravu ucetnich transakci, uctu a identifikatoru. Postavena na Cloudflare Workers s D1 databazi.
+
+## Obsah
+
+- [Architektura](#architektura)
+- [Zivotni cyklus transakce](#zivotni-cyklus-transakce)
+- [Refund flow](#refund-flow)
+- [Ucty a identifikatory](#ucty-a-identifikatory)
+- [RPC akce](#rpc-akce)
+- [Event system](#event-system)
+- [Databazove schema](#databazove-schema)
+- [Error Codes](#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`:
+
+```typescript
+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
+
+```typescript
+{
+  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 |

package/dist/database/schema.cjs

@@ -1,10 +1,10 @@
 'use strict';
 
-const database_schema = require('../shared/ledger.B2SLAQpo.cjs');
+const database_schema = require('../shared/ledger._WA8Ag9K.cjs');
 require('@develit-io/backend-sdk');
 require('drizzle-orm');
 require('drizzle-orm/sqlite-core');
-require('../shared/ledger.C6xAPWKq.cjs');
+require('../shared/ledger.QNHpaH-m.cjs');
 require('zod');
 require('@develit-io/general-codes');
 

package/dist/database/schema.d.cts

@@ -1,4 +1,4 @@
-export { F as account, G as accountIdentifier, H as accountIdentifierMapping, J as accountIdentifierMappingRelations, K as accountIdentifierRelations, L as accountRelations, M as entry, N as transaction } from '../shared/ledger.Ci2NnLFo.cjs';
+export { G as account, H as accountIdentifier, J as accountIdentifierMapping, K as accountIdentifierMappingRelations, L as accountIdentifierRelations, M as accountRelations, N as entry, O as transaction } from '../shared/ledger.aRF1eJOD.cjs';
 import 'drizzle-orm';
 import 'drizzle-orm/sqlite-core';
 import '@develit-io/backend-sdk';

package/dist/database/schema.d.mts

@@ -1,4 +1,4 @@
-export { F as account, G as accountIdentifier, H as accountIdentifierMapping, J as accountIdentifierMappingRelations, K as accountIdentifierRelations, L as accountRelations, M as entry, N as transaction } from '../shared/ledger.Ci2NnLFo.mjs';
+export { G as account, H as accountIdentifier, J as accountIdentifierMapping, K as accountIdentifierMappingRelations, L as accountIdentifierRelations, M as accountRelations, N as entry, O as transaction } from '../shared/ledger.aRF1eJOD.mjs';
 import 'drizzle-orm';
 import 'drizzle-orm/sqlite-core';
 import '@develit-io/backend-sdk';

package/dist/database/schema.d.ts

@@ -1,4 +1,4 @@
-export { F as account, G as accountIdentifier, H as accountIdentifierMapping, J as accountIdentifierMappingRelations, K as accountIdentifierRelations, L as accountRelations, M as entry, N as transaction } from '../shared/ledger.Ci2NnLFo.js';
+export { G as account, H as accountIdentifier, J as accountIdentifierMapping, K as accountIdentifierMappingRelations, L as accountIdentifierRelations, M as accountRelations, N as entry, O as transaction } from '../shared/ledger.aRF1eJOD.js';
 import 'drizzle-orm';
 import 'drizzle-orm/sqlite-core';
 import '@develit-io/backend-sdk';

package/dist/database/schema.mjs

@@ -1,7 +1,7 @@
-export { a as account, b as accountIdentifier, c as accountIdentifierMapping, d as accountIdentifierMappingRelations, e as accountIdentifierRelations, f as accountRelations, g as entry, t as transaction } from '../shared/ledger.149a0ags.mjs';
+export { a as account, b as accountIdentifier, c as accountIdentifierMapping, d as accountIdentifierMappingRelations, e as accountIdentifierRelations, f as accountRelations, g as entry, t as transaction } from '../shared/ledger.B-gGCFFu.mjs';
 import '@develit-io/backend-sdk';
 import 'drizzle-orm';
 import 'drizzle-orm/sqlite-core';
-import '../shared/ledger.DkcYdsVZ.mjs';
+import '../shared/ledger.DWO4eS7Q.mjs';
 import 'zod';
 import '@develit-io/general-codes';