Agri Trace Blockchain

Monorepo cho hệ thống truy xuất nguồn gốc nông sản, tổng hợp frontend, backend và Hyperledger Fabric trong một cấu trúc thống nhất.

Không gian doanh nghiệp hiện có đăng ký năm bước, xét duyệt, thành viên cấp 1–2–3, nhóm quyền, liên kết, danh mục riêng, cơ sở/phương tiện và các trang vụ/nhật ký/thu hoạch độc lập. Phân phối giữ nguyên lô nguồn, hỗ trợ nhiều dòng, nhiều chặng, lượng giao từng phần, ký hai phía và báo cáo đối soát; xem nghiệp vụ và các route giao diện. Luồng phân phối mới chưa mở cho binding bắt buộc signed intent c2; các chuỗi đó giữ luồng Shipment đã ký hiện hành cho đến khi có integration/acceptance riêng. Kiểm thử local không phải nghiệm thu Fabric hoặc quyền của doanh nghiệp thật.

Bản Hybrid A/B/C thực hiện theo kế hoạch cài mới production. Đọc PROJECT_CONTEXT, quy tắc nghiệp vụ, ADR-004 và runbook production. CI/source completion và nghiệm thu runtime là các cổng riêng; kiểm SHA/receipt trong PR và controller state.

Cấu trúc

Hybrid A phân quyền theo chuỗi; B pin binding/authority/permission epoch và ledger registry; C dùng khóa Ed25519 tổ chức và bàn giao hai bên. Chữ ký độc lập bắt buộc ở bàn giao khác tổ chức; care/harvest giữ xác thực hiện hành. Một mạng có channel theo nhóm hợp tác. Hosted technical identities không chứng minh quyền của đối tác bên ngoài; external partner authority vẫn NotEvaluated, không tuyên bố HA.

apps/
  api/                 NestJS API + dedicated blockchain worker entrypoint
  web/                 Next.js PWA
blockchain/
  chaincode/           Smart contract Hyperledger Fabric
  gateway/             Adapter kết nối Fabric Gateway
  network/             Script dựng mạng Fabric local
docs/
  archive/business-specification-v1.2.md
  adr-001-modular-monolith-dedicated-worker.md

Các file cấu hình ở gốc được chia theo nơi sử dụng:

Nhóm file	Mục đích
docker-compose.yml, .env.docker.example	Chạy ứng dụng local, kèm service ledger-simulator gắn binding giả lập vì local không chạy Fabric
docker-compose.app.yml, .env.deploy.example	Ứng dụng production dùng image đã pin qua CD
docker-compose.app-hybrid.yml	Overlay kết nối mạng hosted của production (config schema 3)
deploy/ci/, deploy/cd/, deploy/edge/	Rehearsal production trong CI; controller, installer và đóng gói CD; Edge (Caddy) dùng chung
package.json, package-lock.json, các file .git* và .dockerignore	Lệnh, dependency lock và cấu hình công cụ

Controller chỉ nhận config schema 3, manifest format 2 và release prod-*; nó ghép docker-compose.app.yml và docker-compose.app-hybrid.yml. Overlay signer/network cũ docker-compose.app-fabric.yml đã bỏ cùng luồng ghi bản A; manifest app delivery chỉ bắt buộc docker-compose.app.yml. Controller đã cài trên VPS phải được cập nhật theo quy trình digest trước release đầu tiên không còn file này. hybrid-floor.json chỉ cho rollback tới image verified tương thích migration.

Mọi sự kiện truy xuất đi qua binding Fabric của chuỗi (bản B, bản C có chữ ký c2). Luồng ghi bản A (route chung, envelope 3.0.0) và giao thức chữ ký c1 đã gỡ khỏi API, Worker, chaincode và Gateway; migration 20261213000000_retire_release_a_and_c1 từ chối database còn dữ liệu A/c1. Xem kế hoạch gỡ.

Môi trường UAT cũ (schema 2, project agri-trace-uat) đã retire: stack, bootstrap và mẫu môi trường của nó không còn trong repo. Application CI kiểm ứng dụng bằng docker-compose.app.yml trong job Production rehearsal (deploy/ci/). Xem runbook production.

Cài đặt

Yêu cầu Node.js 24.22.1 (xem .node-version) và npm 12.1.0. npm cũ có thể bỏ qua overrides của dependency trong workspace. Từ thư mục gốc:

node --version # v24.22.1; dùng phiên bản trong .node-version
npm install --global [email protected]
npm ci

Tạo file môi trường từ các mẫu trong apps/api/.env.example, apps/web/.env.example và blockchain/network/.env.example khi chạy từng phần.

Làm việc với Claude Code và Codex

Hai công cụ dùng chung AGENTS.md và năm skill nguồn trong .agents/skills. CLAUDE.md import hướng dẫn chung; .claude/skills là bản sinh đã commit, không sửa riêng. Xem guide agent cho trigger, discovery và review. Model, permissions và MCP kế thừa phiên hiện có; không có hook tự chạy.

Sau khi sửa nguồn skill, dùng Node/npm hỗ trợ, Python 3.11+ và Git:

npm run agents:sync
npm run agents:check
npm run test:agents

Checker không cần database hoặc Fabric. Lỗi đồng bộ/config/reference/Git ignore chặn Application gate; schema pass chưa chứng minh client thực đã nạp hướng dẫn. Giữ evidence, worktree, launch config và settings local ngoài commit.

Chạy ứng dụng

npm run dev:web
npm run dev:api
npm run dev:worker

Frontend chạy ở http://localhost:3000; API chạy ở http://localhost:8080/api. Trang / giới thiệu AgriTrace bằng tiếng Việt và cung cấp tra cứu QR công khai. Truy cập trực tiếp /login để đăng nhập; sau đăng nhập mở /dashboard. Trang giới thiệu không có liên kết đăng nhập hoặc lô/QR mẫu. Doanh nghiệp vào /register (chọn vai trò, năm bước, OTP email đăng nhập; mật khẩu tạm gửi qua email), theo dõi hồ sơ ở /enterprise/onboarding. Admin duyệt trước; doanh nghiệp chọn mô hình peer và gói tham khảo tại /enterprise/service, xem hợp đồng ở /enterprise/service/contract, hoàn tất thanh toán mô phỏng local ở /enterprise/service/payment; thao tác này chỉ ghi nhận PAID_SIMULATED và xếp hàng email hợp đồng. Quản trị nền tảng phải kích hoạt dịch vụ riêng trước khi cấp quyền nghiệp vụ hoặc cho phép yêu cầu peer tại /enterprise/connections. Hợp đồng và kết quả xét duyệt gửi bằng Worker mail; SMTP dùng file private, test dùng Mailpit. Chưa tích hợp thu tiền NAPAS/QR hoặc chữ ký số hợp đồng có chứng thư. Quản trị xét duyệt tại /admin/enterprises. API và Worker mặc định đóng admission (ENTERPRISE_ONBOARDING_ENABLED=false). Demo cách ly bật true ở cả hai process; xem kế hoạch v1 và hướng dẫn kết nối. Xem frontend và bố cục mobile để kiểm tra giao diện.

Frontend mặc định kết nối backend thật. Worker là process độc lập; chỉ worker được cấp Fabric signing identity.

Chạy bằng Docker Compose

Sao chép .env.docker.example thành .env.docker, thay toàn bộ secret mẫu rồi chạy:

docker compose --env-file .env.docker up --build

PostgreSQL 18 dùng volume tại /var/lib/postgresql. Volume đã khởi tạo bằng PostgreSQL 16 cần quy trình chuyển dữ liệu hoặc tạo mới có ủy quyền; thay tag image không tự nâng định dạng dữ liệu. Xem runbook database.

Compose khởi động PostgreSQL 18, API, Dedicated Worker và Web. Stack local mở ghi nghiệp vụ qua HYBRID_WRITES_MODE=OPEN (mặc định trong docker-compose.yml); đặt CLOSED trong .env.docker để thử chế độ bảo trì. Production không dùng file này: controller giữ ghi đóng đến khi bản phát hành được xác minh. API vẫn hoạt động khi Fabric hoặc Worker tạm dừng; các sự kiện chờ được giữ trong blockchain_outbox. Worker health chỉ mở trong Docker network tại http://worker:8081/health/ready.

Triển khai production

main là nguồn triển khai duy nhất vào agritrace.dev. Không còn target dev, dev CD, profile light hoặc route nongtrace.site. CI kiểm PR vào main và mọi push lên main; database/Fabric thử nghiệm dùng local hoặc runner cách ly.

Vận hành theo runbook production. Cài mới dùng schema-3 controller, project agritrace-prod, PostgreSQL agri_trace_prod và mạng hosted mới sau encrypted backup + isolated restore. Dữ liệu trước đó đều là test, được giữ trong bản lưu; không backfill account/history/proof/QR vào production mới. Ngoại lệ cài lại được chủ dự án chọn ngày 24/10/2026 bỏ dataset cũ không backup, gom ba Org về VPS nền tảng và gỡ Fabric cũ trên VPS doanh nghiệp. Operation reinstall cần target rỗng và root receipt đúng SHA/manifest/generation; xem quy trình cài lại.

Migration A/B/C giữ byte nguyên vẹn; 20261017000000_hybrid_fresh_install chỉ cleanup khi chưa có business history và từ chối trường hợp đã có dữ liệu. New cycle cần ACTIVE binding; không tạo legacy fallback. Domain/journal/trace/outbox và quyền/version/idempotency vẫn cùng transaction. Admin/Auditor không ghi thay business actors.

API không có signing key. Worker nhận technical identity read-only; owner MSP chỉ dùng trong one-off operator. Production bootstrap chỉ dùng cấu hình riêng tư. Sau build, operator chạy node dist/operator/ledger-operator.js, signer độc lập chạy node dist/operator/org-signer.js, và restore checker chạy node dist/operator/verify-evidence.js từ apps/api.

Thay đổi đi qua PR; chủ dự án quyết định merge và thời điểm triển khai. Push vào main có đường dẫn thuộc bộ lọc trong .github/workflows/production-cd.yml tự kích hoạt Production CD. PR chỉ sửa README gốc, docs/ (ngoài docs/openapi/) và .gitignore không kích hoạt CD; README dưới apps/ hoặc blockchain/ vẫn thuộc bộ lọc CD. Không coi CI xanh là quyền tự merge hoặc deploy.

Khi triển khai được duyệt, giữ smoke thực trên VPS theo runbook. Không đặt maintenance deadline 2 giờ, canary riêng, collector/systemd timer hoặc quan sát liên tục 24 giờ; sự cố sau bàn giao do chủ dự án vận hành.

Seed đầy đủ trên database local hiện tại

Quy trình tại kế hoạch seed chỉ dành cho stack local agri-trace-demo-local, database agri_trace cổng 5433. Nó thay toàn bộ dữ liệu sau backup; không tạo database khác. Các tài khoản, khóa ký demo, khóa mã hóa local, checkpoint và backup nằm trong .codex/, không commit hoặc gửi chúng ra ngoài. Ảnh chụp kèm nguồn và giấy phép nằm trong scripts/demo/assets/manifest.json; giấy tờ có nhãn DEMO, không có giá trị pháp lý.

# Chuẩn bị: build API/Gateway theo hướng dẫn kiểm tra bên dưới; stack local đang chạy.
python scripts/demo/prepare-assets.py
# Tạo tài liệu demo theo prepare-documents.py (cần reportlab, pypdf và pdftoppm).
./scripts/demo/seed-current.ps1                    # Chỉ xác minh target
./scripts/demo/seed-current.ps1 -ReplaceCurrentData # Backup rồi thay dữ liệu một lần
./scripts/demo/seed-current.ps1 -Resume             # Tiếp tục checkpoint, không reset lại
./scripts/demo/seed-current.ps1 -Verify             # Kiểm DB, quyền và đăng nhập thật
node scripts/demo/verify-browser.mjs

Seed giữ nguyên schema/guard từ snapshot trong chính DB này, giữ catalog hệ thống và migration catalog; không tắt trigger. Để dùng dữ liệu quyền riêng tư, helper tạo khóa mã hóa local và Compose override riêng, pin đúng API image đang chạy. Khi kiểm tra đạt, khởi động lại Web/Worker đã dừng. Credential nằm ở .codex/seed-current/accounts.json; receipt và đường dẫn backup ở cùng thư mục. -Restore kiểm checksum và phục hồi snapshot trước seed vào chính DB đó sau khi dừng writer. Không coi backup DB local là bằng chứng khôi phục production/Fabric.

Kiểm tra toàn bộ

Swagger sinh từ NestJS là contract. Sau npm ci, sinh Prisma client và build Gateway trước khi xuất OpenAPI/kiểu TypeScript cho Web:

npm run prisma:generate --workspace apps/api
npm run build --workspace blockchain/gateway
npm run api-contract:generate
npm run api-contract:check

Exporter dùng metadata đã compile và cấu hình riêng, không mở listener hoặc kết nối database/Fabric. Kết quả nằm trong docs/openapi/openapi.json, checksum docs/openapi/openapi.sha256 và apps/web/src/lib/generated/api.d.ts; sửa DTO/decorator NestJS rồi sinh lại, không sửa trực tiếp file sinh. CI API chặn contract lệch và schema public lộ các field nội bộ đã liệt kê trong generator.

npm run check

Lệnh trên chạy test logic CI/CD, rồi lint, typecheck, unit/e2e test và build tương ứng cho các workspace. Lint API/Web chặn cả warning; build Web chạy lint. Test ràng buộc và nghiệp vụ PostgreSQL cần TEST_DATABASE_URL trỏ đến database test riêng đã chạy migration; thiếu hoặc để rỗng biến này thì E2E từ chối chạy. Không đặt TEST_DATABASE_URL thành database production. Để chạy riêng một phần:

npm run check --workspace apps/web
npm run check --workspace apps/api
npm run check --workspace blockchain/chaincode
npm run check --workspace blockchain/gateway

Web chạy ESLint cho React/TypeScript/accessibility và Oxlint cho các rule Next.js. npm run build --workspace apps/web chạy cả hai trước khi biên dịch; check còn kiểm tra hợp đồng lint và xác nhận build bị chặn khi có warning hoặc lỗi.

PR chọn job theo phạm vi thay đổi; mọi push lên main chạy đầy đủ để CD dùng bằng chứng của đúng SHA. Xem chính sách CI và báo cáo kiểm tra CI/clean code.

Mạng Fabric local cần thêm Docker; xem script trong blockchain/network.

Mô hình dữ liệu core hiện tại tách rõ ProductionCycle, HarvestEvent, Lot và Shipment. Tài liệu docs/archive/business-specification-v1.2.md chỉ còn là baseline lịch sử; Prisma schema được đồng bộ với database PostgreSQL agri_traceDB tại apps/api/prisma/schema.prisma.

Audit dependency

Kiểm tra root và package chaincode độc lập trong các môi trường cài tách riêng:

npm ci
npm run audit:dependencies
npm run check:chaincode:standalone

Các lệnh ghi audit đầy đủ, audit production, kiểm tra peer dependency và metadata (ngày, SHA checkout, Node/npm, SHA-256 lockfile) vào .codex/evidence/dependencies. Kiểm tra standalone sao chép nguồn/config và hai file package của chaincode vào thư mục tạm, cài theo lockfile riêng, audit và chạy check, rồi dọn thư mục tạm. Manifest/lockfile trong thư mục cài phải khớp byte với checkout nguồn. Cách này giữ graph root ổn định khi chaincode cũng là workspace của monorepo. High/moderate làm lệnh thất bại. CI lưu cùng bằng chứng dưới dạng artifact cho workspace và chaincode độc lập. Xem báo cáo AGT-002.