Configuration

Tổng quan

Gói Core cung cấp quản lý cấu hình tập trung qua biến môi trường, constants, định nghĩa kênh sự kiện, và định nghĩa queue. Mọi service kế thừa các cấu hình này cho hành vi nhất quán trên toàn nền tảng BANA.

Liên kết nhanh

Phần	Mô tả
Constants	Hằng tĩnh, enum, và định nghĩa schema
Environment Variables	Tham chiếu biến môi trường đầy đủ
Events	Định nghĩa sự kiện và kiểu payload cho giao tiếp xuyên service
Cross-Package Messaging (Kafka / CDC)	Hợp đồng topic sự kiện domain Kafka + CDC Debezium

Cấu trúc thư mục

packages/core/src/common/
├── index.ts              # Mọi export
├── environments.ts       # Định nghĩa key môi trường (re-export qua keys.ts)
├── constants.ts          # Hằng tĩnh
├── decorators.ts         # Decorator tuỳ chỉnh
├── validations.ts        # Tiện ích validation
├── events/               # Định nghĩa sự kiện
│   ├── index.ts
│   ├── commerce-events.ts
│   ├── ledger-events.ts
│   ├── payment-events.ts
│   └── websocket-events.ts
├── kafka/                # Hợp đồng topic + message Kafka
│   ├── index.ts
│   ├── topics.ts         # KafkaTopics + CDCKafkaTopics
│   └── types.ts
└── cdc/                  # Hằng bảng CDC Debezium
    ├── index.ts
    └── tables.ts

Biến môi trường

Lớp EnvironmentKeys mở rộng base keys của IGNIS Framework với cấu hình riêng application:

import { EnvironmentKeys as BaseEnvironmentKeys } from '@venizia/ignis';

export class EnvironmentKeys extends BaseEnvironmentKeys {
  // Application
  static readonly APP_ENV_NODE_ENV = 'APP_ENV_NODE_ENV';
  static readonly APP_ENV_APPLICATION_EXPLORER_URL = 'APP_ENV_APPLICATION_EXPLORER_URL';

  // Database
  static readonly APP_ENV_POSTGRES_HOST = 'APP_ENV_POSTGRES_HOST';
  static readonly APP_ENV_POSTGRES_PORT = 'APP_ENV_POSTGRES_PORT';
  // ... thêm key
}

Phân loại

Phân loại	Ví dụ	Mô tả
Application	APP_ENV_NODE_ENV, APP_ENV_APPLICATION_NAME	Cài đặt app cốt lõi
Database	APP_ENV_POSTGRES_HOST, APP_ENV_POSTGRES_PORT	Kết nối PostgreSQL
Redis/BullMQ	APP_ENV_BULLMQ_REDIS_HOST	Kết nối job queue
Storage	APP_ENV_MINIO_HOST, APP_ENV_MINIO_ACCESS_KEY	Lưu trữ MinIO/S3
Mail	APP_ENV_MAIL_HOST, APP_ENV_MAIL_USER	Cấu hình SMTP
ID Generation	APP_ENV_SNOWFLAKE_WORKER_ID	Cấu hình Snowflake ID
Services	APP_ENV_IDENTITY_SERVICE_BASE_URL	URL liên service

Xem mọi Environment Variables -->

Constants

Giá trị cấu hình tĩnh dùng khắp application:

PostgreSQL Schemas

export class PostgresSchemas {
  static readonly PUBLIC = 'public';
  static readonly PRICING = 'pricing';
  static readonly ALLOCATION = 'allocation';
  static readonly SALE = 'sale';
  static readonly INVENTORY = 'inventory';
  static readonly FINANCE = 'finance';
  static readonly PAYMENT = 'payment';
}

Fixed User Roles

export class FixedUserRoles {
  static readonly SUPER_ADMIN = '999-super-admin';
  static readonly ADMIN = '998-admin';
  static readonly OPERATOR = '997-operator';
  static readonly ORGANIZER_OWNER = '899-organizer-owner';
  static readonly EMPLOYEE = '898-employee';

  static readonly ALWAYS_ALLOW_ROLES = new Set([
    FixedUserRoles.SUPER_ADMIN,
    FixedUserRoles.ADMIN,
  ]);
}

Xem mọi Constants -->

Events

Định nghĩa sự kiện có kiểu cho giao tiếp xuyên service, publish/subscribe qua event bus (IEventBus, adapter Redis Pub/Sub). Định nghĩa trong src/common/events/: commerce-events.ts, ledger-events.ts, payment-events.ts, websocket-events.ts.

Danh sách event-class chính xác bên dưới là một ảnh chụp một phần — xem Events và file source cho tập hiện tại.

Tiện ích WebSocket

Lớp	Mô tả
WebSocketRooms	Dựng định danh room chuẩn hoá (wr:{prefix}/{paths})
WebSocketTopics	Dựng định danh topic chuẩn hoá (ws:{paths})

Xem mọi Events -->

Cross-Package Messaging (Kafka / CDC)

Đường nối xuyên package là Kafka (sự kiện domain) và Debezium CDC, không phải một hệ thống queue BullMQ. Hằng topic nằm trong src/common/kafka/topics.ts.

Lớp	Mục đích
KafkaTopics	Tên topic sự kiện domain + prefixer build({ paths }) (nx.seller)
CDCKafkaTopics	Tên topic CDC Debezium dựng từ CdcTables

Xem Cross-Package Messaging -->

Cách dùng

Truy cập biến môi trường

import { applicationEnvironment } from '@venizia/ignis';
import { EnvironmentKeys } from '@nx/core';

// Lấy biến bắt buộc
const dbHost = applicationEnvironment.get<string>(EnvironmentKeys.APP_ENV_POSTGRES_HOST);

// Lấy với mặc định
const port = applicationEnvironment.get<number>(EnvironmentKeys.APP_ENV_POSTGRES_PORT) ?? 5432;

Dùng Constants

import { FixedUserRoles, DeviceTypes, PostgresSchemas } from '@nx/core';

// Kiểm tra role
if (userRoles.includes(FixedUserRoles.SUPER_ADMIN)) {
  // Logic super admin
}

// Validate kiểu thiết bị
if (DeviceTypes.isValid(device.type)) {
  // Kiểu thiết bị hợp lệ
}

// Tham chiếu schema
const schema = PostgresSchemas.PRICING;

Luồng cấu hình

Thực hành tốt

1. Dùng Key an toàn kiểu

// Tốt -- an toàn kiểu
const host = applicationEnvironment.get<string>(EnvironmentKeys.APP_ENV_POSTGRES_HOST);

// Tệ -- dễ lỗi
const host = process.env.APP_ENV_POSTGRES_HOST;

2. Validate cấu hình bắt buộc

// Lúc khởi động application
function validateConfig() {
  const required = [
    EnvironmentKeys.APP_ENV_POSTGRES_HOST,
    EnvironmentKeys.APP_ENV_POSTGRES_DATABASE,
    EnvironmentKeys.APP_ENV_SNOWFLAKE_WORKER_ID,
  ];

  for (const key of required) {
    if (!applicationEnvironment.get(key)) {
      throw new Error(`Missing required environment variable: ${key}`);
    }
  }
}

3. Dùng Constants cho giá trị magic

// Tốt -- dùng constant
if (user.role === FixedUserRoles.SUPER_ADMIN) { }

// Tệ -- chuỗi magic
if (user.role === '999-super-admin') { }

Tài liệu liên quan

• DefaultApplication
• Core Utilities
• Database Overview