Configuration

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

Các khoá cốt lõi đến từ @venizia/ignis / @nx/core; khoá riêng của service nằm trong src/common/environments.ts.

Core / Runtime

Tên	Kiểu	Mặc định	Bắt buộc	Mô tả
APP_ENV_SERVER_PORT	number	1190 ⚠️		Cổng HTTP lắng nghe (lẻ so với các anh em 310x0)
APP_ENV_BASE_PATH	string	/v1/api		Tiền tố route (không có segment riêng cho service)
APP_ENV_KAFKA_BROKERS	string	—	✓	Brokers ngăn cách bằng dấu phẩy
APP_ENV_KAFKA_CLIENT_ID	string	SVC-00150-INVOICE_CONSUMER		Mặc định fallback (${ServiceCodes.INVOICE}_CONSUMER); env đặt SVC-00150-INVOICE
APP_ENV_KAFKA_GROUP_ID	string	SVC-00150-INVOICE_CONSUMER_GROUP		Consumer group; env đặt SVC-00150-INVOICE-LOCAL
APP_ENV_APPLICATION_TIMEZONE	string	Asia/Ho_Chi_Minh		Timezone cho cron

BullMQ Redis

Tên	Kiểu	Mặc định	Bắt buộc	Mô tả
APP_ENV_INVOICE_BULLMQ_REDIS_MODE	single|cluster	—		Chế độ kết nối
APP_ENV_INVOICE_BULLMQ_REDIS_HOST / _PORT	string/number	—	✓	Host/port chế độ single
APP_ENV_INVOICE_BULLMQ_REDIS_PASSWORD / _DATABASE	string/number	—		Auth / db index
APP_ENV_INVOICE_BULLMQ_REDIS_CLUSTER_NODES	string	—		Nodes chế độ cluster
APP_ENV_INVOICE_BULLMQ_REDIS_MAX_RETRY	number	—		Retry kết nối
APP_ENV_INVOICE_ISSUANCE_WORKER_CONCURRENCY	number	10		Concurrency worker phát hành (claim-expiry cố định 3)

Providers & Webhooks

Tên	Kiểu	Bắt buộc	Mô tả
APP_ENV_VNIS_DEFAULT_TAX_CODE / _CLIENT_ID / _CLIENT_SECRET	string	✓	Kết nối VNIS mặc định (seed vào Configuration)
APP_ENV_TVAN_API_KEY	string	✓	Credential T-VAN (seed, đã mã hoá)
APP_ENV_VNPAY_TVAN_NAME / _API_KEY	string		Tên/khoá T-VAN của VNPAY
APP_ENV_INVOICE_WEBHOOK_SECRET	string	✓	Webhook merchant→platform (callback VNPAY/iiapi)
APP_ENV_INVOICE_WEBHOOK_INTERNAL_SECRET	string	✓	Webhook nội bộ iiapi/commerce→platform (HMAC-SHA256)
APP_ENV_INVOICE_WEBHOOK_CALLBACK_URL / _INTERNAL_BASE_URL	string		URL callback
APP_ENV_INVOICE_CREDENTIALS_KEY	string	✓	Khoá AES-256-GCM — đúng 32 byte / 64 hex (openssl rand -hex 32)
APP_ENV_INVOICE_CLAIM_BASE_URL	string	✓	Base link tự khai báo của người mua

⚠️ APP_ENV_..._WORKER_ID (snowflake) chưa được cấu hình — xem Operations.

2. Feature Flags

Flag	Nguồn	Mặc định	Mô tả
Phát hành định kỳ	hàng Configuration INVOICE_SCHEDULED_ISSUANCE.jValue.enabled	true	Bật/tắt phát hành theo lô bằng cron
Issuance mode	InvoiceProviderConfig.issuanceMode	MANUAL	Theo từng config: REAL_TIME / MANUAL / SCHEDULED / BUYER_SELF_SERVICE
autoRelease / autoSign / autoSendCqt / isSendMail	InvoiceProviderConfig	false	Chính sách xuất theo từng config

3. Dữ liệu seed

Các process migration ở src/migrations/processes/ — idempotent (kiểm tra tồn tại), chạy qua bun run migrate:dev.

File	Seed	Idempotent
invoice-0001-seed-configurations.ts	3 hàng Configuration (VNIS, T-VAN, phát hành định kỳ)	✓
invoice-0002-seed-webhook-configs.ts	webhook config commerce (INVOICE_COMMERCE_EVENTS → ORGANIZER_HQ_CHANGED)	✓
invoice-0003-seed-permissions.ts	permissions invoice	✓
invoice-0004-seed-role-permissions.ts	grant role↔permission	✓
(dữ liệu hành chính VN)	tỉnh / phường / đơn vị hành chính	✓

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

Config runtime theo từng môi trường; credential được mã hoá AES-256-GCM qua encryptText.

Code	jValue	Credential	Đọc bởi
VNIS_DEFAULT_CONNECTION	{ taxCode, provider, clientId }	clientSecret (đã mã hoá)	InvoiceProviderConnectionComponent
TVAN_DEFAULT_CONNECTION	{ provider, name }	apiKey (đã mã hoá)	TVanConnectionComponent
INVOICE_SCHEDULED_ISSUANCE	{ enabled, cronTime: '0 23 * * *', batchSize: 200 }	—	CronComponent / InvoiceScheduledIssuanceService

Credential theo từng merchant (InvoiceProvider.password, .webhookSecret) được mã hoá trên hàng provider, không phải trong Configuration.

5. Trang liên quan

• Operations
• Integration
• Decisions