5-Layer Supply Chain Data Platform Architecture

Dựa trên đặc tả kiến trúc tại docs/technical/TECH_ARCHITECTURE_5LAYER.md và implementation trong codebase Gotrace-portal, toàn bộ hệ thống được thiết kế xoay quanh 5-Layer Supply Chain Data Architecture tuân thủ tiêu chuẩn quốc gia TCVN 12850:2019, Thông tư 02/2024/TT-BKHCN, GS1 EPCIS 2.0, và Hệ thống ngành kinh tế Việt Nam VSIC 2025 (QĐ 36/2025/QĐ-TTg).

---

1. Sơ đồ Kiến trúc 5-Layer Data Platform

Rendering diagram...

---

2. Phân tích Chi tiết Từng Layer trong Codebase

Layer 1: Multi-Channel Data Capture Layer

Layer 1 giải quyết bài toán thu thập dữ liệu từ thực địa vào hệ thống với chi phí thao tác thấp nhất:

• Unified Import/Export Engine (TXNG-F49 — src/common/import-export/): Hệ thống xây dựng một Import/Export Engine dùng chung (ModuleImportExportService, ExcelBuilderService, ImportRunnerService, ReferenceResolverService). Mọi module (Product, Material, Input Source, Raw Material Zone, Warehouse, Facility, Personnel...) đều tự động sinh file Excel template kèm sheet "Ghi chú giá trị" kết xuất từ master data thực tế của đúng tenant đó, validate từng dòng/cột và cho phép xuất lại file lỗi (export-errors) để người dùng sửa trực tiếp.
• Field Data Capture qua Zalo MiniApp (apps/zalo-be): Tài xế chụp ảnh/ký nhận biên bản giao hàng (driver-shipments), nhân viên kho quét mã SGTIN xuất/nhập (enterprise-shipments), người mua xác nhận đã nhận hàng (buyer-confirmations).
• Smart Column Mapping & Onboarding (src/modules/import-onboarding/): Cho phép doanh nghiệp lưu lại mapping template (ImportMappingTemplate) ánh xạ cột từ file Excel nội bộ của họ sang schema chuẩn của GoTrace.

---

Layer 2: Standardization & Master Data Layer

Mọi dữ liệu thô từ Layer 1 khi đi vào hệ thống đều được chuẩn hóa theo bộ khung định danh quốc tế và quốc gia:

• Dual-Axis Multi-Industry Classification (TXNG-F41):
  • Trục Ngành kinh tế Việt Nam (Industry): Ánh xạ theo mã VSIC 2025 (vsic_code, industry_group_code).
  • Trục Phân loại Sản phẩm Toàn cầu GS1 GPC (Segment → Family → Class → Brick): Phân cấp 4 tầng chuẩn GS1 Global Product Classification.
• Dynamic Attribute Templates (AttributeTemplate & AttributeDefinition — src/modules/attribute-templates/): Mỗi ngành nghề (Industry) gắn với một default_template_id. Khi doanh nghiệp khai báo Input Source (InputSource) thuộc ngành Trồng trọt, Chăn nuôi, Thủy sản, Dược phẩm hay Điện tử, AttributeValidationService (src/modules/input-sources/attribute-validation.service.ts) sẽ tự động validate kiểu dữ liệu (STRING, NUMBER, DATE, BOOLEAN, SELECT), đơn vị tính và tính bắt buộc của từng dynamic attribute lưu trong cột JSONB attributes.
• GS1 Identification Standards (Gtin, Sgtin, PackagingUnit): Chuẩn hóa Global Company Prefix (GCP), Global Trade Item Number (GTIN-14 / nda_gtin_code), Serialized GTIN (SGTIN), và Serial Shipping Container Code (SSCC).

---

Layer 3: Traceability Graph & Cryptographic Trust Layer

Thay vì chỉ lưu thông tin tĩnh của sản phẩm, Layer 3 liên kết các thực thể thành một Directed Acyclic Graph (DAG):

• Input–Output Lineage Link (PlanInputLink — src/modules/plan-input-links/): Nối kết nguyên liệu (Material), nguồn đầu vào (InputSource), hoặc lô bán thành phẩm (Batch) từ đơn mua hàng (PurchaseOrder) vào kế hoạch sản xuất (ProductionPlan) và lô thành phẩm (Batch), kèm cơ chế Row-Level Lock (FOR NO KEY UPDATE / FOR UPDATE OF wi) để chống xuất âm tồn kho khi nhiều luồng tạo batch đồng thời.
• Immutable Movement Ledger (SgtinMovement — src/modules/sgtin-ledger/): Ghi lại mọi bước chuyển trạng thái vòng đời của từng tem SGTIN. Bảng sgtin_movements được bảo vệ bởi PostgreSQL Trigger trg_sgtin_movements_no_update chặn mọi câu lệnh UPDATE hoặc DELETE trái phép.
• W3C Verifiable Credentials & Blockchain Anchoring (src/modules/vc/ & src/modules/vc-anchor/): Mỗi sự kiện trọng yếu (CTE) sinh ra một bản ghi W3C VC được ký bằng khóa riêng Ed25519 của Decentralized Identifier (did:web / did:key) thuộc doanh nghiệp, sau đó gom vào Merkle Tree để anchor lên Spores Blockchain.

---

Layer 4: Intelligence & Quality Layer

Layer 4 biến dữ liệu truy xuất thành công cụ phân tích tự động và kiểm soát rủi ro:

• Nutrition Engine (src/modules/nutrition-engine/): Tính toán hàm lượng dinh dưỡng của từng công thức món ăn (MenuRecipe) và thực đơn ngày/tuần (MenuPlan) dựa trên tỷ lệ phần ăn được (edible_portion), hệ số giữ lại dưỡng chất qua chế biến (retention_factor), đối chiếu với chuẩn nhu cầu dinh dưỡng khuyến nghị (RDA) theo từng lứa tuổi học sinh để đưa ra gợi ý điều chỉnh tự động.
• Cost Reconciliation Engine (src/modules/cost-reconciliations/, finance-ledgers/): So sánh chi phí định mức (MealCostNorm), bảng tính chi phí dự kiến (MealCostSheet) và sổ thu/chi thực tế (FinanceLedger), phát hiện chênh lệch vượt ngưỡng (FinanceThreshold).
• Alert Rule Engine (src/modules/alerts/rule-engine/): Tự động kích hoạt cảnh báo (Alert, OversightAlert) khi phát hiện chứng nhận hết hạn, lô hàng bị recall, vi phạm nhiệt độ/thời gian vận chuyển, hoặc phản ánh tiêu cực từ phụ huynh/người tiêu dùng vượt ngưỡng.

---

Layer 5: Data Sharing & Disclosure Layer

• Public QR Trace & Disclosure (src/modules/public-trace/, public-menu-trace/, cost-disclosures/): Cung cấp thông tin minh bạch cho người tiêu dùng và phụ huynh học sinh khi quét mã QR (hỗ trợ đa ngôn ngữ và che thông tin nhạy cảm B2B theo cấu hình PublicPortalConfig).
• National Gateway Synchronization (apps/integration-gateway): Đồng bộ dữ liệu chuẩn hóa lên 12 cổng dữ liệu quốc gia và bộ ngành theo kiến trúc chịu lỗi cao (Transactional Outbox + Exponential Backoff + Circuit Breaker).