Tổng quan Hệ sinh thái Client

1. Kiểm soát Tài liệu

Thuộc tính	Giá trị
Trạng thái	Hoạt động
Phiên bản	1.0.0
Cập nhật lần cuối	20/01/2025
Người bảo trì	Frontend Team

2. Phạm vi & Mục tiêu

2.1. Phạm vi

Hệ sinh thái Client bao gồm tất cả các ứng dụng giao diện người dùng trong giải pháp BANA, bao gồm thiết bị Điểm bán hàng (POS), bảng điều khiển quản lý Back Office và các thư viện dùng chung hỗ trợ chúng.

2.2. Mục tiêu Chiến lược

Mục tiêu	Mô tả	Chỉ số
Nhất quán	Duy trì UX/UI thống nhất trên các nền tảng bằng hệ thống thiết kế chung	Một thư viện thành phần duy nhất
Hiệu suất	Thời gian phản hồi dưới 100ms cho các tương tác POS quan trọng	Thao tác giỏ hàng < 100ms
Khả năng bảo trì	Tối đa hóa việc tái sử dụng mã thông qua các thư viện lõi dùng chung	80%+ tiện ích dùng chung
Khả năng hoạt động ngoại tuyến	Chức năng POS cốt lõi không cần internet (Local-First)	100% thao tác giỏ hàng ngoại tuyến

3. Danh mục Ứng dụng

3.1. Tổng quan Ứng dụng

📱

Ứng dụng

Sản phẩm giao diện người dùng

🌐

client

Ứng dụng Web Back Office

🖥️

sale-main

Tauri Backend (Rust)

🎨

sale-renderer

Giao diện POS (React)

▼ Imports

📦

Thư viện dùng chung

Các gói nội bộ

🧩

admin-ui-kit

36 Thành phần UI

🔧

core

Tiện ích & Locales

3.2. Chi tiết Ứng dụng

Ứng dụng	Gói	Loại	Tệp	Cổng	Người dùng chính
Back Office	`@nx-app/client`	Web SPA	637 TS/TSX	3001	Quản lý / Chủ sở hữu
POS Terminal	`@nx-app/sale-main`	Desktop (Rust)	46 Rust	N/A	Thu ngân
POS UI	`@nx-app/sale-renderer`	Web SPA (Tauri)	337 TS/TSX	3002	Thu ngân
UI Kit	`@nx-app/admin-ui-kit`	Library	44 TS/TSX	N/A	Nhà phát triển
Core	`@nx-app/core`	Library	11 TS	N/A	Nhà phát triển

3.3. Sản phẩm bàn giao

Ứng dụng	Triển khai	Artifact
Back Office	Docker / Nginx	Static bundle (`dist/`)
POS Terminal	Native Installer	`.msi` (Win), `.dmg` (Mac), `.deb` (Linux)
POS UI	Nhúng trong Tauri	Static bundle (WebView)

4. Ngăn xếp Công nghệ

4.1. Công nghệ Cốt lõi

Lớp	Công nghệ	Phiên bản	Mục đích
Runtime	Bun	1.3.2+	JavaScript/TypeScript runtime
Framework	React	19.2.x	UI framework
Công cụ Build	Vite	7.x	Phát triển & đóng gói
Styling	Tailwind CSS	4.1.x	Utility-first CSS
Desktop	Tauri	2.9.1	Native desktop framework
Backend (Tauri)	Rust	Stable	Lớp native POS

4.2. Quản lý Trạng thái

Phạm vi	Thư viện	Phiên bản	Trường hợp sử dụng
Server State	TanStack Query	5.90.5	Lấy dữ liệu API & caching
Global UI State	Redux Toolkit	2.9.x	Giỏ hàng, tùy chọn người dùng, điều hướng
Form State	React Hook Form	7.66.0	Xác thực form với Zod
Admin Framework	react-admin	5.13.x	Thao tác CRUD, data provider

4.3. Thành phần UI

Thư viện	Phiên bản	Mục đích
Radix UI	Mới nhất	Các thành phần cơ sở dễ tiếp cận
shadcn/ui	Mới nhất	Các thành phần dựng sẵn
Lucide Icons	0.562.0	Thư viện biểu tượng
TanStack Table	8.21.3	Bảng dữ liệu
TanStack Virtual	Mới nhất	Danh sách ảo hóa
Recharts	2.15.4	Biểu đồ (sale-renderer)

4.4. Đặc thù Tauri (sale-main)

Thư viện	Mục đích
sea-orm	SQLite ORM
reqwest	HTTP client
tokio	Async runtime
serde	JSON serialization
tracing	Ghi log có cấu trúc

5. Cấu trúc Thư mục

5.1. Cấu trúc Ứng dụng Chung

apps/{app-name}/
├── src/
│   ├── application/          # DI container, providers, API services
│   ├── components/           # React components
│   │   ├── core/             # Custom components
│   │   └── shadcn/           # shadcn UI components
│   ├── constants/            # Routes, endpoints, configurations
│   ├── helpers/              # Utility functions
│   ├── hooks/                # Custom React hooks
│   ├── interfaces/           # TypeScript interfaces
│   ├── layout/               # Layout components
│   ├── libs/                 # Library configurations
│   ├── redux/                # State management
│   ├── screens/              # Page components
│   ├── App.tsx               # Root component
│   ├── main.tsx              # Entry point
│   └── index.css             # Global styles
├── public/                   # Static assets
├── index.html                # HTML entry
├── package.json
├── tsconfig.json
├── vite.config.ts
└── tailwind.config.ts

5.2. Cấu trúc Cụ thể theo Ứng dụng

Back Office (client)

src/
├── screens/                  # 23 module màn hình
│   ├── product/              # Quản lý sản phẩm
│   ├── category/             # Quản lý danh mục
│   ├── merchant/             # Quản lý merchant
│   ├── organizer/            # Quản lý tổ chức
│   ├── customer/             # Quản lý khách hàng
│   ├── user/                 # Quản lý người dùng
│   ├── employee/             # Quản lý nhân viên
│   ├── role/                 # Quản lý vai trò
│   ├── device/               # Quản lý thiết bị
│   ├── sale-channel/         # Cấu hình kênh bán hàng
│   ├── terminal/             # Quản lý terminal
│   ├── order/                # Quản lý đơn hàng
│   ├── invoice/              # Quản lý hóa đơn
│   ├── transaction/          # Lịch sử giao dịch
│   ├── report/               # Dashboard báo cáo
│   │   ├── revenue/
│   │   └── orders/
│   ├── settings/             # Cài đặt hệ thống
│   ├── sign-in/
│   ├── sign-up/
│   └── home/                 # Dashboard
├── application/
│   └── services/             # 20+ dịch vụ API
└── redux/
    └── slices/               # 5 Redux slices
        ├── route/
        ├── temporary/
        ├── common/
        ├── product/
        └── listView/

POS UI (sale-renderer)

src/
├── screens/                  # 8 module màn hình
│   ├── sale/                 # Màn hình POS chính
│   ├── home/                 # Dashboard
│   ├── settings/             # Cài đặt
│   ├── customer/             # Hiển thị khách hàng
│   ├── errors/               # Trang lỗi
│   ├── sign-in/
│   └── term-of-use/
├── hooks/
│   └── screens/
│       └── sale/             # Hooks riêng cho bán hàng
│           ├── useCart.ts
│           ├── useProductVariant.ts
│           └── usePayment.ts
├── socket/                   # Tích hợp WebSocket
│   ├── connection-manager.ts
│   └── subscription-manager.ts
└── redux/
    └── slices/               # 8 Redux slices
        ├── cart/             # Giỏ hàng
        ├── order/            # Trạng thái đơn hàng
        ├── payment/          # Xử lý thanh toán
        ├── product/          # Danh mục sản phẩm
        ├── sale/             # Hoạt động bán hàng
        ├── userProfile/
        ├── common/
        └── temporary/

Tauri Backend (sale-main)

src-tauri/
├── src/
│   ├── application/          # Khởi tạo ứng dụng
│   │   ├── application.rs
│   │   ├── context.rs
│   │   └── logger.rs
│   ├── pubs/                 # Lệnh IPC (17 modules)
│   │   ├── login_pub.rs
│   │   ├── user_pub.rs
│   │   ├── merchant_pub.rs
│   │   ├── product_pub.rs
│   │   ├── category_pub.rs
│   │   ├── cart_pub.rs
│   │   ├── order_pub.rs
│   │   ├── payment_pub.rs
│   │   ├── payment_attempt.rs
│   │   ├── asset_pub.rs
│   │   ├── role_pub.rs
│   │   ├── permission_pub.rs
│   │   ├── sale_channel_pub.rs
│   │   ├── organizer_pub.rs
│   │   └── product_variant_pub.rs
│   ├── services/             # Logic nghiệp vụ (12 modules)
│   │   ├── auth_service.rs
│   │   ├── user_service.rs
│   │   ├── cart_service.rs
│   │   ├── cart_item_service.rs
│   │   ├── order_service.rs
│   │   ├── payment_service.rs
│   │   ├── api_network_service.rs
│   │   └── base_service.rs
│   ├── datasource/           # SQLite database
│   ├── entities/             # Database schemas
│   ├── helpers/              # Tiện ích
│   ├── main.rs
│   └── lib.rs
├── migration/                # DB migrations
├── capabilities/             # Quyền Tauri
└── tauri.conf.json           # Cấu hình Tauri

6. Dịch vụ API

6.1. Dịch vụ Back Office (20+)

Dịch vụ	Mục đích	Phương thức chính
AuthApi	Xác thực	signIn, signOut, refresh
OAuth2Api	Tích hợp OAuth	authorize, callback
UserApi	Quản lý người dùng	CRUD, profile
EmployeeApi	Quản lý nhân viên	CRUD, assign roles
RoleApi	Quản lý vai trò	CRUD, permissions
ProductApi	Danh mục sản phẩm	CRUD, aggregate
CategoryApi	Danh mục	CRUD, tree
VariantApi	Biến thể sản phẩm	CRUD
MerchantApi	Merchant	CRUD
OrganizerApi	Tổ chức	CRUD
OrderApi	Đơn hàng	CRUD, status
InvoiceApi	Hóa đơn	CRUD, generate
TransactionApi	Giao dịch	list, details
DeviceApi	Thiết bị	CRUD, activate
SaleChannelApi	Kênh bán hàng	CRUD, assign
BucketApi	Lưu trữ tệp	upload, download
MetaLinkApi	Liên kết metadata	CRUD
UserConfigurationApi	Cài đặt người dùng	CRUD
StaticAssetsApi	Phục vụ tệp tĩnh	serve
ReportApi	Báo cáo	revenue, orders

6.2. Dịch vụ POS (15)

Dịch vụ	Mục đích
AuthApi	Xác thực
UserApi	Hồ sơ người dùng
AssetApi	Truy cập tệp
MerchantApi	Dữ liệu merchant
OrganizerApi	Dữ liệu tổ chức
SaleChannelApi	Kênh bán hàng
CategoryApi	Danh mục
ProductApi	Danh mục sản phẩm
ProductVariantApi	Biến thể
CartApi	Quản lý giỏ hàng
CartItemApi	Mục giỏ hàng
OrderApi	Tạo đơn hàng
PaymentApi	Xử lý thanh toán
PaymentAttemptApi	Thử thanh toán

7. Quản lý Trạng thái

7.1. Redux Slices

Back Office

Slice	Trạng thái	Hành động
route	Route hiện tại, lịch sử	navigate, goBack
temporary	Modal, trạng thái tải	setModal, setLoading
common	Trạng thái ứng dụng toàn cục	setLanguage, setTheme
product	Trạng thái chỉnh sửa sản phẩm	setProduct, clearProduct
listView	Cấu hình bảng	setFilters, setSort

POS

Slice	Trạng thái	Hành động
cart	Mục giỏ hàng, tổng	addItem, removeItem, clearCart
order	Đơn hàng hiện tại	createOrder, updateStatus
payment	Trạng thái thanh toán	initiatePayment, confirmPayment
product	Danh mục sản phẩm	loadProducts, searchProducts
sale	Phiên bán hàng	openSession, closeSession
userProfile	Người dùng hiện tại	setUser, clearUser
common	Trạng thái toàn cục	setMerchant, setSaleChannel
temporary	Trạng thái UI	setLoading, setModal

7.2. Luồng Trạng thái

8. Cấu hình Định tuyến

8.1. Routes Back Office

Đường dẫn	Màn hình	Yêu cầu Auth
`/`	Home (Dashboard)	Có
`/product/*`	Quản lý sản phẩm	Có
`/category/*`	Quản lý danh mục	Có
`/merchant/*`	Quản lý merchant	Có
`/organizer/*`	Quản lý tổ chức	Có
`/customer/*`	Quản lý khách hàng	Có
`/user/*`	Quản lý người dùng	Có
`/employee/*`	Quản lý nhân viên	Có
`/role/*`	Quản lý vai trò	Có
`/device/*`	Quản lý thiết bị	Có
`/order/*`	Quản lý đơn hàng	Có
`/invoice/*`	Quản lý hóa đơn	Có
`/transaction/*`	Lịch sử giao dịch	Có
`/report/*`	Báo cáo	Có
`/settings/*`	Cài đặt	Có
`/sign-in`	Đăng nhập	Không
`/sign-up`	Đăng ký	Không

8.2. Routes POS

Đường dẫn	Màn hình	Yêu cầu Auth
`/sale`	POS Chính	Có
`/settings`	Cài đặt chung	Có
`/account-setting`	Cài đặt tài khoản	Có
`/store-setting`	Cài đặt cửa hàng	Có
`/customer`	Hiển thị khách hàng	Không
`/term-of-use`	Điều khoản sử dụng	Không
`/error/*`	Trang lỗi	Không

9. Giao tiếp Thời gian thực

9.1. WebSocket (POS)

🔌

Tích hợp Socket.IO

Xử lý sự kiện thời gian thực

📡SocketConnectionManager→Vòng đời kết nối

📬SocketSubscriptionManager→Đăng ký sự kiện

📦OrderSocketService→Xử lý sự kiện đơn hàng

9.2. Loại Sự kiện

Sự kiện	Nguồn	Mô tả
`order:created`	Server	Đơn hàng mới được tạo
`order:updated`	Server	Trạng thái đơn hàng thay đổi
`payment:confirmed`	Payment Gateway	Thanh toán thành công
`payment:failed`	Payment Gateway	Thanh toán thất bại

10. Giao tiếp Tauri IPC

10.1. Mẫu Command

10.2. Lệnh IPC (17 modules)

Module	Lệnh
login_pub	sign_in, sign_out, verify_token
user_pub	get_user, update_user
merchant_pub	list_merchants, get_merchant
product_pub	list_products, get_product, search
category_pub	list_categories, get_tree
cart_pub	get_cart, create_cart, clear_cart
order_pub	create_order, get_order, list_orders
payment_pub	initiate_payment, confirm_payment
asset_pub	upload_file, get_file

10.3. Lưu trữ Dữ liệu

Kho lưu trữ	Công nghệ	Mục đích
Local DB	SQLite + SeaORM	Dữ liệu ngoại tuyến
Cache	In-memory	Dữ liệu phiên
Keychain	OS Secure Storage	Token xác thực

11. Build & Triển khai

11.1. Cấu hình Build

Ứng dụng	Công cụ Build	Đầu ra	Lệnh
client	Vite 7	`dist/`	`bun run build`
sale-renderer	Vite 7	`dist/`	`bun run build`
sale-main	Cargo/Tauri	Native binary	`bun run tauri build`
admin-ui-kit	tsc	`dist/`	`bun run build`

11.2. Tối ưu hóa Vite

typescript

// Cấu hình Vite chung
{
  build: {
    minify: 'terser',
    rollupOptions: {
      output: {
        manualChunks: {
          react: ['react', 'react-dom'],
          admin: ['react-admin', 'ra-core'],
          infra: ['@minimaltech/ra-core-infra'],
          lodash: ['lodash'],
        }
      }
    }
  }
}

11.3. Mô hình Triển khai

12. Chất lượng Mã nguồn

12.1. Linting & Formatting

Công cụ	Cấu hình	Mục đích
ESLint	Strict React rules	Chất lượng mã
Prettier	Pre-commit hooks	Định dạng mã
TypeScript	Strict mode	An toàn kiểu

12.2. Yêu cầu An toàn Kiểu

Bật chế độ TypeScript "strict"
Không cho phép kiểu any tường minh
Tất cả phản hồi API được định kiểu với Zod schemas
Các kiểu được tạo tự động cho các hợp đồng API

13. Các bước Tiếp theo

Back Office (client) - Tài liệu quản trị web chi tiết
POS Terminal (sale-main) - Tài liệu backend Tauri
POS UI (sale-renderer) - Tài liệu frontend POS
Admin UI Kit - Tài liệu thư viện thành phần

Client Guide

Nhà cung cấp

Các loại Hóa đơn

Tổng quan Hệ sinh thái Client ​

1. Kiểm soát Tài liệu ​

2. Phạm vi & Mục tiêu ​

2.1. Phạm vi ​

2.2. Mục tiêu Chiến lược ​

3. Danh mục Ứng dụng ​

3.1. Tổng quan Ứng dụng ​

3.2. Chi tiết Ứng dụng ​

3.3. Sản phẩm bàn giao ​

4. Ngăn xếp Công nghệ ​

4.1. Công nghệ Cốt lõi ​

4.2. Quản lý Trạng thái ​

4.3. Thành phần UI ​

4.4. Đặc thù Tauri (sale-main) ​

5. Cấu trúc Thư mục ​

5.1. Cấu trúc Ứng dụng Chung ​

5.2. Cấu trúc Cụ thể theo Ứng dụng ​

Back Office (client) ​

POS UI (sale-renderer) ​

Tauri Backend (sale-main) ​

6. Dịch vụ API ​

6.1. Dịch vụ Back Office (20+) ​

6.2. Dịch vụ POS (15) ​

7. Quản lý Trạng thái ​

7.1. Redux Slices ​

Back Office ​

POS ​

7.2. Luồng Trạng thái ​

8. Cấu hình Định tuyến ​

8.1. Routes Back Office ​

8.2. Routes POS ​

9. Giao tiếp Thời gian thực ​

9.1. WebSocket (POS) ​

9.2. Loại Sự kiện ​

10. Giao tiếp Tauri IPC ​

10.1. Mẫu Command ​

10.2. Lệnh IPC (17 modules) ​

10.3. Lưu trữ Dữ liệu ​

11. Build & Triển khai ​

11.1. Cấu hình Build ​

11.2. Tối ưu hóa Vite ​

11.3. Mô hình Triển khai ​

12. Chất lượng Mã nguồn ​

12.1. Linting & Formatting ​

12.2. Yêu cầu An toàn Kiểu ​

13. Các bước Tiếp theo ​