Configuration

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

Nguồn: packages/core/src/common/environments.ts (EnvironmentKeys) + src/common/ của package này.

Core

Tên	Kiểu	Mặc định	Bắt buộc	Mô tả
APP_ENV_PORT	number	3000		Port HTTP lắng nghe (dev external 31040)
APP_ENV_HOST	string	0.0.0.0		Host bind
APP_ENV_BASE_PATH	string	/v1/api/finance		Prefix route
APP_ENV_NODE_ID	number	4	✓	Snowflake worker ID
APP_ENV_LOG_LEVEL	info|debug|warn|error	info		Mức logger
NODE_ENV	string	production		Phân vùng env đóng dấu lên tài khoản

Database

Tên	Kiểu	Mặc định	Bắt buộc	Mô tả
APP_ENV_DB_URL	string	—	✓	URL kết nối PostgreSQL
APP_ENV_DB_POOL_MAX	number	10		Kích thước pool tối đa

Kafka

Tên	Kiểu	Mặc định	Bắt buộc	Mô tả
APP_ENV_KAFKA_BROKERS	string	—	✓	Broker phân tách bằng dấu phẩy (rỗng → component throw khi boot)
APP_ENV_KAFKA_CLIENT_ID	string	SVC-00040-FINANCE_PRODUCER / _CONSUMER		Client id
APP_ENV_KAFKA_GROUP_ID	string	SVC-00040-FINANCE_CONSUMER_GROUP		Consumer group
APP_ENV_KAFKA_SASL_ENABLE	boolean	false		Bật SASL
APP_ENV_KAFKA_SASL_MECHANISM / _USERNAME / _PASSWORD	string	—		Credential SASL (khi bật)

WebSocket Redis

Tên	Kiểu	Mặc định	Bắt buộc	Mô tả
APP_ENV_WEBSOCKET_REDIS_MODE	single|cluster	single		Topology Redis của emitter
APP_ENV_WEBSOCKET_REDIS_HOST	string	localhost		—
APP_ENV_WEBSOCKET_REDIS_PORT	number	6379		—
APP_ENV_WEBSOCKET_REDIS_PASSWORD	string	—		—
APP_ENV_WEBSOCKET_REDIS_DB	number	0		—
APP_ENV_WEBSOCKET_REDIS_IDENTIFIER	string	finance-ws-redis		Tên kết nối

Cache / Authorization Redis

Tên	Kiểu	Mặc định	Bắt buộc	Mô tả
APP_ENV_REDIS_HOST	string	—	✓	Host cache authorization (useCacheRedis)
APP_ENV_REDIS_PORT	number	6379		—

2. Feature Flags

Không. Finance không có runtime feature flag. Các công tắc hành vi (một tiền tệ, sự hiện diện của tài khoản kiểm soát) là cấu trúc, không gate bằng flag. Đa tiền tệ đang ngủ: cột exchangeRate tồn tại nhưng hard-set thành 1.

3. Dữ liệu Seed

Các migration process trong src/migrations/processes/ — load bởi migration-process.ts, idempotent.

File	Seeds	Always-run	Ghi chú
finance-0001-seed-categories.ts	14 dòng FinanceCategory hệ thống (merchantId=null)	no	Upsert theo (name, type, identifier, merchantId=null)
finance-0002-seed-permissions.ts	Tất cả dòng Permission finance	yes	Upsert theo code
finance-0003-seed-role-permissions.ts	Cấp TẤT CẢ quyền finance cho OWNER, EMPLOYEE, CASHIER	yes	Baseline khoan dung; siết sau qua merchant policy API

14 danh mục hệ thống

Identifier	Type	Name (en)
000_SALE	INCOME	Sales Revenue
001_OTHER_INCOME	INCOME	Other Income
002_REFUND_INCOME	INCOME	Refund Received
300_COLLECT_INTEREST	INCOME	Interest Income
100_PURCHASE	EXPENSE	Purchase - Inventory
101_OTHER_EXPENSE	EXPENSE	Other Expenses
102_REFUND_EXPENSE	EXPENSE	Refund to Customer
200_OPERATING	EXPENSE	Operating Expenses
201_SALARY	EXPENSE	Salaries & Wages
202_RENT_UTILITIES	EXPENSE	Rent & Utilities
203_MARKETING	EXPENSE	Marketing & Advertising
204_SHIPPING	EXPENSE	Transportation & Delivery
205_MAINTENANCE	EXPENSE	Maintenance & Repairs
301_PAY_INTEREST	EXPENSE	Interest Expense

Hằng số trong FixedFinanceCategories. Merchant thêm danh mục con tùy chỉnh dưới các danh mục này qua category API. Tài khoản kiểm soát INVENTORY/COGS không phải seed — chúng được đối soát theo từng merchant khi sự kiện merchant CDC đầu tiên.

4. Lưu trữ Configuration (bảng Configuration)

Config runtime theo từng merchant / hệ thống đọc qua ConfigurationRepository.

Configuration	Group	Read by	Mục đích
DEFAULT_FINANCE_ACCOUNTS	SYSTEM (principal null)	FinanceWorkerService._loadDefaultAccountConfig	Mảng template tài khoản mặc định seed cho merchant mới khi thiếu merchant.metadata.finance.accounts; validate bởi DefaultFinanceAccountsConfigSchema
PaymentIntegration.credential	— (bảng riêng)	PaymentIntegrationService / FinanceIntegrationService	Credential gateway encrypted; mask trong API response

5. Trang liên quan

• Operations
• API Events
• Decisions