Case: deposit, withdraw ve exchange servisini baştan kurmak

0.1 + 0.2                 -> 0.30000000000000004
10 kez 0.1 toplamı         -> 0.9999999999999999
new BigDecimal(0.1)       -> 0.1000000000000000055511151231257827...
BigDecimal.valueOf(0.1)   -> 0.1
new BigDecimal("1.0").equals(new BigDecimal("1.00"))     -> false
new BigDecimal("1.0").compareTo(new BigDecimal("1.00"))  -> 0
new BigDecimal("10").divide(new BigDecimal("3"))         -> ArithmeticException

public record Money(BigDecimal amount, Currency currency) {

    public Money {
        Objects.requireNonNull(amount, "amount");
        Objects.requireNonNull(currency, "currency");
        int scale = currency.getDefaultFractionDigits();          // TRY/USD 2, JPY 0, KWD 3
        if (amount.stripTrailingZeros().scale() > scale) {
            throw new InvalidAmountException(
                    "%s en fazla %d ondalık basamak alır: %s".formatted(currency, scale, amount));
        }
        amount = amount.setScale(scale, RoundingMode.UNNECESSARY); // 10 -> 10.00; değer kaybı yoksa
    }

    public static Money of(String amount, String currencyCode) {
        return new Money(new BigDecimal(amount), Currency.getInstance(currencyCode));
    }

    public boolean isPositive() {
        return amount.signum() > 0;
    }

    public Money plus(Money other) {
        requireSameCurrency(other);
        return new Money(amount.add(other.amount), currency);
    }

    public Money minus(Money other) {
        requireSameCurrency(other);
        return new Money(amount.subtract(other.amount), currency);
    }

    public boolean isLessThan(Money other) {
        requireSameCurrency(other);
        return amount.compareTo(other.amount) < 0;               // equals değil: 1.0 ve 1.00 farklı scale
    }

    private void requireSameCurrency(Money other) {
        if (!currency.equals(other.currency)) {
            throw new CurrencyMismatchException(currency, other.currency);
        }
    }
}

public final class FxConversion {

    private FxConversion() {
    }

    /** rate: 1 birim kaynak para = rate birim hedef para. */
    public static Money convert(Money source, Currency target, BigDecimal rate) {
        if (rate.signum() <= 0) {
            throw new InvalidAmountException("Kur pozitif olmalı: " + rate);
        }
        BigDecimal exact = source.amount().multiply(rate);        // çarpma kesindir, yuvarlama yok
        BigDecimal rounded = exact.setScale(target.getDefaultFractionDigits(), RoundingMode.HALF_EVEN);
        return new Money(rounded, target);                        // tek yuvarlama noktası burası
    }
}

Varsayımlar
- Müşterinin her para birimi için ayrı hesabı var; overdraft yok (balance >= 0).
- Exchange: kuru 3rd party verir, çevrimi biz kendi defterimizde yaparız. Kur 30 sn geçerli.
- 1M istek/gün; yaklaşık yarısı okuma (bakiye, hareketler).
- Güçlü tutarlılık: başarılı çekimden sonra bakiye hemen doğru görünür.
- Her hareket değişmez kayıt; düzeltme ters kayıtla.
- Kimlik doğrulama gateway'de; servis customerId'yi token'dan alır.

1.000.000 istek / 86.400 sn          ≈ 11,6 istek/sn (ortalama)
Gün içi dağılım (trafik ~8-10 saate yığılır) ≈ 2-3x
Maaş günü, kampanya, kur dalgalanması      ≈ 10x tepe
Tasarım hedefi                            ≈ 100-200 istek/sn

Okuma ~%50  -> tepe ~100 okuma/sn (tek satırlık PK ve index sorguları)
Yazma ~%50  -> tepe ~100 yazma/sn; exchange quote'ları ayrıca 3rd party'ye gider

flowchart LR
    C[Mobil / Web] -->|HTTPS + JWT| GW[API Gateway]
    GW --> APP
    subgraph APP[account-service: tek deploy, 2-3 pod]
        API[REST controller'lar<br/>Idempotency-Key, ProblemDetail]
        ACC[account modülü]
        LED[ledger modülü]
        EXC[exchange modülü]
        FXC[fx-client modülü<br/>timeout, retry, CB]
        API --> ACC
        API --> EXC
        ACC --> LED
        EXC --> ACC
        EXC --> LED
        EXC --> FXC
    end
    APP -->|tek transaction| DB[(PostgreSQL 16<br/>tek primary + standby)]
    FXC -->|GET /v1/rates| FX[3rd party kur sağlayıcısı]

CREATE TABLE accounts (
    id           BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    customer_id  BIGINT        NOT NULL,
    currency     CHAR(3)       NOT NULL,
    balance      NUMERIC(19,4) NOT NULL DEFAULT 0,
    status       VARCHAR(16)   NOT NULL DEFAULT 'ACTIVE',
    version      BIGINT        NOT NULL DEFAULT 0,
    created_at   TIMESTAMPTZ   NOT NULL DEFAULT now(),
    updated_at   TIMESTAMPTZ   NOT NULL DEFAULT now(),
    CONSTRAINT accounts_balance_non_negative CHECK (balance >= 0),
    CONSTRAINT accounts_status_valid CHECK (status IN ('ACTIVE', 'BLOCKED', 'CLOSED')),
    CONSTRAINT accounts_customer_currency_uq UNIQUE (customer_id, currency)
);

CREATE TABLE exchange_quotes (
    id                 UUID          PRIMARY KEY,
    customer_id        BIGINT        NOT NULL,
    source_account_id  BIGINT        NOT NULL REFERENCES accounts (id),
    target_account_id  BIGINT        NOT NULL REFERENCES accounts (id),
    source_amount      NUMERIC(19,4) NOT NULL CHECK (source_amount > 0),
    target_amount      NUMERIC(19,4) NOT NULL CHECK (target_amount > 0),
    rate               NUMERIC(19,8) NOT NULL CHECK (rate > 0),
    provider_ref       VARCHAR(64)   NOT NULL,
    status             VARCHAR(16)   NOT NULL DEFAULT 'ACTIVE',
    expires_at         TIMESTAMPTZ   NOT NULL,
    created_at         TIMESTAMPTZ   NOT NULL DEFAULT now(),
    CONSTRAINT quotes_status_valid CHECK (status IN ('ACTIVE', 'USED')),
    CONSTRAINT quotes_accounts_differ CHECK (source_account_id <> target_account_id)
);

CREATE TABLE transactions (
    id               UUID          PRIMARY KEY,
    customer_id      BIGINT        NOT NULL,
    idempotency_key  VARCHAR(255)  NOT NULL,
    request_hash     CHAR(64)      NOT NULL,     -- SHA-256(kanonik istek)
    type             VARCHAR(16)   NOT NULL,
    status           VARCHAR(16)   NOT NULL,
    account_id       BIGINT        NOT NULL REFERENCES accounts (id),
    amount           NUMERIC(19,4) NOT NULL CHECK (amount > 0),
    currency         CHAR(3)       NOT NULL,
    quote_id         UUID          REFERENCES exchange_quotes (id),
    created_at       TIMESTAMPTZ   NOT NULL DEFAULT now(),
    updated_at       TIMESTAMPTZ   NOT NULL DEFAULT now(),
    CONSTRAINT transactions_type_valid CHECK (type IN ('DEPOSIT', 'WITHDRAWAL', 'EXCHANGE')),
    CONSTRAINT transactions_status_valid CHECK (status IN ('PENDING', 'COMPLETED', 'FAILED')),
    CONSTRAINT transactions_idem_uq UNIQUE (customer_id, idempotency_key),
    CONSTRAINT transactions_quote_uq UNIQUE (quote_id)          -- bir quote tek bir işleme
);

CREATE TABLE ledger_entries (
    id              BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    transaction_id  UUID          NOT NULL REFERENCES transactions (id),
    account_id      BIGINT        NOT NULL REFERENCES accounts (id),
    amount          NUMERIC(19,4) NOT NULL CHECK (amount <> 0),   -- işaretli: çekim negatif
    currency        CHAR(3)       NOT NULL,
    balance_after   NUMERIC(19,4) NOT NULL CHECK (balance_after >= 0),
    created_at      TIMESTAMPTZ   NOT NULL DEFAULT now()
);

CREATE INDEX ledger_entries_account_idx ON ledger_entries (account_id, id);
CREATE INDEX ledger_entries_transaction_idx ON ledger_entries (transaction_id);
CREATE INDEX transactions_pending_idx ON transactions (updated_at) WHERE status = 'PENDING';

CREATE FUNCTION reject_ledger_change() RETURNS trigger AS $$
BEGIN
    RAISE EXCEPTION 'ledger_entries is append-only';
END;
$$ LANGUAGE plpgsql;

CREATE TRIGGER ledger_entries_append_only
    BEFORE UPDATE OR DELETE ON ledger_entries
    FOR EACH ROW EXECUTE FUNCTION reject_ledger_change();

-- 1) Bakiye = hareketlerin toplamı mı?
SELECT a.id, a.balance, COALESCE(SUM(l.amount), 0) AS ledger_balance
  FROM accounts a
  LEFT JOIN ledger_entries l ON l.account_id = a.id
 GROUP BY a.id, a.balance
HAVING a.balance <> COALESCE(SUM(l.amount), 0);

-- 2) Her tamamlanmış işlemin hareket sayısı tipine uygun mu?
SELECT t.id, t.type, t.status, count(l.id) AS entries
  FROM transactions t
  LEFT JOIN ledger_entries l ON l.transaction_id = t.id
 WHERE t.status = 'COMPLETED'
 GROUP BY t.id, t.type, t.status
HAVING count(l.id) <> CASE t.type WHEN 'EXCHANGE' THEN 2 ELSE 1 END;

@Transactional
public void withdraw(long accountId, BigDecimal amount) {
    Account account = accountRepository.findById(accountId).orElseThrow();   // SELECT
    if (account.getBalance().compareTo(amount) < 0) {
        throw new InsufficientFundsException(...);
    }
    account.setBalance(account.getBalance().subtract(amount));               // commit'te UPDATE
}

naive (oku-kontrol et-yaz):  100 çekimin 100'ü başarılı, ledger toplamı -1.000 TL, bakiye 480 TL
koşullu UPDATE:               50 başarılı, 50 reddedildi, ledger toplamı -500 TL, bakiye 0 TL

UPDATE accounts
   SET balance = balance - :amount, version = version + 1, updated_at = now()
 WHERE id = :id AND customer_id = :customerId AND currency = :currency
   AND status = 'ACTIVE' AND balance >= :amount
RETURNING balance;

BEGIN;
SELECT id, customer_id, currency, balance, status
  FROM accounts
 WHERE id = :id
   FOR UPDATE;
-- Java'da domain kuralları, sonra:
UPDATE accounts SET balance = :newBalance, version = version + 1 WHERE id = :id;
COMMIT;

ERROR:  deadlock detected
DETAIL:  Process 624 waits for ShareLock on transaction 766; blocked by process 626.
         Process 626 waits for ShareLock on transaction 765; blocked by process 624.

SELECT id, customer_id, currency, balance, status
  FROM accounts
 WHERE id IN (:first, :second) AND customer_id = :customerId
 ORDER BY id
   FOR UPDATE;

UPDATE accounts SET balance = :newBalance, version = version + 1
 WHERE id = :id AND version = :expectedVersion;

@Transactional
public synchronized void withdraw(long accountId, BigDecimal amount) { ... }   // YANLIŞ

BEGIN;
-- 1) Anahtarı sahiplen. Aynı anahtar varsa 0 satır.
INSERT INTO transactions (id, customer_id, idempotency_key, request_hash, type, status,
                          account_id, amount, currency)
VALUES (:txId, :customerId, :key, :hash, 'WITHDRAWAL', 'COMPLETED', :accountId, :amount, :currency)
ON CONFLICT (customer_id, idempotency_key) DO NOTHING;
-- 2) 1 satır eklendiyse: koşullu UPDATE + ledger insert. 0 ise: kayıtlı sonucu oku ve dön.
COMMIT;

sequenceDiagram
    participant M as Mobil
    participant S as account-service
    participant FX as Kur sağlayıcısı
    participant DB as PostgreSQL
    M->>S: POST /exchange-quotes {targetAccountId, 340 TRY}
    S->>DB: Hesapları oku (sahiplik, para birimi)
    S->>FX: GET /v1/rates?from=TRY&to=USD (timeout 1 sn)
    FX-->>S: rate 0.0291, providerRef
    S->>DB: INSERT exchange_quotes (expires_at = now() + 30 sn)
    S-->>M: 201 {quoteId, 9.89 USD, expiresAt}
    M->>S: POST /exchanges {quoteId} + Idempotency-Key
    S->>DB: BEGIN
    S->>DB: INSERT transactions ON CONFLICT DO NOTHING
    S->>DB: UPDATE exchange_quotes SET status='USED' WHERE status='ACTIVE' AND expires_at > now()
    S->>DB: SELECT ... WHERE id IN (TRY, USD) ORDER BY id FOR NO KEY UPDATE
    S->>DB: UPDATE iki bakiye + INSERT iki ledger kaydı
    S->>DB: COMMIT
    S-->>M: 201 {transactionId, balanceAfter}

@Transactional
public Outcome exchange(...) {
    accounts.lockInIdOrder(...);              // satır kilitleri ve bir DB bağlantısı alındı
    FxRate rate = fxRateClient.rate(...);      // YANLIŞ: 1 sn'lik read timeout boyunca ikisi de tutulur
    ...
}

stateDiagram-v2
    [*] --> PENDING: Tx1 - TRY düşülür (ledger -340), transactions PENDING
    PENDING --> COMPLETED: Sağlayıcı "gerçekleşti" / Tx2 - USD eklenir (ledger +9.89)
    PENDING --> FAILED: Sağlayıcı kesin red / Tx2 - TRY iade edilir (ledger +340)
    PENDING --> PENDING: Timeout veya 5xx / aynı referansla tekrar sor
    note right of PENDING: N dakika belirsiz kalırsa alarm ve mutabakat
    COMPLETED --> [*]
    FAILED --> [*]

UPDATE transactions
   SET updated_at = now()                       -- 30 sn'lik kira (lease)
 WHERE id IN (SELECT id FROM transactions
               WHERE status = 'PENDING' AND updated_at < now() - interval '30 seconds'
               ORDER BY updated_at
               LIMIT 50
                 FOR UPDATE SKIP LOCKED)
RETURNING id;

public abstract sealed class DomainException extends RuntimeException
        permits AccountNotFoundException, QuoteNotFoundException,
                InsufficientFundsException, AccountNotActiveException, CurrencyMismatchException,
                InvalidAmountException, IdempotencyKeyReusedException,
                QuoteNotUsableException, ConcurrentUpdateException {

    private final String code;

    protected DomainException(String code, String message) {
        super(message);
        this.code = code;
    }

    public String code() {
        return code;
    }
}

public record AccountRow(long id, long customerId, String currency, BigDecimal balance, String status) {

    public Account toDomain() {
        return new Account(id, customerId,
                new Money(balance, Currency.getInstance(currency)),
                Account.Status.valueOf(status));
    }
}

@Repository
public class AccountRepository {

    private final JdbcClient jdbc;

    public AccountRepository(JdbcClient jdbc) {
        this.jdbc = jdbc;
    }

    public Optional<AccountRow> findOwned(long id, long customerId) {
        return jdbc.sql("""
                SELECT id, customer_id, currency, balance, status
                  FROM accounts
                 WHERE id = :id AND customer_id = :customerId
                """)
                .param("id", id)
                .param("customerId", customerId)
                .query(AccountRow.class)
                .optional();
    }

    /** Kontrol ve düşüm tek ifadede. Boş dönerse hiçbir satır değişmemiştir. */
    public Optional<BigDecimal> debitIfSufficient(long id, long customerId, Money amount) {
        return jdbc.sql("""
                UPDATE accounts
                   SET balance = balance - :amount, version = version + 1, updated_at = now()
                 WHERE id = :id AND customer_id = :customerId AND currency = :currency
                   AND status = 'ACTIVE' AND balance >= :amount
                RETURNING balance
                """)
                .param("amount", amount.amount())
                .param("id", id)
                .param("customerId", customerId)
                .param("currency", amount.currency().getCurrencyCode())
                .query(BigDecimal.class)
                .optional();
    }

    public Optional<BigDecimal> credit(long id, long customerId, Money amount) {
        return jdbc.sql("""
                UPDATE accounts
                   SET balance = balance + :amount, version = version + 1, updated_at = now()
                 WHERE id = :id AND customer_id = :customerId AND currency = :currency
                   AND status = 'ACTIVE'
                RETURNING balance
                """)
                .param("amount", amount.amount())
                .param("id", id)
                .param("customerId", customerId)
                .param("currency", amount.currency().getCurrencyCode())
                .query(BigDecimal.class)
                .optional();
    }

    /**
     * İki hesabı her zaman küçük id'den başlayarak kilitler: deadlock'u önleyen kural.
     * NO KEY UPDATE: önceden eklenen FK'li satırların KEY SHARE kilidiyle çakışmaz.
     */
    public List<AccountRow> lockInIdOrder(long customerId, long firstId, long secondId) {
        return jdbc.sql("""
                SELECT id, customer_id, currency, balance, status
                  FROM accounts
                 WHERE id IN (:first, :second) AND customer_id = :customerId
                 ORDER BY id
                   FOR NO KEY UPDATE
                """)
                .param("first", firstId)
                .param("second", secondId)
                .param("customerId", customerId)
                .query(AccountRow.class)
                .list();
    }

    /** Sadece satır kilidi bu transaction'dayken çağrılır (lockInIdOrder sonrası). */
    public void updateBalance(long id, BigDecimal newBalance) {
        int rows = jdbc.sql("""
                UPDATE accounts
                   SET balance = :balance, version = version + 1, updated_at = now()
                 WHERE id = :id
                """)
                .param("balance", newBalance)
                .param("id", id)
                .update();
        if (rows != 1) {
            throw new IllegalStateException("Kilitli hesap güncellenemedi: " + id);
        }
    }
}

@Repository
public class TransactionRepository {

    private final JdbcClient jdbc;

    public TransactionRepository(JdbcClient jdbc) {
        this.jdbc = jdbc;
    }

    /**
     * true: bu key ilk kez görüldü, işi yap. false: key zaten var (gerekirse onun commit'i beklendi).
     * Aynı key ile eşzamanlı ikinci istek unique index üzerinde birincinin bitmesini bekler.
     */
    public boolean insertIfAbsent(NewTransaction tx) {
        int rows = jdbc.sql("""
                INSERT INTO transactions (id, customer_id, idempotency_key, request_hash, type, status,
                                          account_id, amount, currency, quote_id)
                VALUES (:id, :customerId, :key, :hash, :type, 'COMPLETED',
                        :accountId, :amount, :currency, :quoteId)
                ON CONFLICT (customer_id, idempotency_key) DO NOTHING
                """)
                .param("id", tx.id())
                .param("customerId", tx.customerId())
                .param("key", tx.idempotencyKey())
                .param("hash", tx.requestHash())
                .param("type", tx.type().name())
                .param("accountId", tx.accountId())
                .param("amount", tx.amount().amount())
                .param("currency", tx.amount().currency().getCurrencyCode())
                .param("quoteId", tx.quoteId(), Types.OTHER)
                .update();
        return rows == 1;
    }

    /** İlk isteğin cevabını DB'deki kayıttan yeniden üretir; body farklıysa 422. */
    public TransactionView replay(long customerId, String key, String requestHash) {
        record Stored(String requestHash, TransactionView view) { }
        Stored stored = jdbc.sql("""
                SELECT t.id, t.request_hash, t.type, t.status, t.amount, t.currency, l.balance_after
                  FROM transactions t
                  LEFT JOIN ledger_entries l ON l.transaction_id = t.id AND l.account_id = t.account_id
                 WHERE t.customer_id = :customerId AND t.idempotency_key = :key
                """)
                .param("customerId", customerId)
                .param("key", key)
                .query((rs, rowNum) -> new Stored(
                        rs.getString("request_hash"),
                        new TransactionView(
                                rs.getObject("id", UUID.class),
                                TransactionType.valueOf(rs.getString("type")),
                                rs.getString("status"),
                                rs.getBigDecimal("amount"),
                                rs.getString("currency"),
                                rs.getBigDecimal("balance_after"))))
                .single();
        if (!stored.requestHash().equals(requestHash)) {
            throw new IdempotencyKeyReusedException(key);
        }
        return stored.view();
    }
}

@Service
public class AccountService {

    private final AccountRepository accounts;
    private final TransactionRepository transactions;
    private final LedgerRepository ledger;

    public AccountService(AccountRepository accounts, TransactionRepository transactions,
                          LedgerRepository ledger) {
        this.accounts = accounts;
        this.transactions = transactions;
        this.ledger = ledger;
    }

    @Transactional
    public Outcome deposit(long customerId, long accountId, String idempotencyKey, Money amount) {
        return apply(TransactionType.DEPOSIT, customerId, accountId, idempotencyKey, amount,
                () -> accounts.credit(accountId, customerId, amount),
                account -> account.deposit(amount));
    }

    @Transactional
    public Outcome withdraw(long customerId, long accountId, String idempotencyKey, Money amount) {
        return apply(TransactionType.WITHDRAWAL, customerId, accountId, idempotencyKey, amount,
                () -> accounts.debitIfSufficient(accountId, customerId, amount),
                account -> account.withdraw(amount));
    }

    private Outcome apply(TransactionType type, long customerId, long accountId, String key, Money amount,
                          Supplier<Optional<BigDecimal>> atomicUpdate, Consumer<Account> domainRule) {
        if (!amount.isPositive()) {          // negatif "deposit" gizli bir withdraw olurdu
            throw new InvalidAmountException("Tutar pozitif olmalı: " + amount.amount());
        }
        String hash = RequestHash.of(type, accountId, amount.amount(), amount.currency());
        UUID txId = UUID.randomUUID();

        // 1) Idempotency: key'i iş verisiyle aynı transaction'da sahiplen.
        if (!transactions.insertIfAbsent(new NewTransaction(txId, customerId, key, hash, type,
                accountId, amount, null))) {
            return Outcome.replay(transactions.replay(customerId, key, hash));
        }

        // 2) Bakiye: kontrol ve değişiklik tek atomik UPDATE.
        BigDecimal balanceAfter = atomicUpdate.get()
                .orElseThrow(() -> explainRejection(customerId, accountId, domainRule));

        // 3) Değişmez hareket kaydı.
        BigDecimal signed = type == TransactionType.WITHDRAWAL ? amount.amount().negate() : amount.amount();
        ledger.append(txId, accountId, signed, amount.currency(), balanceAfter);

        return Outcome.fresh(new TransactionView(txId, type, "COMPLETED", amount.amount(),
                amount.currency().getCurrencyCode(), balanceAfter));
    }

    /**
     * UPDATE 0 satır döndü: hangi kural bozuldu? Hesabı okuyup aynı kuralı bellekte çalıştırırız.
     * Fırlatılan exception transaction'ı rollback eder; idempotency kaydı da geri alınır.
     */
    private RuntimeException explainRejection(long customerId, long accountId, Consumer<Account> domainRule) {
        Account account = accounts.findOwned(accountId, customerId)   // başkasının hesabı da 404
                .map(AccountRow::toDomain)
                .orElseThrow(() -> new AccountNotFoundException(accountId));
        try {
            domainRule.accept(account);
        } catch (DomainException violated) {
            return violated;
        }
        // Okuma anında kural geçiyor: arada başka bir işlem bakiyeyi değiştirdi. Nadir; tekrar denenebilir.
        return new ConcurrentUpdateException(accountId);
    }
}

@Service
public class ExchangeService {

    private static final int QUOTE_TTL_SECONDS = 30;

    private final AccountRepository accounts;
    private final QuoteRepository quotes;
    private final TransactionRepository transactions;
    private final LedgerRepository ledger;
    private final FxRateClient fxRateClient;

    public ExchangeService(AccountRepository accounts, QuoteRepository quotes,
                           TransactionRepository transactions, LedgerRepository ledger,
                           FxRateClient fxRateClient) {
        this.accounts = accounts;
        this.quotes = quotes;
        this.transactions = transactions;
        this.ledger = ledger;
        this.fxRateClient = fxRateClient;
    }

    /** Bilerek @Transactional DEĞİL: dış HTTP çağrısı sırasında DB bağlantısı tutulmaz. */
    public QuoteView quote(long customerId, long sourceAccountId, long targetAccountId, BigDecimal sourceAmount) {
        Account source = loadOwned(customerId, sourceAccountId);
        Account target = loadOwned(customerId, targetAccountId);
        if (source.currency().equals(target.currency())) {
            throw new CurrencyMismatchException(source.currency(), target.currency());
        }
        Money amount = new Money(sourceAmount, source.currency());

        FxRate rate = fxRateClient.rate(source.currency(), target.currency());
        Money targetAmount = FxConversion.convert(amount, target.currency(), rate.rate());

        UUID quoteId = UUID.randomUUID();
        var expiresAt = quotes.insert(quoteId, customerId, sourceAccountId, targetAccountId,
                amount.amount(), targetAmount.amount(), rate.rate(), rate.providerRef(), QUOTE_TTL_SECONDS);
        return new QuoteView(quoteId, amount.amount(), source.currency().getCurrencyCode(),
                targetAmount.amount(), target.currency().getCurrencyCode(), rate.rate(), expiresAt);
    }

    @Transactional
    public Outcome execute(long customerId, long sourceAccountId, String idempotencyKey, UUID quoteId) {
        QuoteRow quote = quotes.findOwned(quoteId, customerId)
                .filter(q -> q.sourceAccountId() == sourceAccountId)
                .orElseThrow(() -> new QuoteNotFoundException(quoteId));
        Money debit = new Money(quote.sourceAmount(), Currency.getInstance(quote.sourceCurrency()));
        Money credit = new Money(quote.targetAmount(), Currency.getInstance(quote.targetCurrency()));
        String hash = RequestHash.of(TransactionType.EXCHANGE, sourceAccountId, quoteId);
        UUID txId = UUID.randomUUID();

        // 1) Idempotency
        boolean fresh;
        try {
            fresh = transactions.insertIfAbsent(new NewTransaction(txId, customerId, idempotencyKey, hash,
                    TransactionType.EXCHANGE, sourceAccountId, debit, quoteId));
        } catch (DuplicateKeyException sameQuoteOtherKey) {   // transactions.quote_id UNIQUE
            throw new QuoteNotUsableException(quoteId);
        }
        if (!fresh) {
            return Outcome.replay(transactions.replay(customerId, idempotencyKey, hash));
        }

        // 2) Teklifi tek seferlik tüket (süre kontrolü DB saatiyle)
        if (!quotes.markUsed(quoteId, customerId)) {
            throw new QuoteNotUsableException(quoteId);
        }

        // 3) İki hesabı id sırasıyla kilitle, kuralları domain nesnesinde çalıştır
        List<AccountRow> locked = accounts.lockInIdOrder(customerId,
                Math.min(quote.sourceAccountId(), quote.targetAccountId()),
                Math.max(quote.sourceAccountId(), quote.targetAccountId()));
        Account source = pick(locked, quote.sourceAccountId());
        Account target = pick(locked, quote.targetAccountId());
        source.withdraw(debit);      // InsufficientFunds / AccountNotActive -> rollback
        target.deposit(credit);

        accounts.updateBalance(source.id(), source.balance().amount());
        accounts.updateBalance(target.id(), target.balance().amount());
        ledger.append(txId, source.id(), debit.amount().negate(), debit.currency(), source.balance().amount());
        ledger.append(txId, target.id(), credit.amount(), credit.currency(), target.balance().amount());

        return Outcome.fresh(new TransactionView(txId, TransactionType.EXCHANGE, "COMPLETED",
                debit.amount(), debit.currency().getCurrencyCode(), source.balance().amount()));
    }

    private Account loadOwned(long customerId, long accountId) {
        return accounts.findOwned(accountId, customerId)
                .map(AccountRow::toDomain)
                .orElseThrow(() -> new AccountNotFoundException(accountId));
    }

    private static Account pick(List<AccountRow> rows, long id) {
        return rows.stream()
                .filter(r -> r.id() == id)
                .findFirst()
                .map(AccountRow::toDomain)
                .orElseThrow(() -> new AccountNotFoundException(id));
    }
}

    /** expires_at DB saatiyle hesaplanır; kontrol de DB saatiyle yapılır (pod saat kayması yok). */
    public OffsetDateTime insert(UUID id, long customerId, long sourceAccountId, long targetAccountId,
                                 BigDecimal sourceAmount, BigDecimal targetAmount, BigDecimal rate,
                                 String providerRef, int ttlSeconds) {
        return jdbc.sql("""
                INSERT INTO exchange_quotes (id, customer_id, source_account_id, target_account_id,
                                             source_amount, target_amount, rate, provider_ref, expires_at)
                VALUES (:id, :customerId, :sourceId, :targetId, :sourceAmount, :targetAmount, :rate,
                        :providerRef, now() + (:ttl * interval '1 second'))
                RETURNING expires_at
                """)
                // .param(...) çağrıları
                .query(OffsetDateTime.class)
                .single();
    }

    /** Teklifi tek seferlik tüketir: süresi geçmişse ya da kullanılmışsa false. */
    public boolean markUsed(UUID id, long customerId) {
        return jdbc.sql("""
                UPDATE exchange_quotes
                   SET status = 'USED'
                 WHERE id = :id AND customer_id = :customerId
                   AND status = 'ACTIVE' AND expires_at > now()
                """)
                .param("id", id)
                .param("customerId", customerId)
                .update() == 1;
    }

@Configuration
public class FxClientConfig {

    @Bean
    RestClient fxRestClient(RestClient.Builder builder, @Value("${fx.base-url}") String baseUrl) {
        HttpClient httpClient = HttpClient.newBuilder()
                .connectTimeout(Duration.ofMillis(500))
                .build();
        JdkClientHttpRequestFactory factory = new JdkClientHttpRequestFactory(httpClient);
        factory.setReadTimeout(Duration.ofSeconds(1));      // p99 ~200 ms varsayımıyla
        return builder.baseUrl(baseUrl).requestFactory(factory).build();
    }

    @Bean
    Clock clock() {
        return Clock.systemUTC();
    }
}

@Component
public class FxRateClient {

    /** İş kararı: bundan eski bir kurla müşteriye teklif verilmez. */
    private static final Duration MAX_STALENESS = Duration.ofSeconds(60);

    private record CachedRate(FxRate rate, Instant fetchedAt) { }

    private final RestClient fxRestClient;
    private final Clock clock;
    private final Map<String, CachedRate> lastKnown = new ConcurrentHashMap<>();

    public FxRateClient(RestClient fxRestClient, Clock clock) {
        this.fxRestClient = fxRestClient;
        this.clock = clock;
    }

    // GET ve yan etkisiz: retry güvenli. Fallback en dış katmanda (Retry) ki önce denemeler tükensin.
    @Retry(name = "fx", fallbackMethod = "lastKnownRate")
    @CircuitBreaker(name = "fx")
    public FxRate rate(Currency from, Currency to) {
        FxRate rate = fxRestClient.get()
                .uri("/v1/rates?from={from}&to={to}", from.getCurrencyCode(), to.getCurrencyCode())
                .retrieve()
                .body(FxRate.class);
        if (rate == null || rate.rate() == null || rate.rate().signum() <= 0) {
            throw new IllegalStateException("Geçersiz kur cevabı: " + rate);
        }
        lastKnown.put(key(from, to), new CachedRate(rate, clock.instant()));
        return rate;
    }

    private FxRate lastKnownRate(Currency from, Currency to, Throwable cause) {
        CachedRate cached = lastKnown.get(key(from, to));
        if (cached != null && cached.fetchedAt().isAfter(clock.instant().minus(MAX_STALENESS))) {
            return cached.rate();
        }
        throw new FxRateUnavailableException("Kur alınamadı: " + key(from, to), cause);
    }

    private static String key(Currency from, Currency to) {
        return from.getCurrencyCode() + "/" + to.getCurrencyCode();
    }
}

fx:
  base-url: https://fx-provider.example.com

spring:
  datasource:
    hikari:
      maximum-pool-size: 10
      connection-timeout: 2000          # ms; havuz beklemesi varsayılan 30 sn olmasın

resilience4j:
  circuitbreaker:
    instances:
      fx:
        sliding-window-size: 50
        minimum-number-of-calls: 20
        failure-rate-threshold: 50
        slow-call-duration-threshold: 800ms
        slow-call-rate-threshold: 50
        wait-duration-in-open-state: 10s
        permitted-number-of-calls-in-half-open-state: 5
  retry:
    instances:
      fx:
        max-attempts: 2                 # 1 çağrı + 1 tekrar
        wait-duration: 100ms
        enable-randomized-wait: true
        retry-exceptions:
          - org.springframework.web.client.ResourceAccessException
          - org.springframework.web.client.HttpServerErrorException
        ignore-exceptions:
          - io.github.resilience4j.circuitbreaker.CallNotPermittedException

ALTER ROLE bank_app SET lock_timeout = '2s';
ALTER ROLE bank_app SET statement_timeout = '5s';
ALTER ROLE bank_app SET idle_in_transaction_session_timeout = '10s';
REVOKE UPDATE, DELETE, TRUNCATE ON ledger_entries FROM bank_app;

public record AmountRequest(
        @NotNull @Positive @Digits(integer = 15, fraction = 4) BigDecimal amount,
        @NotNull @Pattern(regexp = "[A-Z]{3}") String currency) {

    public Money toMoney() {
        try {
            return new Money(amount, Currency.getInstance(currency));
        } catch (IllegalArgumentException unknownCurrency) {
            throw new InvalidAmountException("Bilinmeyen para birimi: " + currency);
        }
    }
}

@RestController
@RequestMapping("/api/v1/accounts/{accountId}")
public class AccountController {

    // Gerçekte müşteri kimliği JWT'den gelir; header burada sadeleştirme.
    private static final String CUSTOMER = "X-Customer-Id";
    private static final String IDEMPOTENCY_KEY = "Idempotency-Key";

    private final AccountService accountService;
    private final ExchangeService exchangeService;

    public AccountController(AccountService accountService, ExchangeService exchangeService) {
        this.accountService = accountService;
        this.exchangeService = exchangeService;
    }

    @PostMapping("/deposits")
    public ResponseEntity<TransactionView> deposit(@PathVariable long accountId,
                                                   @RequestHeader(CUSTOMER) long customerId,
                                                   @RequestHeader(IDEMPOTENCY_KEY) @Size(min = 8, max = 255) String key,
                                                   @Valid @RequestBody AmountRequest request) {
        return created(accountService.deposit(customerId, accountId, key, request.toMoney()));
    }

    @PostMapping("/withdrawals")
    public ResponseEntity<TransactionView> withdraw(@PathVariable long accountId,
                                                    @RequestHeader(CUSTOMER) long customerId,
                                                    @RequestHeader(IDEMPOTENCY_KEY) @Size(min = 8, max = 255) String key,
                                                    @Valid @RequestBody AmountRequest request) {
        return created(accountService.withdraw(customerId, accountId, key, request.toMoney()));
    }

    @PostMapping("/exchange-quotes")
    public ResponseEntity<QuoteView> quote(@PathVariable long accountId,
                                           @RequestHeader(CUSTOMER) long customerId,
                                           @Valid @RequestBody QuoteRequest request) {
        QuoteView quote = exchangeService.quote(customerId, accountId,
                request.targetAccountId(), request.sourceAmount());
        return ResponseEntity.status(201).body(quote);
    }

    @PostMapping("/exchanges")
    public ResponseEntity<TransactionView> exchange(@PathVariable long accountId,
                                                    @RequestHeader(CUSTOMER) long customerId,
                                                    @RequestHeader(IDEMPOTENCY_KEY) @Size(min = 8, max = 255) String key,
                                                    @Valid @RequestBody ExchangeRequest request) {
        return created(exchangeService.execute(customerId, accountId, key, request.quoteId()));
    }

    private static ResponseEntity<TransactionView> created(Outcome outcome) {
        return ResponseEntity
                .created(URI.create("/api/v1/transactions/" + outcome.view().transactionId()))
                .header("Idempotent-Replayed", String.valueOf(outcome.replayed()))
                .body(outcome.view());
    }
}

@RestControllerAdvice
public class ApiExceptionHandler extends ResponseEntityExceptionHandler {

    @ExceptionHandler(DomainException.class)
    ProblemDetail handleDomain(DomainException ex) {
        HttpStatus status = switch (ex) {                       // sealed: eksik dal derleme hatası
            case AccountNotFoundException e -> HttpStatus.NOT_FOUND;
            case QuoteNotFoundException e -> HttpStatus.NOT_FOUND;
            case QuoteNotUsableException e -> HttpStatus.CONFLICT;
            case ConcurrentUpdateException e -> HttpStatus.CONFLICT;
            case InsufficientFundsException e -> HttpStatus.UNPROCESSABLE_ENTITY;
            case AccountNotActiveException e -> HttpStatus.UNPROCESSABLE_ENTITY;
            case CurrencyMismatchException e -> HttpStatus.UNPROCESSABLE_ENTITY;
            case InvalidAmountException e -> HttpStatus.UNPROCESSABLE_ENTITY;
            case IdempotencyKeyReusedException e -> HttpStatus.UNPROCESSABLE_ENTITY;
        };
        ProblemDetail problem = ProblemDetail.forStatusAndDetail(status, ex.getMessage());
        problem.setProperty("code", ex.code());
        return problem;
    }

    /** Kilit zaman aşımı, kaçan bir deadlock vb.: transaction geri alındı, aynı key ile tekrar güvenli. */
    @ExceptionHandler(ConcurrencyFailureException.class)
    ResponseEntity<ProblemDetail> handleConcurrency(ConcurrencyFailureException ex) {
        ProblemDetail problem = ProblemDetail.forStatusAndDetail(HttpStatus.CONFLICT,
                "İşlem eşzamanlı bir işlemle çakıştı, aynı Idempotency-Key ile tekrar deneyin");
        problem.setProperty("code", "CONCURRENT_UPDATE");
        return ResponseEntity.status(HttpStatus.CONFLICT).header(HttpHeaders.RETRY_AFTER, "1").body(problem);
    }

    @ExceptionHandler(FxRateUnavailableException.class)
    ResponseEntity<ProblemDetail> handleFx(FxRateUnavailableException ex) {
        ProblemDetail problem = ProblemDetail.forStatusAndDetail(HttpStatus.SERVICE_UNAVAILABLE,
                "Kur servisi geçici olarak kullanılamıyor");
        problem.setProperty("code", "FX_UNAVAILABLE");
        return ResponseEntity.status(HttpStatus.SERVICE_UNAVAILABLE).header(HttpHeaders.RETRY_AFTER, "5").body(problem);
    }
}

public interface AccountJpaRepository extends JpaRepository<AccountEntity, Long> {

    @Modifying(flushAutomatically = true, clearAutomatically = true)
    @Query("""
           update AccountEntity a
              set a.balance = a.balance - :amount, a.version = a.version + 1
            where a.id = :id and a.status = 'ACTIVE' and a.balance >= :amount
           """)
    int debitIfSufficient(@Param("id") long id, @Param("amount") BigDecimal amount);

    @Lock(LockModeType.PESSIMISTIC_WRITE)                      // pessimistic satır kilidi
    @Query("select a from AccountEntity a where a.id in :ids order by a.id")
    List<AccountEntity> lockInIdOrder(@Param("ids") List<Long> ids);
}

class FxConversionTest {

    private static final Currency USD = Currency.getInstance("USD");
    private static final Currency JPY = Currency.getInstance("JPY");

    @Test
    void roundsHalfEvenToTargetCurrencyScale() {
        assertThat(FxConversion.convert(Money.of("123.45", "TRY"), USD, new BigDecimal("0.02913457")).amount())
                .isEqualByComparingTo("3.60");                       // 3.5966626665
        assertThat(FxConversion.convert(Money.of("0.50", "TRY"), USD, new BigDecimal("0.05")).amount())
                .isEqualByComparingTo("0.02");                       // 0.025 -> çift komşu
        assertThat(FxConversion.convert(Money.of("12.34", "USD"), JPY, new BigDecimal("151.237")).amount())
                .isEqualByComparingTo("1866");                       // JPY scale 0
    }

    @Test
    void moneyRejectsMoreDecimalsThanCurrencyAllows() {
        assertThatThrownBy(() -> Money.of("10.005", "TRY")).isInstanceOf(InvalidAmountException.class);
        assertThat(Money.of("10.0500", "TRY").amount()).isEqualTo(new BigDecimal("10.05"));
    }
}

@SpringBootTest
@Testcontainers
class WithdrawConcurrencyIT {

    @Container
    @ServiceConnection
    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:16-alpine");

    private static final long CUSTOMER = 42L;

    @Autowired AccountService accountService;
    @Autowired JdbcClient jdbc;

    @Test
    void hundredConcurrentWithdrawalsNeverOverdrawAndLedgerMatchesBalance() throws Exception {
        long accountId = jdbc.sql("INSERT INTO accounts (customer_id, currency) VALUES (:c, 'TRY') RETURNING id")
                .param("c", CUSTOMER).query(Long.class).single();
        accountService.deposit(CUSTOMER, accountId, UUID.randomUUID().toString(), Money.of("500", "TRY"));

        int threads = 100;
        CountDownLatch ready = new CountDownLatch(threads);
        CountDownLatch start = new CountDownLatch(1);
        AtomicInteger succeeded = new AtomicInteger();
        AtomicInteger rejected = new AtomicInteger();
        List<Future<?>> futures = new ArrayList<>();

        try (ExecutorService pool = Executors.newFixedThreadPool(threads)) {
            for (int i = 0; i < threads; i++) {
                futures.add(pool.submit(() -> {
                    ready.countDown();
                    start.await();                                  // hepsi aynı anda başlasın
                    try {
                        accountService.withdraw(CUSTOMER, accountId, UUID.randomUUID().toString(),
                                Money.of("10", "TRY"));
                        succeeded.incrementAndGet();
                    } catch (InsufficientFundsException e) {
                        rejected.incrementAndGet();
                    }
                    return null;
                }));
            }
            ready.await();
            start.countDown();
            for (Future<?> f : futures) {
                f.get(30, TimeUnit.SECONDS);                        // beklenmeyen exception testi düşürsün
            }
        }

        assertThat(succeeded.get()).isEqualTo(50);
        assertThat(rejected.get()).isEqualTo(50);
        assertThat(balance(accountId)).isEqualByComparingTo("0");
        assertThat(ledgerSum(accountId)).isEqualByComparingTo(balance(accountId));   // değişmez kural
    }

    private BigDecimal balance(long id) {
        return jdbc.sql("SELECT balance FROM accounts WHERE id = :id").param("id", id)
                .query(BigDecimal.class).single();
    }

    private BigDecimal ledgerSum(long id) {
        return jdbc.sql("SELECT COALESCE(SUM(amount), 0) FROM ledger_entries WHERE account_id = :id")
                .param("id", id).query(BigDecimal.class).single();
    }
}

class FxRateClientTimeoutTest {

    @RegisterExtension
    static WireMockExtension fx = WireMockExtension.newInstance()
            .options(wireMockConfig().dynamicPort())
            .build();

    @Test
    void slowProviderIsCutByReadTimeout() {
        fx.stubFor(get(urlPathEqualTo("/v1/rates"))
                .willReturn(okJson("""
                        {"from":"TRY","to":"USD","rate":0.0291,"providerRef":"r-1"}
                        """).withFixedDelay(3_000)));
        RestClient restClient = new FxClientConfig().fxRestClient(RestClient.builder(), fx.baseUrl());
        FxRateClient client = new FxRateClient(restClient, Clock.systemUTC());

        assertTimeoutPreemptively(Duration.ofSeconds(2), () ->
                assertThatThrownBy(() -> client.rate(Currency.getInstance("TRY"), Currency.getInstance("USD")))
                        .isInstanceOf(ResourceAccessException.class));
    }
}