Zalo MiniApp Backend (apps/zalo-be) & Integration Gateway (apps/integration-gateway)

Ngoài Core Backend (apps/backend), hệ sinh thái Gotrace-portal còn bao gồm 2 NestJS microservices độc lập đóng vai trò mở rộng giao tiếp ra thiết bị di động (Zalo MiniApp) và đồng bộ dữ liệu với 12 cổng quốc gia/bộ ngành.

---

1. Kiến trúc Zalo MiniApp Backend (apps/zalo-be — Port :3002)

apps/zalo-be phục vụ Zalo MiniApp với API prefix /api/v1/zalo/*, được thiết kế xoay quanh cơ chế Multi-Role Identity Resolution trên cùng một tài khoản Zalo cá nhân.

1.1. Multi-Role Authentication Flow (DRIVER / ENTERPRISE / CONSUMER)

Rendering diagram...

1.2. Các Modules Nghiệp vụ trong apps/zalo-be

Module (apps/zalo-be/src/modules/*)	Endpoint chính (/api/v1/zalo/*)	Chức năng Nghiệp vụ
auth	/auth/login, /auth/enterprise-login, /auth/switch-role, /auth/refresh	Đăng nhập qua Zalo OAuth + Phone Token hoặc đăng nhập trực tiếp bằng tài khoản doanh nghiệp (enterprise-login), switch role động (switch-role) không cần re-login, quản lý Refresh Token trên Redis (RefreshTokenStore).
driver-shipments & drivers	/driver/shipments, /drivers	Dành cho Driver (DRIVER): Xem danh sách chuyến hàng được phân công, xác nhận nhận hàng xuất bến (kích hoạt ký VC CTE-SHIP), cập nhật lộ trình GPS, chụp ảnh minh chứng và ký biên bản bàn giao tại điểm đích.
enterprise-shipments & enterprise-batches	/enterprise/shipments, /enterprise/batches	Dành cho Enterprise / Cafeteria Staff (ENTERPRISE): Quét mã QR kiện hàng/SGTIN tại kho để xác nhận nhận hàng (kích hoạt ký VC CTE-RECEIVE), kiểm tra đối chiếu số lượng thực nhận và tra cứu nhanh batch.
buyer-confirmations & consumer	/buyer-confirmations, /consumer/*	Dành cho Buyer / Consumer (CONSUMER): Quét mã QR SGTIN để xác nhận đã mua sản phẩm chính hãng (sử dụng Row-Level Lock SELECT ... FROM sgtins WHERE sgtin_code = $1 FOR UPDATE chống race condition double-sell và kích hoạt ký VC CTE-SOLD), lưu lịch sử quét và gửi review.
zalo-webhook	/webhook (POST /api/v1/zalo/webhook)	Tuân thủ Nghị định 13/2023/NĐ-CP về Bảo vệ dữ liệu cá nhân (PDPD): Khi người dùng thu hồi quyền truy cập hoặc xóa tài khoản trên Zalo (user_revoked_consent), ZaloSignatureGuard verify chữ ký SHA-256 từ Zalo OA và ZaloWebhookService thực hiện anonymize PII (phone, name, avatar của Consumer), unlink zalo_user_id trên User/TransportDriver và revoke toàn bộ session trên Redis.

---

2. Kiến trúc Integration Gateway (apps/integration-gateway — Port :3003 / :3013)

apps/integration-gateway là event-driven gateway chuyên trách việc đồng bộ dữ liệu từ GoTrace/HanoiTrace ra 12 hệ thống bên ngoài (Cổng Truy xuất Nguồn gốc Quốc gia, NDA, các Bộ Ngành).

2.1. Dual HTTP Listeners (src/http/listeners.ts)

1. Public Listener (0.0.0.0:3003) — PublicController:
   • GET /health: Healthcheck endpoint (liveness/readiness).
   • POST /webhooks/:connectorCode: Nhận async callback/webhook từ các cổng quốc gia khi xử lý xong gói tin đồng bộ.
2. Internal Listener (127.0.0.1:3013) — InternalController + BullBoard:
   • Chỉ bind trên loopback interface (127.0.0.1) và bắt buộc xác thực header x-internal-key bằng hàm constant-time comparison crypto.timingSafeEqual trên SHA-256 digest (InternalAuthGuard).
   • Cung cấp Admin API cho apps/backend cấu hình credentials doanh nghiệp (dùng AES-256-GCM Envelope Encryption qua @gotrace/integration-crypto), bật/tắt connector, xem thống kê lỗi và trigger manual retry.

---

2.2. Transactional Outbox Relay & Per-Entity Ordering (ordering_key)

Rendering diagram...

2.3. Danh mục 12 Integration Connectors (apps/integration-gateway/src/connectors/*)

STT	Connector Code	Source Folder	Target System & Sync Scope
1	nda	connectors/nda/	Cổng định danh & xác thực quốc gia NDA (đồng bộ doanh nghiệp, sản phẩm GTIN, lô SGTIN).
2	national-trace	connectors/national-trace/	Cổng Thông tin Truy xuất Nguồn gốc Sản phẩm, Hàng hóa Quốc gia (Bộ KH&CN — Thông tư 02/2024/TT-BKHCN).
3	hanoitrace	connectors/hanoitrace/	Cổng dữ liệu liên thông Sở/Ngành TP. Hà Nội.
4	mard	connectors/mard/	Cổng dữ liệu Bộ Nông nghiệp và Phát triển Nông thôn (Nông-Lâm-Thủy sản, VietGAP, Kiểm dịch).
5	moit	connectors/moit/	Cổng dữ liệu Bộ Công Thương (Công nghiệp chế biến, lưu thông phân phối, chợ/siêu thị).
6	moh	connectors/moh/	Cổng dữ liệu Bộ Y tế / Cục An toàn Thực phẩm (Hồ sơ tự công bố, chứng nhận ATTP, bếp ăn).
7	most	connectors/most/	Cổng dữ liệu mã số mã vạch & tiêu chuẩn đo lường chất lượng (Bộ KH&CN / GS1 Việt Nam).
8	customs	connectors/customs/	Cổng thông tin tờ khai nhập khẩu & chứng từ vận đơn quốc tế.
9	vietqr	connectors/vietqr/	Tra cứu và đồng bộ thông tin pháp nhân doanh nghiệp theo Mã số thuế.
10	spores	connectors/spores/	Dịch vụ Merkle Tree Anchoring lên Spores Blockchain.
11	erp-webhook	connectors/erp-webhook/	Kết nối push/receive sự kiện chuẩn Webhook sang hệ thống ERP/WMS nội bộ của doanh nghiệp lớn.
12	sandbox	connectors/sandbox/	Mock/Sandbox connector phục vụ E2E integration testing và đào tạo.