Hệ thống Build

Monorepo được điều phối bởi Makefile ở thư mục gốc (~750 dòng). Tất cả các tác vụ build, lint, dev, deploy và database đều được thực hiện thông qua nó.

Chạy make help để xem danh sách target đầy đủ.

Đồ thị Phụ thuộc Package

make build chạy build-3rd trước, sau đó là build-packages theo thứ tự ở trên.

Cài đặt

Target	Lệnh	Mục đích
make install	bun install + cài đặt gateway portal	Cài đặt tất cả dependencies của workspace
make clean	bun run --filter "*" clean	Xóa dist/ từ tất cả các package
make purge	find . -name node_modules -exec rm -rf	Xóa tất cả node_modules (lựa chọn triệt để)
make setup-tools	git config core.hooksPath .githooks	Bật git hooks của project
make rebuild	purge → clean → install → build	Rebuild sạch hoàn toàn từ đầu

Target Build

Tổng hợp

Target	Build cái gì
make build	Mọi thứ (alias của build-all)
make build-all	build-3rd rồi build-packages
make build-packages	Tất cả packages/* theo thứ tự phụ thuộc
make build-3rd	Tất cả third-parties/* (iiapi, mq-pay, mq-sms, t-van)

Package riêng lẻ

Mỗi target tự động build các phụ thuộc của nó trước (qua các prerequisite của Makefile).

Target	Phụ thuộc	Package
make core	—	@nx/core
make asset	core	@nx/asset
make search	core	@nx/search
make identity	core, mq-sms	@nx/identity
make inventory	core	@nx/inventory
make finance	core	@nx/finance
make outreach	core	@nx/outreach
make ledger	core, asset	@nx/ledger
make pricing	core	@nx/pricing
make taxation	core	@nx/taxation
make commerce	asset, search	@nx/commerce
make sale	core	@nx/sale
make payment	core, mq-pay	@nx/payment
make signal	core	@nx/signal
make licensing	core	@nx/licensing

Third-parties

Target	Package
make iiapi	@nx/iiapi
make mq-pay	@nx/mq-pay
make mq-sms	@nx/mq-sms
make t-van	@nx/t-van

App Frontend

Target	Package
make bo	@nx-app/bo
make client	@nx-app/client
make overture	@nx-app/overture
make app-core	@nx-app/core

Các build frontend chạy bun run apps:rebuild trước (build lại các thư viện app dùng chung), sau đó là build riêng cho app.

Cơ chế Build Bên trong Mỗi Package

Mỗi package backend đều có script build giống hệt nhau:

bun run rebuild     # → scripts/rebuild.sh → clean.sh + compile.sh
bun run build       # → scripts/build.sh
bun run compile     # → scripts/compile.sh (tsc + tsc-alias)
bun run clean       # → scripts/clean.sh (rm -rf dist/)

Luôn dùng bun run rebuild hoặc make <pkg>

Đừng bao giờ gọi tsc hay npx trực tiếp. Build sử dụng tsc-alias để giải quyết các path alias như @/services thành đường dẫn tương đối trong output đã biên dịch. tsc thuần sẽ tạo ra các import bị hỏng.

Compile (Binary Độc lập)

Bun có thể biên dịch các dịch vụ thành các file thực thi đơn:

Target	Build trước	Output
make compile-commerce	commerce	packages/commerce/dist/bin/
make compile-finance	finance	packages/finance/dist/bin/
make compile-identity	identity	packages/identity/dist/bin/
make compile-inventory	inventory	packages/inventory/dist/bin/
make compile-payment	payment	packages/payment/dist/bin/
make compile-pricing	pricing	packages/pricing/dist/bin/
make compile-sale	sale	packages/sale/dist/bin/
make compile-signal	signal	packages/signal/dist/bin/
make compile-ledger	ledger	packages/ledger/dist/bin/
make compile-licensing	licensing	packages/licensing/dist/bin/
make compile-outreach	outreach	packages/outreach/dist/bin/

Docker

Build Docker image để triển khai:

# Phiên bản hiện tại
make docker pkg=identity

# Tăng phiên bản patch (0.0.1 → 0.0.2) rồi build
make docker pkg=identity v=patch

# Đặt phiên bản cụ thể
make docker pkg=identity v=0.2.0

# Tăng prerelease (0.0.1 → 0.0.1-1)
make docker pkg=identity v=pre

# Build chỉ với tag (không thay đổi package.json)
make docker pkg=identity tag=0.0.1-2

# Build TẤT CẢ image
make docker-all

Tên package có sẵn: identity, commerce, sale, finance, inventory, ledger, payment, pricing, signal.

Script build nằm tại scripts/build-docker.sh. Image được push lên container registry của project.

Lint

Target	Phạm vi
make lint	Mọi thứ (alias của lint-all)
make lint-all	lint-apps + lint-packages + lint-3rd + lint-docs
make lint-apps	Tất cả apps/*
make lint-packages	Tất cả packages/*
make lint-3rd	Tất cả third-parties/*
make lint-docs	Tất cả docs/*
make lint-wiki	Chỉ @nexpando/eventry-docs
make lint-packages-fix	Tự động sửa tất cả package
make lint-<package>	Một package (ví dụ lint-identity, lint-commerce)
make lint-app-<app>	Một app (ví dụ lint-app-client, lint-app-bo)

Dùng --elide-lines=0 để có output chi tiết (Makefile đã làm điều này cho các target lint-packages và dev-*).

Dev Server

Target	Dịch vụ	Cổng
make dev-identity	Identity	31010
make dev-commerce	Commerce	31020
make dev-sale	Sale	31030
make dev-finance	Finance	31040
make dev-inventory	Inventory	31050
make dev-ledger	Ledger	31060
make dev-pricing	Pricing	31070
make dev-payment	Payment	31080
make dev-signal	Signal	31090
make dev-outreach	Outreach	31110
make dev-taxation	Taxation	31130
make dev-bo	Back Office	5174
make dev-client	Admin Dashboard	5173
make dev-overture	Marketing Site	4321
make dev-portal	Gateway Portal	—
make dev-wiki	Tài liệu này	5175

Cơ sở Dữ liệu

Target	Cách dùng
make db-generate schema=<name>	Tạo SQL migration cho một schema
make db-generate-all	Tạo migration cho tất cả 8 schema
make db-migrate schema=<name>	Áp dụng migration cho một schema
make db-migrate-all	Áp dụng migration cho tất cả schema
make db-migrate-package-dev package=<name>	Chạy migration mức package ở chế độ dev
make db-migrate-ledger-dev	Lối tắt cho migration ledger ở dev

Tên schema: public, pricing, allocation, sale, inventory, finance, payment, ledger

Các lệnh database chạy trong packages/core — nơi sở hữu các định nghĩa schema Drizzle ORM dùng chung.

Deploy (Dev Server)

Target	Triển khai
make deploy-dev-deps	Các phụ thuộc hạ tầng
make deploy-dev-gateway	Traefik gateway
make deploy-dev-backend-services	Tất cả các dịch vụ backend (identity tới licensing)
make deploy-dev-<service>	Dịch vụ riêng lẻ (ví dụ deploy-dev-identity)
make deploy-dev-client	Admin dashboard
make deploy-dev-bo	Back office
make deploy-dev-overture	Marketing site
make deploy-dev-wiki	Tài liệu
make deploy-dev-prototypes	Prototype thiết kế

Script deploy nằm trong infrastructure/deployments/develop/scripts/.

Benchmark

Target	Mục đích
make benchmark-ledger	Chạy benchmark tạo PDF + XLSX cho cả 6 loại ledger

Git Hooks

Target	Mục đích
make setup-tools	Cấu hình git để dùng .githooks/
make pre-commit	Chạy tất cả các kiểm tra lint (dùng bởi pre-commit hook)

Trang Liên quan

Trang	Mô tả
Bắt đầu	Hướng dẫn cài đặt lần đầu
Tham khảo Biến Môi trường	Tất cả biến môi trường
Quy trình Git	Đặt tên nhánh, commit, MR