Traceability Graph (11 Stages), CTE/KDE & W3C VC Ed25519

Tài liệu này phân tích chi tiết phần lõi công nghệ của Gotrace-portal: Vòng đời 11 công đoạn (11-Stage Lifecycle) của mã định danh đơn chiếc SGTIN, mô hình sự kiện CTE/KDE, cơ chế ký số W3C Verifiable Credentials (Ed25519) bất đồng bộ qua Piscina Worker Pool, và quy trình Merkle Tree Anchoring lên Spores Blockchain.

---

1. SGTIN 11-Stage Traceability Graph & Sự kiện CTE/KDE

Theo đặc tả docs/technical/TRACEABILITY_GRAPH_MODEL.md và implementation trong apps/backend/src/modules/vc/ cùng apps/zalo-be/src/modules/vc/, mỗi đơn vị sản phẩm vật lý được gắn một mã SGTIN duy nhất và đi qua tối đa 11 stages trong chuỗi cung ứng.

Tại mỗi Critical Tracking Event (CTE), hệ thống ghi nhận bộ Key Data Elements (KDE — Who, Where, When, What, Why):

Rendering diagram...

Bảng Mapping Sự kiện CTE sang W3C VC (CTE_EVENT_CODE)

Mã CTE (cte_event_code)	Nguồn phát sinh (source_type)	Module xử lý trong Code	Nội dung KDE được ký trong W3C VC
CTE-MATERIAL-IN	PLAN_INPUT	batchs/batch.service.ts (buildMaterialInKde)	Danh sách nguyên liệu/lô đầu vào liên kết (PlanInputLink), nhà cung cấp, số lượng, kế hoạch sản xuất.
CTE-PRODUCTION	PRODUCTION_LOG	production-logs/production-logs.service.ts	Sự kiện canh tác/sản xuất đã hoàn thành (cultivation_event_type), thời gian thực hiện, cơ sở sản xuất, hình ảnh minh chứng.
CTE-PACKAGING	PACKAGING_PLAN	packaging-plans/packaging-plans.service.ts	Mã đơn vị đóng gói (PackagingUnit / SSCC), quy cách đóng gói (Box/Carton/Pallet), danh sách child SGTINs.
CTE-SHIP	SHIPMENT_ORDER	shipment-orders/ & zalo-be/driver-shipments/	Đơn vận chuyển xuất kho, doanh nghiệp gửi, doanh nghiệp nhận, biển số xe, tài xế, thời điểm xuất bến.
CTE-RECEIVE	SHIPMENT_RECEIVE	shipment-orders/ & zalo-be/enterprise-shipments/	Biên bản nhận hàng tại kho bên mua / bếp ăn trường học, tình trạng hàng hóa, chữ ký xác nhận.
CTE-SOLD	POS_TRANSACTION / BUYER_CONFIRMATION	pos-sales/ & zalo-be/buyer-confirmations/	Giao dịch bán hàng tại điểm bán (SalePoint) hoặc lượt quét QR xác nhận mua hàng của người tiêu dùng cuối.

---

2. Kiến trúc Phát hành W3C Verifiable Credentials (vc_outbox + Piscina)

Để đảm bảo không mất sự kiện VC khi DB hoặc Redis gặp sự cố và đảm bảo đúng thứ tự chuỗi nhân quả (Causal Chain Ordering) giữa các sự kiện trên cùng một mã SGTIN, hệ thống áp dụng pattern Transactional Outbox kết hợp PostgreSQL Transactional Advisory Lock:

Rendering diagram...

Các Cơ chế Kỹ thuật Trọng yếu trong VcIssuanceWorker (apps/backend/src/modules/vc/issuance/vc-issuance.worker.ts)

1. Idempotency Key (idempotency_key): Mỗi bản ghi vc_outbox có khóa chống trùng lặp tính từ (source_type, source_id, cte_event_code). Nếu job retry nhiều lần, hệ thống chỉ phát hành đúng 1 VC cho mỗi cặp (sgtin_code, cte_event_code).
2. Predecessor Chain Gate: Trước khi ký sự kiện CTE-RECEIVE hoặc CTE-SOLD, worker kiểm tra xem còn bản ghi vc_outbox nào của sự kiện đứng trước (CTE-SHIP, CTE-MATERIAL-IN) cho cùng SGTIN đang ở trạng thái PENDING/PROCESSING hay không. Nếu còn, job tự động delay để đảm bảo chuỗi thời gian VC không bao giờ bị đảo ngược.
3. Per-SGTIN Transactional Advisory Lock (SELECT pg_advisory_xact_lock(hashtext(sgtinCode))): Tuần tự hóa việc ghi sgtin_vcs cho từng mã SGTIN ngay cả khi nhiều worker xử lý song song.

---

3. Merkle Tree Anchoring lên Spores Blockchain (vc-anchor)

Sau khi các bản ghi SgtinVc được phát hành, module apps/backend/src/modules/vc-anchor/ thực hiện neo bằng chứng bất biến lên Spores Blockchain:

1. Tạo Merkle Leaf (vc_anchor_leaves): Mỗi bản ghi VC mới sinh ra một leaf có hash leaf_hash = SHA256(canonical(vc_json)).
2. Merkle Batching (AnchorBatcherService — vc-anchor/batcher/anchor-batcher.service.ts): Định kỳ quét các leaves PENDING bằng câu lệnh UPDATE ... WHERE id IN (SELECT ... FOR UPDATE SKIP LOCKED), dựng Merkle Tree, tính merkle_root cùng merkle_proof cho từng leaf, lưu vào bảng vc_anchor_batches và gửi request (POST) sang Spores Anchor API (ký xác thực bằng khóa Ed25519 qua ed25519-canonical-signer.ts).
3. On-Chain Confirmation Webhook (SporesWebhookController & SporesWebhookGuard): Khi transaction đã được confirm trên blockchain, Spores gọi callback vào POST /api/v1/webhooks/spores. SporesWebhookGuard verify chữ ký Ed25519 trên req.rawBody và kiểm tra timestamp skew X-Timestamp, sau đó cập nhật tx_hash, block_number, anchored_at cho toàn bộ batch VC.