Thao tác Liên chuỗi (2PC)

Tổng quan

Khi một thao tác nghiệp vụ cần thực hiện một cách nguyên tử (atomic) trải dài trên hai Sub-Chain (ví dụ: chuyển tài sản từ Sub-Chain logistics sang Sub-Chain finance), HieraChain sử dụng giao thức Cam kết Hai pha (Two-Phase Commit - 2PC) để đảm bảo tính nguyên tử. Hoặc cả hai chuỗi cùng cam kết thay đổi, hoặc cả hai cùng hoàn tác (rollback). Không cho phép trạng thái dở dở dang dang.

Ví dụ thực tế: Chuyển một mặt hàng trong kho giữa hai phòng ban khác nhau. Chuỗi nguồn ghi nhận sự kiện deduct (trừ hàng); chuỗi đích ghi nhận sự kiện receive (nhận hàng). Cả hai hoạt động đều phải thành công hoặc không hoạt động nào được áp dụng.

Biểu đồ Luồng: Kịch bản Thành công (Happy Path)

sequenceDiagram
    autonumber
    participant HM as 🏛️ HierarchyManager
    participant TM as 🔄 CrossChainOperationManager
    participant SRC as 📦 Source SubChain
    participant DST as 📦 Destination SubChain

    HM->>TM: initiate_cross_chain_operation(src, dst, payload)
    TM->>TM: Tạo CrossChainOperation (UUID, state=PENDING)

    rect rgb(0, 0, 0, 0)
        Note over TM,DST: PHA 1 — CHUẨN BỊ (PREPARE)
        TM->>SRC: prepare_operation(op_id, payload, is_source=True)
        SRC->>SRC: Khóa tài nguyên, xác thực payload
        SRC-->>TM: True ✅

        TM->>DST: prepare_operation(op_id, payload, is_source=False)
        DST->>DST: Kiểm tra khả năng tiếp nhận
        DST-->>TM: True ✅

        TM->>TM: state = PREPARED
    end

    rect rgb(0, 0, 0, 0)
        Note over TM,DST: PHA 2 — CAM KẾT (COMMIT)
        TM->>SRC: commit_operation(op_id)
        SRC-->>TM: True ✅
        TM->>DST: commit_operation(op_id)
        DST-->>TM: True ✅
        TM->>TM: state = COMMITTED
    end

    TM-->>HM: op_id (COMMITTED)

Biểu đồ Luồng: Kịch bản Thất bại (Failure Paths)

sequenceDiagram
    autonumber
    participant TM as 🔄 CrossChainOperationManager
    participant SRC as 📦 Source SubChain
    participant DST as 📦 Destination SubChain

    rect rgb(0, 0, 0, 0)
        Note over TM,DST: KỊCH BẢN A — Pha 1 Chuẩn bị Thất bại
        TM->>SRC: prepare_operation(op_id, payload)
        SRC-->>TM: True ✅
        TM->>DST: prepare_operation(op_id, payload)
        DST-->>TM: False ❌  (Lỗi dung lượng / xác thực)
        TM->>TM: state = PENDING → Kích hoạt hoàn tác
        TM->>SRC: rollback_operation(op_id)
        TM->>DST: rollback_operation(op_id)
        TM->>TM: state = ROLLED_BACK ⚠️
    end

    rect rgb(0, 0, 0, 0)
        Note over TM,DST: KỊCH BẢN B — Pha 2 Cam kết Một phần Thất bại
        TM->>SRC: commit_operation(op_id)
        SRC-->>TM: True ✅
        TM->>DST: commit_operation(op_id)
        DST-->>TM: Ngoại lệ (Exception) ❌
        TM->>TM: state = FAILED ❌
        Note over TM: Yêu cầu xử lý thủ công<br/>Kiểm tra nhật ký để tìm trạng thái một phần
    end

Máy trạng thái Giao dịch (Transaction State Machine)

flowchart LR
    P["PENDING"] --> PR["PREPARED"]
    PR --> C["COMMITTED ✅"]
    PR --> RB["ROLLED_BACK ⚠️"]
    P --> F["FAILED ❌"]
    PR --> F

Các bước thực hiện chi tiết

Xử lý lỗi

Các Class & Method quan trọng

Liên quan

• Gửi Sự kiện: mỗi phương thức commit_transaction() bên trong sẽ gọi đến add_event()
• Giảm thiểu Lỗi & Phục hồi: quản lý khôi phục trạng thái ở cấp độ hệ thống