Configuration

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

Nguồn: packages/core/src/common/environments.ts + packages/taxation/.env.development.

Core / Server

Tên	Kiểu	Mặc định	Bắt buộc	Mô tả
RUN_MODE	startup|migrate	startup	✓	startup boot app + CDC consumer; migrate chạy seed
NODE_ENV	string	development		Runtime env
TZ	string	Asia/Ho_Chi_Minh		Timezone
APP_ENV_APPLICATION_NAME	string	taxation		Tên app
APP_ENV_APPLICATION_CODE	string	SVC-00130-TAXATION		Service code
APP_ENV_SERVER_HOST	string	localhost		Host bind
APP_ENV_SERVER_PORT	number	31130		Port HTTP (container 3000)
APP_ENV_SERVER_BASE_PATH	string	/v1/api/taxation		Prefix route
APP_ENV_SNOWFLAKE_WORKER_ID	number	13	✓	Snowflake worker id (hardcode — rủi ro collision nếu scale)
APP_ENV_SNOWFLAKE_EPOCH_CHECKPOINT	number	1735689600000		Base epoch Snowflake

Database

Tên	Kiểu	Mặc định	Bắt buộc	Mô tả
APP_ENV_POSTGRES_HOST	string	—	✓	Host PostgreSQL
APP_ENV_POSTGRES_PORT	number	35432	✓	Port
APP_ENV_POSTGRES_USERNAME	string	—	✓	User
APP_ENV_POSTGRES_PASSWORD	string	—	✓	Password
APP_ENV_POSTGRES_DATABASE	string	nx_seller	✓	Database (schema tax, pricing)

Identity / Auth

Tên	Kiểu	Mặc định	Bắt buộc	Mô tả
APP_ENV_IDENTITY_SERVICE_BASE_URL	string	—	✓	Base URL identity cho JWKS
APP_ENV_JWKS_REST_PATH	string	/jw-certs	✓	Path endpoint JWKS
APP_ENV_APPLICATION_SECRET	string	—	✓	App secret

Kafka (CDC consumer)

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
APP_ENV_KAFKA_CLIENT_ID	string	SVC-00130-TAXATION		Client id consumer
APP_ENV_KAFKA_GROUP_ID	string	SVC-00130-TAXATION_CONSUMER_GROUP		Consumer group
APP_ENV_KAFKA_SASL_ENABLE	boolean	true		Bật SASL
APP_ENV_KAFKA_SASL_MECHANISM	string	SCRAM-SHA-512		SASL mechanism
APP_ENV_KAFKA_SASL_USERNAME / _PASSWORD	string	—		Credential SASL

2. Feature Flags

Không. Hành vi điều khiển bởi env vars và payload CDC.

3. Dữ liệu Seed

Các migration process trong src/migrations/processes/. Chạy ở RUN_MODE=migrate qua bun run migrate:dev. Cả bốn là alwaysRun: true (upsert idempotent). Dữ liệu tham chiếu VN KHÔNG được seed ở đây.

File	Seeds	Idempotent	Ghi chú
taxation-0001-seed-discrimination-types.ts	Phân loại thuế (scope tax_classification): VAT, Excise, Environmental, Luxury, PIT, Custom	✓	Hậu thuẫn TaxGroupItem.discriminationTypeId
taxation-0002-seed-tax-groups.ts	13 tax group hệ thống + các TaxGroupItem của chúng (9 DIRECT + 4 DEDUCTION)	✓	Resolve item theo DiscriminationType
taxation-0003-seed-permissions.ts	TaxationPermissions (quyền đọc TaxGroup, TaxGroupItem, Vn*)	✓	Upsert theo code
taxation-0004-seed-role-permissions.ts	Cấp tất cả quyền taxation cho OWNER, EMPLOYEE, CASHIER	✓	Baseline khoan dung; siết sau qua policy-definition API

Tax group hệ thống (13)

Method DIRECT (9 — VAT + PIT theo ngành):

Identifier	VAT	PIT	Ngành
VN_DIRECT_VAT0_PIT05_DISTRIBUTION	0%	0.5%	Phân phối
VN_DIRECT_VAT1_PIT05_DISTRIBUTION	1%	0.5%	Phân phối
VN_DIRECT_VAT0_PIT2_SERVICES	0%	2%	Dịch vụ
VN_DIRECT_VAT0_PIT5_SERVICES	0%	5%	Dịch vụ
VN_DIRECT_VAT5_PIT2_SERVICES	5%	2%	Dịch vụ
VN_DIRECT_VAT5_PIT5_SERVICES	5%	5%	Dịch vụ
VN_DIRECT_VAT0_PIT15_MANUFACTURING	0%	1.5%	Sản xuất
VN_DIRECT_VAT3_PIT15_MANUFACTURING	3%	1.5%	Sản xuất
VN_DIRECT_VAT2_PIT1_OTHER	2%	1%	Khác

Method DEDUCTION (4 — bậc VAT):

Identifier	VAT
VN_DEDUCTION_VAT0	0%
VN_DEDUCTION_VAT5	5%
VN_DEDUCTION_VAT8	8%
VN_DEDUCTION_VAT10	10%

Enum tham chiếu

Enum	Source	Values
TaxMethods	tax/tax-group/constants.ts	000_DIRECT, 100_DEDUCTION
FixedTaxTypes	pricing/tax-type/constants.ts	000_VAT, 100_EXCISE, 200_ENVIRONMENTAL, 300_LUXURY, 400_PIT, 999_CUSTOM
TaxModes	pricing/tax/constants.ts	000_AMOUNT, 100_PERCENTAGE, 200_PER_UNIT_AMOUNT
TaxUsages	pricing/tax/constants.ts	000_SALE, 100_PURCHASE
TaxChargeTargets	pricing/tax-type/constants.ts	000_CUSTOMER, 100_MERCHANT

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

Không dùng. Taxation không giữ config runtime theo từng merchant hay credential encrypted.

5. Trang liên quan

• Operations
• Domain Model — Entities
• Decisions