Configuration
1. Biến môi trường
Khoá core kế thừa từ
EnvironmentKeyscủa@nx/core; khoá riêng ledger trongsrc/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.tschạy theo thứ tự.alwaysRun: true= seed permission idempotent;false= một lần.
| File | Seed | Always run | Ghi chú |
|---|---|---|---|
ledger-0001-seed-permissions | hàng LedgerSystemPermissions | ✓ | Upsert theo code |
ledger-0002-seed-tax-declaration-levels | TaxDeclarationLevel — TIRE_1, TIRE_2, TIRE_3 | — | Dải thuế + rule lịch nộp |
ledger-0003-seed-merchant-ledger-configs | Một MerchantLedgerConfig mỗi merchant (năm hiện tại, requiredLedgerTypes=[S1a-HKD], origin: migration) | — | Bỏ qua nếu config tồn tại; bỏ qua hoàn toàn nếu thiếu bậc TIRE_1 |
ledger-0004-seed-role-permissions | Grant role→permission cho permission ledger | ✓ | Map code LedgerSystemPermissions tới role |
4. Lưu trữ Configuration
Config runtime theo từng merchant nằm trong bảng
MerchantLedgerConfig(không phải bảngConfigurationchung). 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 |
|---|---|---|
| Loại sổ bắt buộc, lịch nộp, bậc thuế | ledger.MerchantLedgerConfig | MerchantLedgerConfigService, validate batch |