Bắt đầu cho Developer

Hướng dẫn này đưa bạn từ con số không đến chạy được dịch vụ backend BANA đầu tiên ở môi trường cục bộ.

Yêu cầu Hệ thống

Công cụ	Phiên bản	Mục đích
Bun	>= 1.3.8	Runtime, trình quản lý package, test runner
PostgreSQL	>= 14	Cơ sở dữ liệu chính
Redis	>= 7	Cache, pub/sub, hàng đợi BullMQ
Lưu trữ tương thích S3	—	Lưu trữ asset (MinIO cho dev cục bộ)
Typesense	>= 0.25	Tìm kiếm full-text
Git	—	Quản lý phiên bản
glab	—	GitLab CLI cho MR (tùy chọn nhưng được khuyến nghị)

Chỉ dành cho phát triển POS desktop:

Rust + Tauri CLI

Clone & Cài đặt

bash

git clone ssh://git@git.nexpando.com:2268/eventry/nx-seller.git
cd nx-seller
make install        # bun install + cài đặt gateway portal
make setup-tools    # cấu hình git để dùng .githooks/

make install chạy bun install ở gốc workspace cộng với một lần cài đặt riêng cho gateway portal. make setup-tools thiết lập core.hooksPath để pre-commit hook của project chạy trên mọi commit.

Hạ tầng Cục bộ

Khởi động tất cả phụ thuộc bằng Docker Compose từ thư mục dev deployment:

bash

cd infrastructure/deployments/develop

# Phụ thuộc cốt lõi (PostgreSQL, Redis, Kafka, Typesense, MinIO)
docker compose -f services/docker-compose.yml up -d

# Pipeline CDC (Debezium: PostgreSQL -> Kafka -> Typesense)
docker compose -f cdc/docker-compose.yml up -d

Tạo database:

bash

psql -h localhost -U postgres -c "CREATE DATABASE nx_seller;"

Cấu hình Môi trường

Mỗi package backend dùng dotenv-flow. Sao chép file ví dụ để tạo cấu hình cục bộ của bạn:

bash

cp packages/identity/.env.development.example packages/identity/.env.development
cp packages/commerce/.env.development.example packages/commerce/.env.development
# lặp lại cho mỗi package bạn cần chạy

Tối thiểu, hãy xác minh các giá trị này trong mỗi .env.development:

Biến	Cần kiểm tra
`APP_ENV_POSTGRES_*`	Trỏ đến PostgreSQL cục bộ của bạn
`APP_ENV_CACHE_REDIS_*`	Trỏ đến Redis cục bộ của bạn
`APP_ENV_SERVER_PORT`	Không có xung đột cổng giữa các dịch vụ
`APP_ENV_IDENTITY_SERVICE_BASE_URL`	Trỏ đến dịch vụ identity đang chạy

Xem Tham khảo Biến Môi trường để có danh mục biến đầy đủ.

Build

Monorepo có thứ tự build nghiêm ngặt vì các package phụ thuộc lẫn nhau. Makefile xử lý điều này:

bash

make build    # build tất cả theo đúng thứ tự phụ thuộc

Lệnh này chạy build-3rd (tích hợp bên thứ ba) rồi build-packages (tất cả package backend) theo thứ tự phụ thuộc:

core → asset, search, identity, inventory, finance, ledger, pricing, taxation, outreach, signal, sale
     → commerce (phụ thuộc asset + search)
     → payment (phụ thuộc core + mq-pay)

Để build một package riêng (cùng các phụ thuộc của nó):

bash

make identity    # build core → mq-sms → identity
make commerce    # build core → asset → search → commerce

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

Đừng bao giờ chạy tsc hay npx trực tiếp. Các script build xử lý việc giải quyết path alias (tsc-alias) mà việc biên dịch TypeScript thuần sẽ bỏ sót.

Chạy Migration

Migration được chạy theo từng package. Package core sở hữu các schema database dùng chung:

bash

# 1. Schema core trước (public, pricing, allocation, sale, inventory, finance, payment)
make db-migrate-all

# 2. Dữ liệu seed theo từng package (quyền, cấu hình mặc định)
cd packages/identity && bun run migrate:dev
cd ../commerce && bun run migrate:dev
cd ../sale && bun run migrate:dev
# ... lặp lại cho mỗi package bạn cần

Hoặc migrate một schema cụ thể:

bash

make db-migrate schema=public
make db-migrate schema=pricing
make db-migrate schema=inventory

Chạy Dịch vụ Đầu tiên của Bạn

Identity là điểm khởi đầu tốt nhất — tất cả các dịch vụ khác đều phụ thuộc vào nó để xác thực JWT.

bash

make dev-identity

Lệnh này khởi động dịch vụ identity ở cổng 31010. Xác minh nó đang chạy:

bash

curl http://localhost:31010/v1/api/identity/health
# Sẽ trả về { "status": "ok" }

curl http://localhost:31010/v1/api/identity/jw-certs
# Sẽ trả về các public key JWKS

Sau đó khởi động các dịch vụ khác khi cần:

bash

make dev-commerce    # cổng 31020
make dev-sale        # cổng 31030
make dev-finance     # cổng 31040
make dev-pricing     # cổng 31070

Mỗi dịch vụ phơi bày một Swagger UI tại base URL của nó (ví dụ http://localhost:31020/v1/api/commerce).

Danh mục Dịch vụ

Dịch vụ	Mã	Cổng	Snowflake ID	Base Path
identity	`SVC-00010`	31010	1	`/v1/api/identity`
commerce	`SVC-00020`	31020	2	`/v1/api/commerce`
sale	`SVC-00030`	31030	3	`/v1/api/sale`
finance	`SVC-00040`	31040	4	`/v1/api/finance`
inventory	`SVC-00050`	31050	5	`/v1/api/inventory`
ledger	`SVC-00060`	31060	6	`/v1/api/ledger`
pricing	`SVC-00070`	31070	7	`/v1/api/pricing`
payment	`SVC-00080`	31080	8	`/v1/api/payment`
signal	`SVC-00090`	31090	9	`/v1/api/signal`
outreach	`SVC-00100`	31110	10	`/v1/api/outreach`
licensing	`SVC-00110`	31120	11	`/v1/api/licensing`
taxation	`SVC-00130`	31130	13	`/v1/api/taxation`

Chạy App Frontend

bash

make dev-client      # Admin dashboard — http://localhost:5173
make dev-bo          # Back office — http://localhost:5174
make dev-overture    # Marketing site — http://localhost:4321
make dev-wiki        # Tài liệu này — http://localhost:5175

Ứng dụng POS desktop yêu cầu Tauri:

bash

cd apps/sale-main
cargo tauri dev

Chạy Test

bash

# Unit test theo từng package (không cần DB)
cd packages/licensing
bun run test:unit

# Toàn bộ test suite theo từng package (có thể cần .env.test + DB)
bun run test

Chạy Lint

bash

make lint            # lint tất cả (apps + packages + third-parties + docs)
make lint-identity   # lint một package
make lint-app-client # lint một app

Không có lỗi lint

Lỗi lint là cổng cứng — mỗi commit và MR phải vượt qua make lint với không có lỗi nào. Chạy bun run lint:fix trong package bị ảnh hưởng để tự động sửa hầu hết các vấn đề.

Script Phổ biến (Theo từng Package)

Mỗi package backend đều có cùng giao diện script:

Script	Mục đích
`bun run rebuild`	Clean + compile (luôn dùng cái này)
`bun run server:dev`	Dev server với `.env.development`
`bun run server:local`	Dev server với `.env.local`
`bun run migrate:dev`	Chạy migration
`bun run test`	Toàn bộ test suite
`bun run test:unit`	Chỉ unit test (nếu được cấu hình)
`bun run lint:fix`	ESLint + Prettier tự động sửa

Bước Tiếp theo

Chủ đề	Trang
Tất cả target Makefile	Hệ thống Build
Biến môi trường	Tham khảo Biến Môi trường
Quy trình Git & MR	Quy trình Git
Pattern framework IGNIS	IGNIS Patterns
Package backend	Tổng quan Packages
App frontend	Tổng quan Apps

Client Guide

Nhà cung cấp

Các loại Hóa đơn

Bắt đầu cho Developer ​

Yêu cầu Hệ thống ​

Clone & Cài đặt ​

Hạ tầng Cục bộ ​

Cấu hình Môi trường ​

Build ​

Chạy Migration ​

Chạy Dịch vụ Đầu tiên của Bạn ​

Danh mục Dịch vụ ​

Chạy App Frontend ​

Chạy Test ​

Chạy Lint ​

Script Phổ biến (Theo từng Package) ​

Bước Tiếp theo ​

Bắt đầu cho Developer

Yêu cầu Hệ thống

Clone & Cài đặt

Hạ tầng Cục bộ

Cấu hình Môi trường

Build

Chạy Migration

Chạy Dịch vụ Đầu tiên của Bạn

Danh mục Dịch vụ

Chạy App Frontend

Chạy Test

Chạy Lint

Script Phổ biến (Theo từng Package)

Bước Tiếp theo