Core Package
@nx/core là thư viện nền tảng của monorepo BANA. Nó không phải microservice - bản thân nó không có runtime riêng. Mọi backend package khác đều import và mở rộng nó, nên core phải được build trước.
Đây là một thẻ định danh ngắn gọn. Core có lý do chính đáng để khác với template service 8-file chuẩn - cấu trúc đã hoàn chỉnh của nó (
architecture,components/*,configuration/*,database/*,utilities/*) được mô tả trong các trang con liên kết bên dưới.
Thẻ định danh
| Thuộc tính | Giá trị |
|---|---|
| Package | @nx/core |
| Loại | Thư viện dùng chung / mở rộng framework (không có 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 | Nơi duy nhất chứa mọi schema trong monorepo - <domain>/<entity>/{schema.ts, model.ts, constants.ts, index.ts} trải trên 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(), các helper merchant-access + postgres + transform + slug | src/utilities/ |
| Constants & types | Statuses (của IGNIS, dùng lại - không tự định nghĩa enum), PostgresSchemas, AppFixedRoles, các validation, decorator dùng chung | src/common/ |
Điểm giao tiếp xuyên package
Kafka/CDC là điểm 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 |
| Các service khác (invoice, ledger, licensing, outreach, tax, helpdesk, search, asset) | VerifierApplication | Dùng lại schema, repo, và contract 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, AppFixedRoles, 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 |
Các domain schema
Schema nằm dưới src/models/schemas/<domain>/<entity>/; repository được phản chiếu tương ứng dưới src/repositories/<domain>/. Có 14 domain - các service package dùng lại các schema này, chúng không tự định nghĩa schema riêng.
public · pricing · allocation · sale · inventory · finance · payment · invoice · ledger · identity · licensing · outreach · tax · helpdesk
Các trang con
database/hiện chỉ mô tả một snapshot 7-schema. Xem Database Overview cho các schema đã được ghi; bố cục 14-domain đầy đủ mới là nguồn chuẩn duy nhất (.agents/knowledge/packages/core.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