Tổng quan và hướng dẫn luồng công việc

HieraChain là sổ cái phân cấp thuần Python, hoạt động như plugin layer cho hạ tầng Web2 hiện có. Nó không thay thế ngăn xếp mạng doanh nghiệp vốn đã xử lý TLS/SSL, tường lửa và WAF ở API gateway. HieraChain tập trung vào tính bất biến, niềm tin phân tán, bằng chứng can thiệp và chống chối bỏ.

Tài liệu này là tham khảo trung tâm cho 16 luồng công việc hệ thống trong 6 nhóm chức năng. Nó mô tả cách các luồng tương tác khi chạy và cách đọc, duy trì hoặc thêm luồng mới.

1. Rào chắn phát triển cốt lõi

Khi làm việc với luồng công việc của HieraChain, tuân thủ các rào chắn sau:

Kiểm duyệt thuật ngữ: HieraChain theo dõi sổ cái quy trình nghiệp vụ, không phải tiền mã hóa. Không dùng thuật ngữ tiền mã hóa trong payload sự kiện, tên biến, khóa cơ sở dữ liệu hoặc comment.
- Từ bị cấm: transaction, mining, coin, token, wallet, address, sender, receiver, amount, fee.
- Từ bắt buộc: event cho mục sổ cái, node cho peer, msp_id cho danh tính, entity_id cho tài sản nghiệp vụ.
- Lưu ý: CrossChainValidator quét commit và từ chối mã chứa từ bị cấm.
Ràng buộc độ trễ tối thiểu: HieraChain giữ độ trễ cơ sở ở mức 10 đến 20ms. Giữ mã luồng ngắn và nhanh. Không thêm mã hóa tầng truyền tải hoặc wrapper thừa làm tăng tải CPU.
Không truy cập trực tiếp bộ lưu trữ: không truy vấn SQL hoặc Redis trực tiếp. Dùng adapter lưu trữ trong adapters/database/ (ví dụ adapters/database/sqlite_adapter.py).

2. Tất cả luồng công việc: tra cứu nhanh

Bảng này liệt kê tất cả luồng để tra cứu nhanh:

Luồng công việc	Nhóm	Kích hoạt	Kết quả	Mô-đun chính
Gửi Sự kiện	A	`POST /api/ledger/chains/{name}/events`	Khối được thêm vào Sub-Chain	`hierarchical/sub_chain/base.py` (`SubChain.add_event`)
Neo giữ Bằng chứng	A	Khối được hoàn thiện trên Sub-Chain	Mã băm bằng chứng trên Main Chain	`hierarchical/main_chain/base.py` + `hierarchical/sub_chain/proof.py`
Giao dịch Liên chuỗi 2PC	A	`HierarchyManager.transaction_manager`	`COMMITTED` hoặc `ROLLED_BACK`	`hierarchical/hierarchy_manager/base.py` + `hierarchical/transaction_manager.py`
Đồng thuận BFT	B	`HRC_MAINCHAIN_CONSENSUS` / `HRC_CONSENSUS_TYPE`	Khối được xác nhận bởi 2f+1 validator	`consensus/bft/consensus.py`
Khóa băng Cụm	C	Bất thường vượt ngưỡng rủi ro	Tất cả node bị đóng băng / khôi phục	`cluster/lockdown_types.py` + `cluster/lockdown_protocol.py`
Giảm thiểu Lỗi & Phục hồi	C	Lỗi mạng / hết hạn leader / lỗi toàn vẹn	Trạng thái khôi phục từ snapshot	`error_mitigation/rollback_manager.py` + `consensus_recovery.py`
Truy vết Thực thể	D	`EntityTracer.trace_entity()`	Dấu vết kiểm toán liên chuỗi đầy đủ	`domains/utils/entity_tracer.py`
Nạp lại Trạng thái Chuỗi	D	Khởi động lại node hoặc lệch mã băm	Chuỗi trong bộ nhớ đồng bộ với DB	`hierarchical/sub_chain/base.py` + `hierarchical/sub_chain/ordering.py`
Xác thực Tính toàn vẹn	D	Định kỳ / thủ công / bất thường Risk Alerts	`IntegrityReport` (HEALTHY / DEGRADED)	`security/verify/block_verifier.py`
Thực thi Chính sách	E	Mọi thao tác nhạy cảm về quyền	`allow` hoặc `deny` kèm đường dẫn quyết định	`security/policy_engine.py`
Luồng dữ liệu WebSocket	E	Client kết nối tới `/ws/{chain_name}`	Đẩy khối/sự kiện thời gian thực	`api/websocket/manager.py`
Lưu trữ Mã hóa IPFS	E	`IPFSClient.upload_json()`	Trả về CID; bản mã trên IPFS	`api/storage/ipfs_client.py`
Cảnh báo Rủi ro	E	Lịch `PerformanceMonitor`	Cảnh báo được gửi; leo thang nếu không xác nhận	`monitoring/alert_system.py`
Đồng bộ Tích hợp ERP	E	Timer `SyncScheduler`	Sự kiện ERP được gửi tới Sub-Chain	`integration/erp_ledger.py`
Danh tính & Xác thực MSP	F	Đăng ký thực thể / xác thực API	Xác nhận danh tính và ủy quyền thao tác	`security/msp.py`
Sao lưu & Khôi phục Khóa	F	Tạo khóa (`cli/key.py`)	Tệp khóa / vault được sao lưu; khôi phục qua CLI	`cli/key.py` + `security/key_provider.py` (không có `key_backup_manager.py`)

3. Nhóm chức năng và phân hệ

Các luồng được nhóm thành sáu khu vực. Dùng bảng điều khiển bên dưới để tìm nhóm khớp với phân hệ bạn đang gỡ lỗi hoặc thay đổi:

Nhóm A: Hoạt động chuỗi cốt lõi

Xử lý tiếp nhận, xác thực mật mã và lưu trữ.
Nhóm B: Hoàn thiện đồng thuận

Hoàn thiện khối. Với lựa chọn PoA/PoF, xem Cơ chế Đồng thuận.
- Đồng thuận BFT (PBFT 3 pha)
Nhóm C: Quản lý cụm

Quản trị, kích hoạt khóa băng và phục hồi.
- Khóa băng Cụm
- Giảm thiểu Lỗi & Phục hồi
Nhóm D: Tính toàn vẹn và truy vết

Kiểm toán, nạp lại khi khởi động lạnh và xác thực toàn vẹn.
Nhóm E: Vận hành và tích hợp

Cổng chính sách, đẩy WebSocket, lưu trữ IPFS mã hóa và đồng bộ ERP.
Nhóm F: Quản lý danh tính và khóa

Đăng ký MSP nhẹ (lớp Certificate nội bộ trong security/msp.py), ủy quyền thành viên và sao lưu khóa do CLI quản lý (không có X.509/mTLS).
- Danh tính & Xác thực MSP
- Sao lưu & Khôi phục Khóa

4. Cách luồng tương tác

Sơ đồ cho thấy quan hệ thời gian chạy và kích hoạt giữa các luồng. Đường liền là thao tác đồng bộ hoặc chặn. Đường đứt là không đồng bộ hoặc theo sự kiện.

flowchart TD
    ERP["🏢 ERP System\n(SAP / Oracle)"]
    CLIENT["🖥️ Client / SDK"]

    WF14["ERP Sync"] -->|add_event| WF1
    CLIENT -->|POST /events| WF1

    WF15["🪪 MSP Identity"] -->|authorize_action| WF1
    WF15 -->|validate_identity| WF10["⚖️ Policy Enforcement"]
    WF10 -->|allow/deny gate| WF1

    WF1["📦 Event Submission"] -->|block finalized| WF2["Proof Anchoring"]
    WF1 -->|broadcast_new_block| WF11["🔌 WebSocket"]
    WF1 -->|upload large data| WF12["🗄️ IPFS Storage"]

    WF1 -->|cross-chain op| WF3["2PC Cross-Chain"]
    WF1 -->|BFT mode| WF4["👑 BFT Consensus"]

    WF9["🔍 Integrity Scan"] -->|DEGRADED| WF13["🚨 Risk & Alerts"]
    WF13 -->|critical threshold| WF5["🔒 Cluster Lockdown"]
    WF5 -.->|after lockdown| WF6["🔧 Error Recovery"]
    WF6 -.->|snapshot fail| WF8["♻️ Rehydration"]
    WF8 -.->|restore state| WF1

    WF5 -.->|key rotation| WF16["🔑 Key Backup"]
    WF15 -.->|cert issued| WF16

    WF7["🗂️ Entity Tracing"] -.->|reads| WF1

    ERP --> WF14

Luồng tích hợp chính cho lập trình viên

Chuỗi tiếp nhận và bảo mật	Mô tả
ERP → ERP Sync → Gửi Sự kiện → Neo giữ Bằng chứng	Pipeline tiếp nhận: thay đổi nghiệp vụ → sự kiện nội bộ → khối Sub-Chain → mã băm bằng chứng neo lên chuỗi gốc.
MSP Identity → Thực thi Chính sách → Gửi Sự kiện	Đường xác thực bảo mật: xác minh cert nội bộ (`msp.py:verify_certificate`) → kiểm tra chính sách ABAC → chấp nhận/từ chối sự kiện.
Quét Tính Toàn vẹn → Cảnh báo Rủi ro → Khóa băng Cụm → Phục hồi Lỗi	Đường phát hiện bất thường: `block_verifier`/`risk_analyzer` → gửi cảnh báo → khóa băng → `rollback_manager` khôi phục.
Khóa băng Cụm → Sao lưu Khóa	Không có liên kết tự động trong mã: xoay vòng/sao lưu khóa là thao tác thủ công qua `cli/key.py` (không do khóa băng kích hoạt).
Phục hồi Lỗi → Nạp lại Trạng thái	Dự phòng đồng bộ trạng thái: xác thực snapshot cục bộ thất bại kích hoạt dựng lại chuỗi trong bộ nhớ từ nhật ký DB.

5. Hướng dẫn lập trình viên: duy trì luồng công việc

Giữ tài liệu luồng đồng bộ với mã khi bạn thêm tính năng hoặc sửa hành vi:

Cấu trúc của một tài liệu luồng

Mỗi trang luồng (ví dụ event-submission.md) có bố cục sau. Nó phải chứa:

Front-matter Zensical: metadata YAML với title, description và icon. Không có tiền tố WF-number.
Tiêu đề H1: # [Title] khớp với front-matter.
Tổng quan: luồng làm gì và khi nào dùng.
Sơ đồ luồng: sơ đồ Mermaid sequence hoặc flowchart thể hiện tương tác thời gian chạy.
Chi tiết từng bước: bảng ánh xạ số thứ tự tới hành động của lập trình viên.
Xử lý lỗi: bảng ánh xạ lỗi (node offline, lỗi xác thực) tới biện pháp xử lý.
Lớp và phương thức chính: con trỏ từ bước luồng tới mã (ví dụ SubChain.add_event()).
Liên quan: liên kết tới luồng anh em hoặc luồng tiếp theo.

Quy trình thêm hoặc sửa luồng

Viết Markdown chuẩn: lưu luồng mới dưới docs/en/workflows/name.md dùng hệ thống thiết kế hiện tại.
Đăng ký trong zensical.toml: thêm luồng vào cây Workflows trong zensical.toml với tên gọn.
Quét thuật ngữ: kiểm tra không thêm từ vựng tiền mã hóa bị cấm.
Biên dịch và xác thực: chạy build Zensical trong môi trường HieraChain để kiểm tra định dạng và liên kết:
```
zensical build -f zensical.toml
```