Core Package
@nx/core là thư viện nền tảng của monorepo BANA. Nó không phải microservice — nó không ship runtime riêng. Mọi backend package khác import và mở rộng nó, nên core phải được build trước.
Đây là một thẻ định danh nhẹ. Core hợp lệ đi chệch khỏi template service 8-file chuẩn — cấu trúc trưởng thành của nó (
architecture,components/*,configuration/*,database/*,utilities/*) được ghi trong các sub-page liên kết bên dưới.
Thẻ định danh
| Thuộc tính | Giá trị |
|---|---|
| Package | @nx/core |
| Type | Thư viện dùng chung / mở rộng framework (không runtime độc lập) |
| Snowflake worker ID | 0 (dành cho core) |
| Framework | IGNIS (@venizia/ignis, @venizia/ignis-helpers) |
| Runtime | Bun |
| ORM | Drizzle ORM + node-postgres (PostgreSQL) |
| Build | bun run rebuild (clean + tsc + tsc-alias) — không bao giờ tsc thô |
| Source | packages/core/src/ |
Core cung cấp gì
| Khả năng | Là gì | Nằm ở |
|---|---|---|
| Lớp application cơ sở | BaseApplication (middleware dùng chung), IssuerApplication (JWKS issuer, ES256 — Identity), VerifierApplication (JWKS verifier — mọi service khác), DefaultApplication (JWT đối xứng legacy) | src/application/ |
| Helper bootstrap | bootstrapApplication(), bootstrapMigration(), createAppConfig(), createMigrationProcessLoader() | src/helpers/bootstraps/, src/common/app-config.ts |
| Drizzle schema tập trung | Nhà duy nhất cho mọi schema trong monorepo — <domain>/<entity>/{schema.ts, model.ts, constants.ts, index.ts} qua 14 domain | src/models/schemas/<domain>/<entity>/ |
| Định nghĩa cột dùng chung | generateCommonColumnDefs() (id, timestamps, soft-delete, metadata jsonb), isoTimestamp(), helper cột i18n | src/models/schemas/common/ |
| Repositories | Một mỗi entity, gom theo domain; extend SoftDeletableRepository hoặc ArchivedRepository | src/repositories/<domain>/ |
| Lớp repository cơ sở | SoftDeletableRepository (re-export từ @venizia/ignis), ArchivedRepository (vòng đời archive theo status) | src/base/repository/ |
| Lớp service cơ sở | BaseSocketEventService (emit WebSocket qua Signal), MerchantScopedService (CRUD phạm vi merchant) | src/base/service/ |
| Snowflake IdGenerator | Singleton bọc IGNIS SnowflakeUidHelper | src/utilities/id-generator.utility.ts |
| Hợp đồng topic Kafka / CDC | KafkaTopics (tên sự kiện domain + prefixer build()), CDCKafkaTopics (Debezium), CdcTables | src/common/kafka/, src/common/cdc/ |
| Event bus | Interface IEventBus + adapter Redis Pub/Sub; định nghĩa sự kiện có kiểu | src/helpers/event-bus/, src/common/events/ |
| Redis | RedisConnectionFactory (single / cluster) | src/helpers/redis/ |
| Tiện ích dùng chung | CryptoUtility, dayjs (cấu hình timezone), useRequestContext(), helper merchant-access + postgres + transform + slug | src/utilities/ |
| Constants & types | Statuses (IGNIS, tái dùng — không enum tuỳ chỉnh), PostgresSchemas, FixedUserRoles, validations, decorator dùng chung | src/common/ |
Đường nối xuyên package
Kafka/CDC là đường nối giao tiếp xuyên package chủ đạo — không phải một hệ thống queue BullMQ.
| Cơ chế | Mục đích |
|---|---|
KafkaTopics | Tên topic sự kiện domain (vd PAYMENT_SUCCESS, INVENTORY_ISSUED_FOR_SALE, LEDGER_GENERATE), với build({ paths }) prefix nx.seller |
CDCKafkaTopics | Topic CDC Debezium dựng từ CdcTables (vd MERCHANT, PRODUCT, SALE_ORDER) |
Event bus (IEventBus) | Trừu tượng pub/sub in-process với adapter Redis Pub/Sub |
| Redis | Quản lý kết nối dùng chung cho caching và pub/sub |
Ai phụ thuộc Core
Mọi backend package phụ thuộc @nx/core và kết nối tới cùng database qua PostgresCoreDataSource được re-export.
| Package | Application base | Vai trò |
|---|---|---|
@nx/identity | IssuerApplication | JWT issuer (JWKS, ES256); auth, RBAC, users |
@nx/commerce | VerifierApplication | Products, pricing, merchants, organizers |
@nx/sale | VerifierApplication | Sale orders, checkout |
@nx/finance | VerifierApplication | Income/expense, wallets |
@nx/payment | VerifierApplication | Điều phối payment, webhooks |
@nx/inventory | VerifierApplication | Quản lý stock, purchase orders |
@nx/signal | VerifierApplication | WebSocket service tập trung |
| Service khác (invoice, ledger, licensing, outreach, tax, helpdesk, search, asset) | VerifierApplication | Tiêu thụ schema, repo, và contracts của core |
Bản đồ tài liệu
| Trang | Bạn sẽ tìm thấy gì |
|---|---|
| Architecture | Phân cấp application, vòng đời, mẫu runtime |
| Components | |
| Components Overview | Chỉ mục lớp cơ sở và hạ tầng dùng chung |
| DefaultApplication | Lớp app cơ sở, middleware, method vòng đời |
| SoftDeletableRepository | Mẫu soft-delete + restore (re-export từ IGNIS) |
| BaseSocketEventService | Broadcast sự kiện WebSocket |
| Network Services | IdentityNetworkService HTTP xuyên service |
| Bootstrap Helpers | bootstrapApplication / bootstrapMigration |
| RedisConnectionFactory | Kết nối Redis single/cluster |
| Event Bus | IEventBus + adapter Redis Pub/Sub |
| Configuration | |
| Configuration Overview | Environment, constants, events, topics |
| Environment Variables | Tham chiếu EnvironmentKeys |
| Constants | PostgresSchemas, FixedUserRoles, v.v. |
| Events | Định nghĩa sự kiện + builder topic WebSocket |
| Queues / Kafka | Hợp đồng messaging xuyên package |
| Database | |
| Database Overview | Bố cục schema, generateCommonColumnDefs, DataSource |
| Public Schema | Users, products, merchants, organizers |
| Pricing Schema | Fares, costs, taxes |
| Allocation Schema | Sắp chỗ sự kiện |
| Sale Schema | Sale orders + items |
| Inventory Schema | Stock, purchase orders, vendors |
| Finance Schema | Wallets, categories, transactions |
| Payment Schema | Cấu hình webhook |
| Outreach Schema | Domain outreach |
| ERD | Sơ đồ thực thể-quan hệ |
| Migrations | CLI migrator theo domain, Drizzle Kit, seeds |
| Utilities | |
| Utilities Overview | Chỉ mục tiện ích dùng chung |
| IdGenerator | Singleton Snowflake ID |
| CryptoUtility | Mã hoá + ký HMAC |
| DateUtility | dayjs cấu hình timezone |
| RequestContext | Auth context + định dạng response |
Domain Schema
Schema nằm dưới src/models/schemas/<domain>/<entity>/; repository phản chiếu chúng dưới src/repositories/<domain>/. Có 14 domain — service package tiêu thụ các schema này, chúng không định nghĩa riêng.
public · pricing · allocation · sale · inventory · finance · payment · invoice · ledger · identity · licensing · outreach · tax · helpdesk
Các sub-page
database/hiện ghi một ảnh chụp 7-schema. Xem Database Overview cho các schema đã ghi; bố cục 14-domain đầy đủ là nguồn sự thật (packages/core/AGENTS.md).
Build & Scripts
| Script | Mục đích |
|---|---|
bun run rebuild | Clean + build (luôn dùng cái này) |
bun run lint:fix | ESLint + Prettier auto-fix |
bun run test | Chạy tests (cần .env.test) |
bun run db:generate / db:migrate | Sinh / áp migration cho một domain |
bun run db:generate:all / db:migrate:all | Mọi domain |
Tham chiếu IGNIS
- IGNIS docs · Application · Repositories · DataSources · DI