Kiến trúc Hệ thống
Danh mục Dịch vụ
| Dịch vụ | Mã | Cổng | Snowflake | Base Path | Lớp cơ sở |
|---|---|---|---|---|---|
| identity | SVC-00010 | 31010 | 1 | /v1/api/identity | IssuerApplication |
| commerce | SVC-00020 | 31020 | 2 | /v1/api/commerce | VerifierApplication |
| sale | SVC-00030 | 31030 | 3 | /v1/api/sale | VerifierApplication |
| finance | SVC-00040 | 31040 | 4 | /v1/api/finance | VerifierApplication |
| inventory | SVC-00050 | 31050 | 5 | /v1/api/inventory | VerifierApplication |
| ledger | SVC-00060 | 31060 | 6 | /v1/api/ledger | VerifierApplication |
| pricing | SVC-00070 | 31070 | 7 | /v1/api/pricing | VerifierApplication |
| payment | SVC-00080 | 31080 | 8 / 91,92 | /v1/api/payment | VerifierApplication |
| signal | SVC-00090 | 31090 | 9 | /v1/api/signal | VerifierApplication |
| outreach | SVC-00100 | 31110 | 10 | /v1/api/outreach | VerifierApplication |
| licensing | SVC-00110 | 31120 | 11 | /v1/api/licensing | VerifierApplication |
| taxation | SVC-00130 | 31130 | 13 | /v1/api/taxation | VerifierApplication |
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, taxationTấ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 |
|---|---|---|---|
public | 15 | 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 |
pricing | 11 | pricing | Giá vé, quy tắc giá, chi phí, thuế, đánh giá giá |
allocation | 4 | commerce | Sắp chỗ sự kiện, sơ đồ địa điểm |
sale | 9 | sale | Đơn hàng, mục đơn hàng, check, ticket bếp |
inventory | 12 | inventory | Tồn kho, đơn mua, mục mua, biến động kho |
finance | 3 | finance | Ví, giao dịch, danh mục |
payment | 1 | payment | Cấu hình webhook |
ledger | 2 | ledger | Tác vụ ledger, tài liệu được tạo |
identity | 8 | identity | Thông tin xác thực, định danh, hồ sơ, xác thực email |
licensing | 5 | licensing | Chính sách, tính năng chính sách, license, kích hoạt, sự kiện license |
outreach | 2 | outreach | Yêu cầu, người đăng ký |
Tổng cộng: 72 bảng trên 11 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 (28 module màn hình) | 5173 |
@nx-app/bo | React 19 + Vite 7 + shadcn/ui | Back office (quản lý merchant) | 5174 |
@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 (38 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 |