Kiến trúc Hệ thống
Danh mục Dịch vụ
Cổng, mã service, Snowflake worker ID và base path được tự sinh từ source - đây là nguồn-sự-thật-duy-nhất (cũng có ở Platform Facts):
| Service | Port | Base path | Snowflake | Mã service |
|---|---|---|---|---|
| identity | 31010 | /v1/api/identity | 1 | SVC-00010-IDENTITY |
| commerce | 31020 | /v1/api/commerce | 2 | SVC-00020-COMMERCE |
| sale | 31030 | /v1/api/sale | 3 | SVC-00030-SALE |
| finance | 31040 | /v1/api/finance | 4 | SVC-00040-FINANCE |
| inventory | 31050 | /v1/api/inventory | 5 | SVC-00050-INVENTORY |
| ledger | 31060 | /v1/api/ledger | 6 | SVC-00060-LEDGER |
| pricing | 31070 | /v1/api/pricing | 7 | SVC-00070-PRICING |
| payment | 31080 | /v1/api/payment | 8 | SVC-00080-PAYMENT |
| signal | 31090 | /v1/api/signal | 9 | SVC-00090-SIGNAL |
| outreach | 31110 | /v1/api/outreach | 10 | SVC-00110-OUTREACH |
| helpdesk | 31032 | /v1/api/helpdesk | 0 | SVC-00120-HELPDESK |
| taxation | 31130 | /v1/api/taxation | 13 | SVC-00130-TAXATION |
| licensing | 31120 | /v1/api/licensing | 11 | SVC-00140-LICENSING |
| invoice | 1190 | /v1/api | - | SVC-00150-INVOICE |
Tự sinh từ packages/* (env) + ServiceCodes + cây schema lúc build - không gõ tay.
Lớp cơ sở ứng dụng - identity là trust root duy nhất (phát JWKS); mọi service khác verify dựa trên nó:
| Lớp cơ sở | Dịch vụ |
|---|---|
IssuerApplication | identity |
VerifierApplication | commerce, sale, finance, inventory, ledger, pricing, payment, signal, outreach, helpdesk, taxation, licensing, invoice |
| hạ tầng (Traefik + Astro) | gateway |
Payment hỗ trợ triển khai theo chế độ:
full(mặc định, tất cả trong một),api(chỉ REST, Snowflake 8),worker(chỉ BullMQ, Snowflake 91, 92, ...).
Sơ đồ Mạng
Phân cấp Ứng dụng
BaseApplication (@venizia/ignis)
└── BaseApplication (@nx/core - CORS, Swagger, health check)
├── IssuerApplication (JWKS issuer - signs JWTs, serves /jw-certs)
│ └── identity
└── VerifierApplication (JWKS verifier - fetches remote /jw-certs)
└── commerce, sale, finance, inventory, pricing, payment,
signal, ledger, outreach, licensing, taxation,
helpdesk, invoiceTất cả dịch vụ xác thực JWT bằng cách lấy endpoint JWKS /jw-certs của dịch vụ identity. Chỉ có identity là dịch vụ ký token.
Chuỗi Phụ thuộc Package
Thứ tự build (từ Makefile): third-parties trước, sau đó là core, rồi đến tất cả các package theo thứ tự phụ thuộc. Xem Hệ thống Build để có tham khảo target đầy đủ.
Ánh xạ Schema Cơ sở Dữ liệu
Tất cả schema được định nghĩa trong @nx/core và dùng chung giữa các dịch vụ thông qua PostgresCoreDataSource. Mỗi dịch vụ kết nối vào cùng một cơ sở dữ liệu PostgreSQL nhưng hoạt động trên các schema khác nhau.
| Schema | Bảng | Dịch vụ chính | Mục đích |
|---|---|---|---|
helpdesk | 30 | helpdesk | Ticket, SLA, cơ sở tri thức, khảo sát, agent, thông báo |
public | 26 | identity, commerce | Người dùng, vai trò, quyền, merchant, organizer, sản phẩm, danh mục, biến thể, thiết bị, kênh bán hàng, cấu hình |
inventory | 17 | inventory | Tồn kho, đơn mua, mục mua, biến động kho, nguyên vật liệu, BOM |
sale | 21 | sale | Đơn hàng, mục đơn hàng, check, ticket bếp, đặt chỗ, ca làm việc |
invoice | 9 | invoice | Hóa đơn điện tử, đánh số, chữ ký, bản ghi nhà cung cấp |
pricing | 9 | pricing | Giá vé, quy tắc giá, chi phí, thuế, đánh giá giá |
identity | 8 | identity | Thông tin xác thực, định danh, hồ sơ, xác thực email |
ledger | 8 | ledger | Tác vụ ledger, tài liệu được tạo, nguồn dữ liệu |
finance | 6 | finance | Ví, giao dịch, danh mục, voucher |
tax | 6 | taxation | Nhóm thuế, mẫu thuế, cấp phát thuế sản phẩm |
licensing | 5 | licensing | Chính sách, tính năng chính sách, license, kích hoạt, sự kiện license |
allocation | 4 | commerce | Sắp chỗ sự kiện, sơ đồ địa điểm |
outreach | 2 | outreach | Yêu cầu, người đăng ký |
payment | 0 | payment | PaymentIntegration nằm trong schema finance |
Tổng cộng: 151 bảng trên 14 schema.
Xem Hướng dẫn Cơ sở Dữ liệu để biết quy trình migration và các pattern ORM.
Ma trận Component
Package nào đăng ký component hạ tầng nào:
| Package | Kafka Producer | Kafka Consumer | WebSocket | Cache Redis | Mail / SMS |
|---|---|---|---|---|---|
| core | - | - | - | Có | - |
| identity | - | - | Có | - | Có (SMS + Mail) |
| commerce | Có | - | Có | - | - |
| sale | Có | - | Có | - | - |
| finance | - | Có | Có | - | - |
| inventory | Có | Có | Có | - | - |
| pricing | - | Có | - | - | - |
| ledger | Có | Có | - | - | - |
| taxation | - | Có | - | - | - |
| search | - | - (CDC) | - | - | - |
| payment | - | - | Có | - | - |
| signal | - | - | Có (mã hóa E2E) | - | - |
| outreach | - | - | Có | - | - |
| licensing | - | - | - | Có | - |
Xem Kiến trúc Sự kiện để có tham khảo đầy đủ về topic và queue.
Ứng dụng Frontend
| App | Framework | Mục đích | Cổng |
|---|---|---|---|
@nx-app/client | React 19 + Vite 7 + shadcn/ui | Bảng điều khiển admin | 3001 |
@nx-app/bo | React 19 + Vite 7 + shadcn/ui | Back office (quản lý merchant) | 3000 |
@nx-app/sale-renderer | React 19 + Tauri 2 WebView | UI POS desktop | - |
@nx-app/sale-main | Rust + Tauri 2 | Backend POS desktop (SQLite, hardware plugins) | - |
@nx-app/overture | Astro | Trang marketing / landing | 4321 |
@nx-app/admin-ui-kit | React + Radix UI | Thư viện component dùng chung (43 shadcn + custom) | - |
@nx-app/core | TypeScript | Hằng số, hooks, locales, tiện ích dùng chung | - |
Tích hợp Bên thứ ba
| Package | Mục đích | Nhà cung cấp |
|---|---|---|
@nx/mq-pay | Thanh toán đa nhà cung cấp (QR, Phone POS, Smart POS) | VNPAY |
@nx/mq-sms | Cổng SMS đa nhà cung cấp | VNPAY |
@nx/iiapi | Dịch vụ hóa đơn điện tử Việt Nam | VNPAY viiAPI |
@nx/t-van | Truyền dữ liệu cho Cơ quan Thuế Việt Nam | T-VAN |
Trang Liên quan
| Trang | Mô tả |
|---|---|
| Bắt đầu | Hướng dẫn cài đặt cục bộ |
| Hệ thống Build | Target Makefile, đồ thị phụ thuộc |
| Kiến trúc Sự kiện | Topic Kafka, queue, WebSocket, CDC |
| Hướng dẫn Cơ sở Dữ liệu | Chi tiết schema, migration, pattern ORM |
| IGNIS Patterns | Phân cấp ứng dụng, DI, controller factory |
| Tổng quan Packages | Mục lục tài liệu từng package |