POS Terminal (Tiến trình Host)
1. Kiểm soát Tài liệu
| Thuộc tính | Giá trị |
|---|---|
| Gói | @nx-app/sale-main |
| Tên Crate | bana |
| Tên Thư viện | bana_lib |
| Loại | Ứng dụng Desktop (Host) |
| Phiên bản | 0.1.0 |
| Ngôn ngữ | Rust (Edition 2021) |
| Framework | Tauri 2.x |
2. Phạm vi & Mục tiêu
2.1. Phạm vi
Gói này tạo nên Tiến trình Host của ứng dụng POS. Được xây dựng bằng Tauri (Rust), nó là cầu nối giữa giao diện người dùng dựa trên web (sale-renderer) và phần cứng vật lý/hệ điều hành. Nó cung cấp các khả năng native mà chỉ công nghệ web không thể đạt được.
2.2. Mục tiêu
- Trừu tượng hóa Phần cứng: API thống nhất cho máy in, thiết bị USB và terminal thanh toán.
- Bảo mật: Lưu trữ an toàn token xác thực trong keychain của hệ điều hành.
- Lưu trữ Ngoại tuyến: Cơ sở dữ liệu SQLite cục bộ cho các hoạt động ngoại tuyến.
- Quản lý Cửa sổ: Hỗ trợ đa cửa sổ (Màn hình khách hàng).
- Đa nền tảng: Hỗ trợ Windows, macOS, Linux, Android và iOS.
3. Ngăn xếp Công nghệ
3.1. Các phụ thuộc Cốt lõi
| Phụ thuộc | Phiên bản | Mục đích |
|---|---|---|
| Tauri | 2.x | Framework ứng dụng Desktop |
| SeaORM | 2.0.0-rc | ORM cho cơ sở dữ liệu SQLite |
| SQLx | 0.8 | Bộ công cụ SQL bất đồng bộ |
| Tokio | 1.x | Runtime bất đồng bộ |
| Serde | 1.x | Tuần tự hóa/Giải tuần tự hóa |
| Chrono | 0.4 | Xử lý ngày/giờ |
| UUID | 1.0 | Tạo định danh duy nhất |
3.2. Tauri Plugins
| Plugin | Phiên bản | Mục đích |
|---|---|---|
| tauri-plugin-http | 2.x | Yêu cầu HTTP |
| tauri-plugin-fs | 2.0.0 | Truy cập hệ thống tệp |
| tauri-plugin-process | 2.x | Quản lý tiến trình |
| tauri-plugin-os | 2.3.2 | Thông tin hệ điều hành |
| tauri-plugin-opener | 2.x | Mở URL/tệp |
| tauri-plugin-log | 2.7.1 | Ghi nhật ký (Logging) |
| tauri-plugin-localhost | 2.3.1 | Máy chủ HTTP cục bộ |
| tauri-plugin-machine-uid | 0.1.3 | Nhận dạng máy |
| tauri-plugin-updater | 2.x | Tự động cập nhật (Desktop) |
3.3. Tauri Plugins Tùy chỉnh
| Plugin | Đường dẫn | Mục đích |
|---|---|---|
| tauri-plugin-external-display | ./tauri-plugin-external-display | Quản lý màn hình khách hàng |
| tauri-plugin-usb | ./tauri-plugin-usb | Giao tiếp thiết bị USB |
| tauri-plugin-payment | ./tauri-plugin-payment | Tích hợp terminal thanh toán (tính năng phonepos trên Android) |
| tauri-plugin-signal | ./tauri-plugin-signal | Tín hiệu WebSocket mã hóa (ECDH P-256 + AES-GCM) |
3.4. Công cụ Phát triển
| Công cụ | Phiên bản | Mục đích |
|---|---|---|
| Specta | 2.0.0-rc.22 | Tạo kiểu TypeScript |
| tauri-specta | 2.0.0-rc.21 | Tạo kiểu lệnh Tauri |
| dotenvy | 0.15.7 | Biến môi trường |
4. Kiến trúc
4.1. Giao tiếp IPC
4.2. Ngữ cảnh Ứng dụng (Application Context)
Ứng dụng quản lý trạng thái chia sẻ thông qua cấu trúc AppContext:
pub struct AppContext {
pub datasource: Datasource,
pub services: ServiceContainer,
pub repositories: RepositoryContainer,
}4.3. Cấu trúc Module
lib.rs
├── application/ # Khởi động ứng dụng
│ ├── application.rs # Trình xây dựng ứng dụng chính
│ ├── context.rs # Trạng thái chia sẻ & DI containers
│ └── logger.rs # Cấu hình ghi nhật ký
├── controllers/ # Xử lý lệnh
├── datasource/ # Cấu hình cơ sở dữ liệu
├── entities/ # Các thực thể SeaORM
├── helpers/ # Các hàm tiện ích
├── pubs/ # Các module lệnh công khai
└── services/ # Các dịch vụ logic nghiệp vụ5. Cấu trúc Dự án
apps/sale-main/src-tauri/
├── src/
│ ├── main.rs # Điểm nhập ứng dụng
│ ├── lib.rs # Gốc thư viện (modules)
│ ├── prelude.rs # Import dùng chung
│ ├── application/ # Khởi động ứng dụng
│ │ ├── mod.rs
│ │ ├── application.rs # Cấu hình Tauri builder
│ │ ├── context.rs # AppState & containers
│ │ └── logger.rs # Thiết lập Fern logger
│ ├── controllers/ # Xử lý lệnh
│ │ ├── mod.rs # Macro lệnh CRUD/tùy chỉnh
│ │ └── tcp_printer_controller.rs
│ ├── datasource/ # Lớp cơ sở dữ liệu
│ │ ├── mod.rs
│ │ └── datasource.rs # Kết nối SQLite
│ ├── entities/ # Các thực thể SeaORM
│ │ ├── mod.rs
│ │ ├── prelude.rs
│ │ ├── payment_attempt.rs
│ │ ├── payment_result.rs
│ │ ├── transaction.rs
│ │ ├── transaction_item.rs
│ │ └── user_configuration.rs
│ ├── helpers/ # Tiện ích
│ │ ├── mod.rs
│ │ ├── error.rs # Xử lý lỗi
│ │ ├── network_request.rs # HTTP helpers
│ │ ├── base_fetcher.rs # Lấy dữ liệu
│ │ ├── date_time.rs # Tiện ích ngày/giờ
│ │ ├── printer.rs # Tiện ích máy in
│ │ └── request.rs # Tiện ích yêu cầu
│ ├── repositories/ # Repository SeaORM
│ │ ├── mod.rs
│ │ ├── prelude.rs
│ │ ├── base_repository.rs
│ │ ├── payment_attempt_repository.rs
│ │ ├── payment_result_repository.rs
│ │ ├── transaction_repository.rs
│ │ └── transaction_item_repository.rs
│ ├── pubs/ # Module lệnh Tauri (34 module *_pub)
│ │ ├── mod.rs
│ │ ├── allocation_layout_pub.rs
│ │ ├── allocation_unit_pub.rs
│ │ ├── allocation_usage_pub.rs
│ │ ├── allocation_zone_pub.rs
│ │ ├── asset_pub.rs
│ │ ├── category_pub.rs
│ │ ├── common_pub.rs
│ │ ├── configuration_pub.rs
│ │ ├── device_pub.rs
│ │ ├── finance_account_pub.rs
│ │ ├── finance_asset_pub.rs
│ │ ├── finance_category_pub.rs
│ │ ├── finance_transaction_pub.rs
│ │ ├── invoice_pub.rs
│ │ ├── kitchen_ticket_pub.rs
│ │ ├── login_pub.rs
│ │ ├── merchant_pub.rs
│ │ ├── organizer_pub.rs
│ │ ├── payment_attempt_pub.rs
│ │ ├── payment_pub.rs
│ │ ├── permission_pub.rs
│ │ ├── pin_auth_pub.rs
│ │ ├── pos_session_pub.rs
│ │ ├── product_pub.rs
│ │ ├── product_variant_pub.rs
│ │ ├── receipt_template_pub.rs
│ │ ├── reservation_pub.rs
│ │ ├── role_pub.rs
│ │ ├── sale_channel_pub.rs
│ │ ├── sale_customer_pub.rs
│ │ ├── sale_order_item_pub.rs
│ │ ├── sale_order_pub.rs
│ │ ├── setting_pub.rs
│ │ └── user_pub.rs
│ └── services/ # Dịch vụ nghiệp vụ (17 modules)
│ ├── mod.rs
│ ├── allocation_layout_service.rs
│ ├── allocation_usage_service.rs
│ ├── api_network_service.rs
│ ├── asset_service.rs
│ ├── auth_service.rs
│ ├── base_service.rs
│ ├── configuration_service.rs
│ ├── finance_asset_service.rs
│ ├── payment_attempt_service.rs
│ ├── payment_service.rs
│ ├── pin_auth_service.rs
│ ├── pos_session_service.rs
│ ├── reservation_service.rs
│ ├── sale_order_service.rs
│ ├── sale_report_service.rs
│ ├── trait_services.rs
│ └── user_service.rs
├── common/ # Crate tiện ích chia sẻ
│ ├── Cargo.toml
│ └── src/
│ ├── lib.rs
│ ├── constant.rs # Hằng số ứng dụng
│ ├── endpoint.rs # Các điểm cuối API
│ ├── macros.rs # Macros tiện ích
│ └── traits.rs # Traits chia sẻ
├── macros/ # Crate macros thủ tục
│ ├── Cargo.toml
│ └── src/
│ ├── lib.rs
│ ├── controller.rs # Macro controller
│ └── scoped_log.rs # Macro logging
├── migration/ # Migrations SeaORM
│ ├── Cargo.toml
│ └── src/
│ ├── lib.rs
│ ├── main.rs
│ └── m20251222_050923_create_tables.rs
├── tauri-plugin-usb/ # Plugin thiết bị USB
│ ├── Cargo.toml
│ └── src/
│ ├── lib.rs
│ ├── commands.rs
│ ├── desktop.rs
│ ├── mobile.rs
│ ├── error.rs
│ └── models.rs
├── tauri-plugin-payment/ # Plugin terminal thanh toán
│ ├── Cargo.toml
│ └── src/
│ ├── lib.rs
│ ├── commands.rs
│ ├── desktop.rs
│ ├── mobile.rs
│ ├── error.rs
│ └── models.rs
├── tauri-plugin-external-display/ # Plugin màn hình khách hàng
│ ├── Cargo.toml
│ └── src/
│ ├── lib.rs
│ ├── commands.rs
│ ├── desktop.rs
│ ├── mobile.rs
│ ├── error.rs
│ └── models.rs
├── tauri-plugin-signal/ # Plugin tín hiệu WebSocket mã hóa
│ ├── Cargo.toml
│ └── src/
│ ├── lib.rs
│ ├── client.rs
│ ├── commands.rs
│ ├── crypto.rs
│ ├── desktop.rs
│ ├── error.rs
│ └── models.rs
├── Cargo.toml # Workspace manifest
├── tauri.conf.json # Cấu hình Tauri
└── build.rs # Script build6. Các lệnh Tauri
6.1. Lệnh CRUD
Được tạo tự động qua macro create_crud_commands! (mỗi tài nguyên cung cấp find, find_one, create, update, delete). Các tài nguyên (từ controllers/mod.rs):
merchant, device, configuration, category, product, product_variant, organizer, sale_channel, receipt_template, invoice, finance_account, finance_category, finance_transaction, setting, sale_order, sale_order_item, sale_customer, reservation, allocation_layout, allocation_zone, allocation_unit, allocation_usage, pos_session.
6.2. Lệnh Tùy chỉnh
Được tạo qua macro create_commands! (và một vài hàm tự do):
| Lệnh | Module | Mô tả |
|---|---|---|
asset_controller_i18n_file | asset_pub | Tải bản dịch i18n |
asset_controller_vnpay_qr_frame_image | asset_pub | Lấy ảnh khung QR VNPay |
auth_controller_sign_in | login_pub | Xác thực người dùng |
auth_controller_sign_out | login_pub | Đăng xuất người dùng |
auth_controller_who_am_i | login_pub | Lấy người dùng hiện tại |
auth_controller_auth_token | login_pub | Lấy token xác thực đã lưu |
auth_controller_refresh_token | login_pub | Làm mới token xác thực |
user_controller_get_user_profile | user_pub | Lấy hồ sơ người dùng |
configuration_controller_get_payment_provider_integration | configuration_pub | Liệt kê tích hợp nhà cung cấp thanh toán |
finance_asset_controller_banks_vn | finance_asset_pub | Danh bạ ngân hàng Việt Nam |
sale_order_controller_draft | sale_order_pub | Tạo đơn nháp |
sale_order_controller_add_item | sale_order_item_pub | Thêm mục vào đơn |
sale_order_controller_clear_items | sale_order_pub | Xóa các mục của đơn |
sale_order_controller_checkout | sale_order_pub | Checkout đơn hàng |
sale_order_controller_revert_checkout | sale_order_pub | Hoàn tác checkout |
sale_order_controller_split | sale_order_pub | Tách đơn hàng |
sale_order_controller_cancel | sale_order_pub | Hủy đơn hàng |
reservation_controller_check_in | reservation_pub | Check-in đặt chỗ |
reservation_controller_cancel | reservation_pub | Hủy đặt chỗ |
payment_controller_checkout | payment_pub | Xử lý thanh toán |
payment_controller_cancel | payment_pub | Hủy thanh toán |
payment_controller_system_ipn | payment_pub | Xử lý IPN thanh toán |
payment_attempt_controller_find_by_id | payment_attempt_pub | Tìm lần thử thanh toán |
allocation_layout_controller_find_aggregate | allocation_layout_pub | Tải aggregate sơ đồ |
allocation_usage_controller_reassign | allocation_usage_pub | Gán lại allocation usage |
allocation_usage_controller_complete_batch | allocation_usage_pub | Hoàn tất lô usage |
allocation_usage_controller_available_units | allocation_usage_pub | Liệt kê unit khả dụng |
allocation_usage_controller_available_zones | allocation_usage_pub | Liệt kê zone khả dụng |
pos_session_controller_get_current | pos_session_pub | Lấy phiên POS hiện tại |
pos_session_controller_open | pos_session_pub | Mở phiên POS |
pos_session_controller_cash_movement | pos_session_pub | Ghi nhận biến động tiền mặt |
pos_session_controller_close | pos_session_pub | Đóng phiên POS |
pos_session_controller_z_report | pos_session_pub | Tạo Z-report |
pos_session_controller_x_report | pos_session_pub | Tạo X-report |
pin_auth_controller_mint | pin_auth_pub | Phát hành token xác thực PIN |
sale_report_controller_get_summary | sale_report_service | Báo cáo tổng hợp doanh số |
sale_report_controller_get_products | sale_report_service | Báo cáo doanh số theo sản phẩm |
sale_report_controller_get_categories | sale_report_service | Báo cáo doanh số theo danh mục |
get_app_env_name | (root) | Lấy tên môi trường build |
set_header | (root) | Đặt header cho yêu cầu API |
7. Plugins Tùy chỉnh
7.1. Plugin USB (tauri-plugin-usb)
Cung cấp giao tiếp thiết bị USB cho máy in nhiệt và các thiết bị ngoại vi khác.
| Lệnh | Mô tả |
|---|---|
get_devices | Liệt kê các thiết bị USB đã kết nối |
connect | Kết nối tới thiết bị USB |
send | Gửi dữ liệu tới thiết bị |
disconnect | Ngắt kết nối thiết bị |
get_connected_device | Lấy thiết bị đang kết nối |
Hỗ trợ Nền tảng:
- Desktop: Giao tiếp USB trực tiếp
- Mobile: Triển khai riêng cho nền tảng
7.2. Plugin Thanh toán (tauri-plugin-payment)
Xử lý tích hợp terminal thanh toán.
| Lệnh | Mô tả |
|---|---|
open_payment | Mở giao diện thanh toán |
Hỗ trợ Nền tảng:
- Desktop: Chưa triển khai (sử dụng web API)
- Mobile (Android): Tích hợp SDK thanh toán native
7.3. Plugin Màn hình Ngoài (tauri-plugin-external-display)
Quản lý màn hình hướng về phía khách hàng (màn hình phụ).
| Lệnh | Mô tả |
|---|---|
send_data | Gửi dữ liệu tới màn hình khách hàng |
Tính năng:
- Mở cửa sổ phụ trên màn hình ngoài
- Hỗ trợ màn hình VFD và LCD
- Cập nhật giỏ hàng thời gian thực
7.4. Plugin Tín hiệu (tauri-plugin-signal)
Một client WebSocket tín hiệu thời gian thực có mã hóa (trao đổi khóa ECDH P-256, HKDF, AES-GCM) dùng cho cập nhật đơn hàng/bếp trực tiếp.
| Lệnh | Mô tả |
|---|---|
connect | Kết nối tới server tín hiệu bằng token |
disconnect | Ngắt kết nối client |
send_message | Phát một sự kiện kèm payload JSON |
join_rooms | Đăng ký các room |
leave_rooms | Hủy đăng ký các room |
get_state | Lấy trạng thái kết nối hiện tại |
get_client_id | Lấy client id được gán |
update_token | Cập nhật token xác thực |
8. Lớp Dịch vụ (Services Layer)
8.1. Kiến trúc Dịch vụ
Các dịch vụ đóng gói logic nghiệp vụ và tương tác với các API bên ngoài:
| Dịch vụ | Mục đích |
|---|---|
| ApiNetworkService | HTTP client cho backend API |
| AuthService | Xác thực & quản lý token |
| UserService | Các thao tác hồ sơ người dùng |
| AssetService | Tải tài sản & tệp i18n |
| ConfigurationService | Cấu hình commerce & tích hợp nhà cung cấp thanh toán |
| FinanceAssetService | Danh bạ tài sản tài chính (ví dụ ngân hàng Việt Nam) |
| PaymentService | Checkout / hủy / IPN thanh toán |
| PaymentAttemptService | Theo dõi lần thử thanh toán |
| PinAuthService | Phát hành token xác thực PIN |
| PosSessionService | Vòng đời phiên POS & báo cáo X/Z |
| ReservationService | Quản lý đặt bàn |
| SaleOrderService | Vòng đời đơn hàng (nháp, checkout, tách, hủy) |
| SaleReportService | Báo cáo doanh số (tổng hợp, sản phẩm, danh mục) |
| AllocationLayoutService | Sơ đồ bố trí mặt bằng nhà hàng |
| AllocationUsageService | Sử dụng cấp phát bàn/khu vực |
| BaseService | Triển khai dịch vụ cơ sở dùng chung |
| trait_services | Các trait dịch vụ dùng chung |
8.2. Mẫu Dịch vụ Cơ sở
Tất cả các dịch vụ đều kế thừa một triển khai cơ sở:
pub trait BaseService {
fn new() -> Self;
// Các phương thức dịch vụ chung
}9. Lớp Cơ sở dữ liệu
9.1. Cấu hình Datasource
Cơ sở dữ liệu SQLite với SeaORM cho các hoạt động bất đồng bộ:
pub struct Datasource {
pub connection: DatabaseConnection,
}
pub struct DatasourceConnectionOptions {
pub path: String,
}9.2. Vị trí Cơ sở dữ liệu
| Môi trường | Đường dẫn |
|---|---|
| Debug | app_data/db/{app_name}.sqlite |
| Release | Thư mục dữ liệu ứng dụng của HĐH |
9.3. Migrations
Các migration cơ sở dữ liệu được quản lý thông qua SeaORM Migration:
Migrator::up(&datasource.connection, None).await?;10. Vòng đời Ứng dụng
10.1. Luồng Khởi động
10.2. Sự kiện
| Sự kiện | Payload | Mô tả |
|---|---|---|
init_ready | true | Ứng dụng khởi tạo thành công |
init_error | String | Khởi tạo thất bại |
migration_error | String | Migration cơ sở dữ liệu thất bại |
11. Cấu trúc Workspace
11.1. Các thành viên Workspace
[workspace]
members = [
".", # Ứng dụng chính
"macros", # Macros thủ tục
"migration", # Migrations cơ sở dữ liệu
"tauri-plugin-external-display", # Plugin màn hình khách hàng
"tauri-plugin-usb", # Plugin giao tiếp USB
"tauri-plugin-payment", # Plugin tích hợp thanh toán
"tauri-plugin-signal" # Plugin tín hiệu mã hóa
]11.2. Các Crates Nội bộ
| Crate | Mục đích |
|---|---|
common | Các hằng số, traits và macros dùng chung |
macros | Macros thủ tục (scoped_log, controller) |
migration | SeaORM database migrations |
12. Các tính năng Đặc thù Nền tảng
12.1. Chỉ Desktop
#[cfg(desktop)]
// Các tính năng chỉ có trên nền tảng desktop
- tauri-plugin-updater // Tự động cập nhật
- printers crate // Hỗ trợ máy in ESC/POS12.2. Chỉ Mobile (Android)
#[cfg(mobile)]
// Các tính năng chỉ có trên nền tảng di động
- tauri-plugin-payment // SDK thanh toán native13. Cấu hình Build
13.1. Profile Release
Tối ưu hóa cho kích thước binary nhỏ nhất:
[profile.release]
opt-level = "z" # Tối ưu hóa kích thước tối đa
lto = true # Tối ưu hóa thời gian liên kết (Link Time Optimization)
codegen-units = 1 # Nén tốt hơn
panic = "abort" # Loại bỏ mã unwinding
strip = true # Loại bỏ các biểu tượng debug13.2. Artifacts Build
| Nền tảng | Artifacts |
|---|---|
| Windows | .msi, .exe |
| macOS | .dmg, .app |
| Linux | .deb, .AppImage |
| Android | .apk, .aab |
14. Phát triển
14.1. Điều kiện Tiên quyết
| Yêu cầu | Mục đích |
|---|---|
| Rust | Chuỗi công cụ ổn định mới nhất |
| Tauri CLI | Build và phát triển |
| libwebkit2gtk-4.0-dev | Linux WebView |
| build-essential | Biên dịch Linux |
| Xcode CLI Tools | Biên dịch macOS |
14.2. Biến Môi trường
| Biến | Mục đích |
|---|---|
APP_ENV_APPLICATION_NAME | Tiền tố tên cơ sở dữ liệu |
EXTERNAL_PORT | Cổng máy chủ HTTP cục bộ |
15. Thống kê Mã nguồn
| Chỉ số | Số lượng |
|---|---|
| Lệnh Tauri | 50+ |
| Plugin Tùy chỉnh | 4 |
| Dịch vụ | 17 |
Module Lệnh (pubs/) | 34 |
| Thực thể Cơ sở dữ liệu | 5 |
| Thành viên Workspace | 7 |