Cấu hình

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

Khóa core từ EnvironmentKeys (@nx/core + @venizia/ignis); commerce thêm khóa Redis BullMQ trong src/common/environments.ts. Đọc qua applicationEnvironment.get<T>(key).

Runtime core

Tên	Type	Mặc định	Bắt buộc	Mô tả
APP_ENV_PORT	number	3000		Cổng HTTP lắng nghe (container)
APP_ENV_HOST	string	0.0.0.0		Địa chỉ bind
APP_ENV_BASE_PATH	string	/v1/api/commerce		Tiền tố route
APP_ENV_NODE_ID	number	—	✓	Snowflake worker ID — phải là 2
APP_ENV_WORKERS	csv|ALL	—		Bật SyncProductWorker (+ CDC consumer ở vai trò WORKER)
RUN_MODE	migrate|server	—		migrate chuyển sang điểm vào migration

Cơ sở dữ liệu

Tên	Type	Mặc định	Bắt buộc	Mô tả
APP_ENV_DB_URL	string	—	✓	URL kết nối PostgreSQL

Cache / authorization Redis

Tên	Type	Mặc định	Bắt buộc	Mô tả
APP_ENV_REDIS_*	—	—		Cache Redis (useCacheRedis); cũng là authorization Redis (getAuthorizationRedisConnection) và cache footer-summary

BullMQ Redis (kết nối riêng)

Tên	Type	Mặc định	Bắt buộc	Mô tả
APP_ENV_BULLMQ_REDIS_MODE	single|cluster	single		Chế độ kết nối
APP_ENV_BULLMQ_REDIS_HOST	string	localhost		Host single-mode
APP_ENV_BULLMQ_REDIS_PORT	number	6379		—
APP_ENV_BULLMQ_REDIS_PASSWORD	string	—		—
APP_ENV_BULLMQ_REDIS_DATABASE	number	0		—
APP_ENV_BULLMQ_REDIS_MAX_RETRY	number	5		—
APP_ENV_BULLMQ_REDIS_CLUSTER_NODES	string	—	cluster	Bắt buộc khi mode=cluster
APP_ENV_BULLMQ_WORKER_CONCURRENCY	number	1		Concurrency của SyncProductWorker

WebSocket Redis

Tên	Type	Mặc định	Bắt buộc	Mô tả
APP_ENV_WEBSOCKET_REDIS_MODE	single|cluster	single		—
APP_ENV_WEBSOCKET_REDIS_HOST/PORT/PASSWORD/DB/MAX_RETRY	—	host localhost, port 6379, db 0, retry 5		Kết nối WebSocketEmitter single-mode
APP_ENV_WEBSOCKET_REDIS_CLUSTER_NODES	string	—	cluster	Bắt buộc khi mode=cluster

Kafka (chỉ producer)

Tên	Type	Mặc định	Bắt buộc	Mô tả
APP_ENV_KAFKA_BROKERS	csv	—		Danh sách broker phân tách bằng dấu phẩy (rỗng ⇒ không broker)
APP_ENV_KAFKA_CLIENT_ID	string	SVC-00020-COMMERCE_PRODUCER		Client id producer
APP_ENV_KAFKA_SASL_ENABLE	'true'|'false'	false		Bật/tắt SASL
APP_ENV_KAFKA_SASL_MECHANISM/USERNAME/PASSWORD	string	NA		Khi SASL được bật

Cấu hình producer: requestTimeout 60_000ms, connectTimeout 30_000ms, serializer giá trị JSON. Producer được bind nhưng không được gọi trong src/.

Bảo mật / tích hợp

Tên	Type	Mặc định	Bắt buộc	Mô tả
APP_ENV_APPLICATION_SECRET	string	—	✓ (cho tích hợp provider)	Khóa AES-256-GCM cho EncryptService
APP_ENV_JWKS_URL	url	—	✓	Endpoint JWKS của identity
APP_ENV_BASIC_AUTH_*	string	—		Thông tin đăng nhập basic service-to-service

Các component search/asset (@nx/search, @nx/asset) đọc env riêng của chúng (node Typesense, endpoint/key Minio, cấu hình embedding) — xem các package đó.

2. Feature Flags

Không có feature flag toàn cục. Hành vi runtime được kiểm soát bởi:

Cổng	Cơ chế
Bật Worker / CDC	APP_ENV_WORKERS (SyncProductWorker; CDC consumer ở vai trò WORKER)
Cờ strictCategoryDeletion / cascade theo merchant	DeletionPolicyService (chính sách theo merchant)
Đồng bộ sản phẩm tới merchant phụ	sự hiện diện của merchantIds[] / syncMerchantIds trong request aggregate

3. Dữ liệu Seed

Các process migration trong src/migrations/processes/. Chạy khi bootstrap (prestart → bun run rebuild → migrate.ts); theo từng dev qua bun run migrate:dev.

Process	Seed / backfill
commerce-0002-seed-permissions	Danh mục quyền RBAC
commerce-0003-seed-typesense-embedding-configs	Cấu hình embedding tìm kiếm ngữ nghĩa
commerce-0005-seed-default-finance-accounts	Config tài khoản tài chính mặc định hệ thống
commerce-0006-seed-merchant-fnb-sectors	Phân loại ngành FnB
commerce-0007-seed-category-templates	Mẫu category SYSTEM
commerce-0008-seed-search-pipeline-config	Config search pipeline
commerce-0009-seed-role-permissions	Cấp quyền Role→permission
commerce-0010-seed-guest-permissions	Quyền cho vai trò guest
commerce-0011-backfill-merchant-onboarding	Backfill cờ metadata.onboarding

4. Lưu trữ Cấu hình (bảng Configuration)

Loại	Mã hóa	Khóa phạm vi
Thông tin đăng nhập tích hợp provider	AES-256-GCM (EncryptService)	(group, code, principalId, principalType, environment)
Config hệ thống (tài khoản tài chính, mẫu category, search pipeline)	—	group=SYSTEM, principalId/Type=null

Định dạng mã credential: {type}:{provider}:{credentialAction}:{credentialType}. Response trả về giá trị hiển thị được che; getDecryptedCredential chỉ nội bộ (không bao giờ phơi bày qua controller).

5. Trang liên quan

• Vận hành — triển khai + observability
• API Events — CDC / BullMQ / WebSocket
• Quyết định