Double-Entry Ledger: Schema Bất Biến & Concurrency

UPDATE accounts SET balance = balance - 1000000 WHERE id = 'A';
UPDATE accounts SET balance = balance + 1000000 WHERE id = 'B';

// TigerBeetle Account Struct — 128 bytes chính xác, CPU cache-line aligned
pub const Account = extern struct {
    id: u128,                 // 16 bytes: Unique identifier (UUIDv4/v7 hoặc custom monotonic ID)
    debits_pending: u128,     // 16 bytes: Số tiền đang được reserve trong pending transfers
    debits_posted: u128,      // 16 bytes: Tổng debit đã commit hoàn toàn
    credits_pending: u128,    // 16 bytes: Số tiền được reserve ở phía credit
    credits_posted: u128,     // 16 bytes: Tổng credit đã commit hoàn toàn
    user_data_128: u128,      // 16 bytes: Metadata tuỳ chỉnh (ví dụ: customer_id)
    user_data_64: u64,        //  8 bytes: Metadata tuỳ chỉnh
    user_data_32: u32,        //  4 bytes: Metadata tuỳ chỉnh
    reserved: u32 = 0,        //  4 bytes: Padding để đạt đúng 128 bytes
    ledger: u32,              //  4 bytes: Nhóm tài khoản theo loại tiền tệ / asset type
    code: u16,                //  2 bytes: Chart of Accounts code (ví dụ: 1001 = tiền mặt)
    flags: u16,               //  2 bytes: Business rules flags
    timestamp: u64,           //  8 bytes: Nanosecond timestamp (do cluster quản lý)
};

// TigerBeetle Transfer Struct — 128 bytes, cùng alignment
pub const Transfer = extern struct {
    id: u128,                 // 16 bytes: Unique transfer ID
    debit_account_id: u128,   // 16 bytes: Tài khoản bị debit
    credit_account_id: u128,  // 16 bytes: Tài khoản được credit
    amount: u128,             // 16 bytes: Số lượng asset cần chuyển
    pending_id: u128,         // 16 bytes: ID của pending transfer (dùng trong two-phase)
    user_data_128: u128,      // 16 bytes: Metadata tuỳ chỉnh
    user_data_64: u64,        //  8 bytes: Metadata tuỳ chỉnh
    user_data_32: u32,        //  4 bytes: Metadata tuỳ chỉnh
    timeout: u32 = 0,         //  4 bytes: Auto-void timeout tính bằng giây
    ledger: u32,              //  4 bytes: Phải khớp với ledger của cả hai accounts
    code: u16,                //  2 bytes: Category code tuỳ chỉnh
    flags: u16,               //  2 bytes: Config flags (pending, post_pending, void_pending)
    timestamp: u64,           //  8 bytes: Timestamp nanosecond khi commit vào log
};

-- Bảng Accounts: Định nghĩa các tài khoản trong Chart of Accounts
CREATE TABLE accounts (
    id              UUID PRIMARY KEY,
    name            VARCHAR(100) NOT NULL,
    currency        CHAR(3) NOT NULL,           -- ISO 4217: 'VND', 'USD', 'JPY'
    debit_balance   NUMERIC(18, 4) DEFAULT 0.0000 NOT NULL 
                    CHECK (debit_balance >= 0),
    credit_balance  NUMERIC(18, 4) DEFAULT 0.0000 NOT NULL 
                    CHECK (credit_balance >= 0),
    type            VARCHAR(20) NOT NULL 
                    CHECK (type IN ('ASSET', 'LIABILITY', 'EQUITY', 'REVENUE', 'EXPENSE')),
    created_at      TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);

-- Bảng Transactions: Header của mỗi nhóm journal entries
CREATE TABLE transactions (
    id              UUID PRIMARY KEY,
    description     VARCHAR(255),
    posted_at       TIMESTAMP WITH TIME ZONE NOT NULL,
    created_at      TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);

-- Bảng Entries: Từng bút toán Nợ/Có (các "legs" của một transaction)
CREATE TABLE entries (
    id              UUID PRIMARY KEY,
    transaction_id  UUID NOT NULL REFERENCES transactions(id) ON DELETE CASCADE,
    account_id      UUID NOT NULL REFERENCES accounts(id),
    amount          NUMERIC(18, 4) NOT NULL CHECK (amount <> 0),
    direction       VARCHAR(6) NOT NULL CHECK (direction IN ('DEBIT', 'CREDIT')),
    created_at      TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);

-- Indexes để tăng tốc balance lookup
CREATE INDEX idx_entries_account_id     ON entries(account_id);
CREATE INDEX idx_entries_transaction_id ON entries(transaction_id);

-- Trigger: Enforce balance invariant — tổng DEBIT phải = tổng CREDIT trong cùng transaction
CREATE OR REPLACE FUNCTION verify_transaction_balance()
RETURNS TRIGGER AS $$
DECLARE
    balance_sum NUMERIC(18, 4);
BEGIN
    SELECT COALESCE(
        SUM(CASE WHEN direction = 'DEBIT' THEN amount ELSE -amount END),
        0
    )
    INTO balance_sum
    FROM entries
    WHERE transaction_id = NEW.transaction_id;

    IF balance_sum <> 0 THEN
        RAISE EXCEPTION 
            'Transaction unbalanced: SUM(DEBIT) - SUM(CREDIT) = %. Transaction ID: %',
            balance_sum, NEW.transaction_id;
    END IF;
    RETURN NEW;
END;
$$ LANGUAGE plpgsql;

CREATE TRIGGER trg_verify_balance
AFTER INSERT ON entries
FOR EACH ROW EXECUTE FUNCTION verify_transaction_balance();

BEGIN;

-- Khóa hai accounts theo thứ tự ID để tránh deadlock
-- Quy tắc: LUÔN lock account có ID nhỏ hơn trước
SELECT id, debit_balance, credit_balance
FROM accounts
WHERE id IN ('account-A', 'account-B')
ORDER BY id  -- Deterministic order — ngăn deadlock
FOR UPDATE;

-- Kiểm tra balance đủ không
-- INSERT vào transactions
-- INSERT vào entries (Nợ và Có)
-- UPDATE account balances

COMMIT;

-- Phát hiện mọi transaction có SUM(DEBIT) ≠ SUM(CREDIT)
SELECT
    transaction_id,
    SUM(CASE WHEN direction = 'DEBIT' THEN amount ELSE -amount END) AS discrepancy
FROM entries
GROUP BY transaction_id
HAVING SUM(CASE WHEN direction = 'DEBIT' THEN amount ELSE -amount END) <> 0;

-- Kết quả mong đợi: 0 rows. Nếu có rows → P1 alert ngay lập tức.

// Chạy 100 goroutines đồng thời rút $10 từ tài khoản có $100
func TestConcurrentWithdrawal(t *testing.T) {
    const (
        numWorkers     = 100
        withdrawAmount = 10_000   // $10 in cents
        initialBalance = 100_000  // $100 in cents
    )
    
    var (
        successCount atomic.Int64
        wg           sync.WaitGroup
    )
    
    for i := 0; i < numWorkers; i++ {
        wg.Add(1)
        go func() {
            defer wg.Done()
            err := withdrawFunds("account-A", withdrawAmount)
            if err == nil {
                successCount.Add(1)
            }
        }()
    }
    wg.Wait()
    
    // Chỉ đúng 10 requests được phép thành công
    assert.Equal(t, int64(10), successCount.Load(),
        "Chỉ 10 withdrawals được phép với balance $100")
    
    // Không có double-spend: balance cuối phải = $0
    balance := getBalance("account-A")
    assert.Equal(t, int64(0), balance, "Balance sau khi rút hết phải = 0")
}

func reconcileAllTransactions(db *sql.DB) ([]UnbalancedTx, error) {
    query := `
        SELECT transaction_id, 
               SUM(CASE WHEN direction = 'DEBIT' THEN amount ELSE -amount END) AS discrepancy
        FROM entries
        GROUP BY transaction_id
        HAVING SUM(CASE WHEN direction = 'DEBIT' THEN amount ELSE -amount END) <> 0
    `
    rows, err := db.Query(query)
    if err != nil {
        return nil, err
    }
    // Parse rows và fire P1 alert nếu có bất kỳ discrepancy nào
    // ...
}