Configuration

1. Biến môi trường

Khoá core kế thừa từ EnvironmentKeys của @nx/core; khoá riêng ledger trong src/common/environments.ts.

Core (chọn lọc)

Tên	Kiểu	Mặc định	Bắt buộc	Mô tả
APP_ENV_PORT	number	3000		Cổng HTTP lắng nghe (ngoài 31060)
APP_ENV_BASE_PATH	string	/v1/api/ledger		Tiền tố route
APP_ENV_NODE_ID	number	-	✓	Snowflake worker ID (6)
APP_ENV_DB_URL	string	-	✓	Kết nối PostgreSQL
APP_ENV_S3_BUCKET	string	ledger		Bucket S3 đích
RUN_MODE	string	-		migrate short-circuit đăng ký component/service/controller

Kafka

Tên	Kiểu	Mặc định	Bắt buộc	Mô tả
APP_ENV_KAFKA_BROKERS	string	-	✓	Brokers ngăn cách bằng dấu phẩy
APP_ENV_KAFKA_CLIENT_ID	string	SVC-00060-LEDGER		Client id producer/consumer
APP_ENV_KAFKA_GROUP_ID	string	SVC-00060-LEDGER_GROUP		Consumer group
APP_ENV_KAFKA_CONSUMER_COUNT	number	1*		Số instance consumer worker
APP_ENV_KAFKA_SASL_ENABLE	boolean	true		Bật/tắt SASL
APP_ENV_KAFKA_SASL_MECHANISM	string	SCRAM-SHA-512		Cơ chế SASL
APP_ENV_KAFKA_SASL_USERNAME / _PASSWORD	string	-		Credential SASL

* int() của giá trị chưa đặt - đặt rõ ràng cho >1.

WebSocket (role worker)

Tên	Kiểu	Mặc định	Mô tả
APP_ENV_WEBSOCKET_REDIS_MODE	single|cluster	single	Topology Redis emitter
APP_ENV_WEBSOCKET_REDIS_HOST / _PORT / _PASSWORD / _DB	-	localhost/6379/-/0	Kết nối chế độ single
APP_ENV_WEBSOCKET_REDIS_CLUSTER_NODES	string	-	Nodes chế độ cluster (bắt buộc nếu cluster)
APP_ENV_WEBSOCKET_REDIS_IDENTIFIER / _MAX_RETRY	-	ledger-ws-redis/5	-

Riêng service

Tên	Kiểu	Mặc định	Mô tả
APP_ENV_APPLICATION_ROLES	string	api,worker	CSV của api/worker; không hợp lệ/rỗng fallback cả hai
APP_ENV_LEDGER_ENCRYPTION_KEY	string	-	Khoá AES-256-GCM (bắt buộc cho encrypt/decrypt)
APP_ENV_SWEEP_INTERVAL_MS	number	300000	Chu kỳ quét recovery
APP_ENV_STALL_THRESHOLD_MS	number	180000	Cutoff job kẹt
APP_ENV_JOB_TIMEOUT_MS	number	120000	Timeout generate mỗi job (Promise.race)
APP_ENV_WORKER_IDLE_TIMEOUT_MS	number	-	Timeout idle worker
APP_ENV_FORCE_GENERATE	boolean	false	Bỏ qua skip in-flight + dùng job mới nhất (testing)
APP_ENV_ALLOW_CURRENT_PERIOD	boolean	false	Bao gồm tháng/quý hiện tại khi mở rộng batch
APP_ENV_EXTERNAL_DATA_BASE_URL	string	-	Base URL nguồn dữ liệu ngoài

2. Feature Flags

Flag	Mặc định	Hiệu ứng
APP_ENV_FORCE_GENERATE	false	Tạo lại ngay cả khi không có job PENDING (testing)
APP_ENV_ALLOW_CURRENT_PERIOD	false	Tạo batch bao gồm kỳ đang diễn ra

3. Dữ liệu seed

src/migrations/processes/migration-process.ts khai báo thứ tự seedPaths. alwaysRun: true = seed permission idempotent; false = dữ liệu tham chiếu một lần (upsert theo natural key).

File	Seed	Always run	Ghi chú
ledger-0001-seed-permissions	Các hàng permission ledger	✓	Upsert theo code
ledger-0004-seed-role-permissions	Grant role→permission cho permission ledger	✓	Map code permission ledger tới role
ledger-0005-seed-ledger-identifiers	6 hàng LedgerIdentifier (S1a-HKD..S2e-HKD) với i18n name/description	-	Upsert theo identifier
ledger-0006-seed-tax-tiers	4 hàng TaxTier (TIRE_1..TIRE_4) với biên doanh thu	-	Upsert theo code
ledger-0007-seed-ledger-tax-configs	Phương pháp thuế LedgerTaxConfig theo từng bậc (requiredLedgers, metadata.isDefault/isSelectable)	-	Upsert theo (taxTierId, code); bỏ qua một phương pháp nếu thiếu TaxTier của nó (chạy 0006 trước)

4. Lưu trữ Configuration

Dữ liệu tham chiếu (danh mục mẫu sổ, bậc thuế, phương pháp thuế) được seed vào các bảng ledger.* riêng, không phải bảng Configuration chung. Service này không lưu credential mã hoá nào; secret duy nhất là APP_ENV_LEDGER_ENCRYPTION_KEY (env).

Config	Lưu trữ	Đọc bởi
Danh mục mẫu sổ HKD	ledger.LedgerIdentifier	LedgerIdentifierController, pipeline tạo sổ
Bậc doanh thu	ledger.TaxTier	TaxTierController
Phương pháp thuế + mẫu sổ bắt buộc	ledger.LedgerTaxConfig	LedgerTaxConfigController
Onboarding thuế theo merchant theo năm	ledger.MerchantTaxConfig	chỉ-schema (chưa wire repository/service)

5. Trang liên quan

• Operations
• Domain Model
• Decisions