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`
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-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
tauri-plugin-external-display	`./tauri-plugin-external-display`	Quản lý màn hình khách hàng

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

React UI

→

Tauri IPC

→

Lệnh Rust

→

Phần cứng / HĐH

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:

rust

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)
│   ├── 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
│   ├── 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
│   │   └── 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
│   │   └── request.rs              # Tiện ích yêu cầu
│   ├── pubs/                       # Các lệnh Tauri (16 modules)
│   │   ├── mod.rs
│   │   ├── asset_pub.rs
│   │   ├── cart_pub.rs
│   │   ├── category_pub.rs
│   │   ├── common_pub.rs
│   │   ├── login_pub.rs
│   │   ├── merchant_pub.rs
│   │   ├── order_pub.rs
│   │   ├── organizer_pub.rs
│   │   ├── payment_attempt.rs
│   │   ├── payment_pub.rs
│   │   ├── permission_pub.rs
│   │   ├── product_pub.rs
│   │   ├── product_variant_pub.rs
│   │   ├── role_pub.rs
│   │   ├── sale_channel_pub.rs
│   │   └── user_pub.rs
│   └── services/                   # Dịch vụ nghiệp vụ (11 modules)
│       ├── mod.rs
│       ├── api_network_service.rs
│       ├── asset_service.rs
│       ├── auth_service.rs
│       ├── base_service.rs
│       ├── cart_service.rs
│       ├── cart_item_service.rs
│       ├── order_service.rs
│       ├── payment_service.rs
│       ├── payment_attempt_service.rs
│       ├── trail_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
├── Cargo.toml                      # Workspace manifest
├── tauri.conf.json                 # Cấu hình Tauri
└── build.rs                        # Script build

6. Các lệnh Tauri

6.1. Lệnh CRUD

Được tạo tự động cho các thao tác phổ biến thông qua macros:

Tài nguyên	Thao tác
merchant	find, find_one, create, update, delete
category	find, find_one, create, update, delete
product	find, find_one, create, update, delete
product_variant	find, find_one, create, update, delete
organizer	find, find_one, create, update, delete
sale_channel	find, find_one, create, update, delete
cart	find, find_one, create, update, delete
cart_item	find, find_one, create, update, delete

6.2. Lệnh Tùy chỉnh

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 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
`user_controller_get_user_profile`	user_pub	Lấy hồ sơ người dùng
`cart_controller_cart_items`	cart_pub	Lấy các mục giỏ hàng
`cart_controller_add_item`	cart_pub	Thêm mục vào giỏ hàng
`cart_controller_clear_cart`	cart_pub	Xóa giỏ hàng
`cart_item_controller_update_quantity`	cart_pub	Cập nhật số lượng mục
`order_controller_checkout`	order_pub	Tạo đơn hàng từ giỏ hàng
`order_controller_revert_checkout`	order_pub	Hủy checkout
`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	Tìm lần thử thanh toán

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

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	Quản lý tài sản/tệp
CartService	Logic giỏ hàng mua sắm
CartItemService	Quản lý mục giỏ hàng
OrderService	Tạo & quản lý đơn hàng
PaymentService	Xử lý thanh toán
PaymentAttemptService	Theo dõi lần thử thanh toán
TrailServices	Ghi nhật ký kiểm toán

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ở:

rust

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ộ:

rust

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:

rust

Migrator::up(&datasource.connection, None).await?;

10. Vòng đời Ứng dụng

10.1. Luồng Khởi động

1. Application::new()
   └── Lấy thư mục cơ sở
2. Application::build()
   ├── Tạo Tauri Builder
   ├── Quản lý tùy chọn & thư mục cơ sở
   ├── bind_plugins() - Gắn tất cả plugins
   ├── bind_commands() - Đăng ký các lệnh IPC
   └── setup() - Khởi tạo bất đồng bộ
       ├── configure() - Thiết lập datasource & trạng thái
       │   ├── Cấu hình cơ sở dữ liệu SQLite
       │   ├── Tạo ServiceContainer
       │   ├── Tạo RepositoryContainer
       │   └── Quản lý AppState
       ├── Phát sự kiện "init_ready"
       └── migrate() - Chạy migration cơ sở dữ liệu
           └── Phát sự kiện "migration_error" nếu thất bại
3. builder.run() - Bắt đầu Tauri runtime

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

toml

[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
]

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

rust

#[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/POS

12.2. Chỉ Mobile (Android)

rust

#[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 native

13. Cấu hình Build

13.1. Profile Release

Tối ưu hóa cho kích thước binary nhỏ nhất:

toml

[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 debug

13.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
File Mã nguồn Rust	~75
Lệnh Tauri	50+
Plugin Tùy chỉnh	3
Dịch vụ	11
Thực thể Cơ sở dữ liệu	1+
Workspace Crates	7

Client Guide

Nhà cung cấp

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

POS Terminal (Tiến trình Host) ​

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 ​

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

3.1. Các phụ thuộc Cốt lõi ​

3.2. Tauri Plugins ​

3.3. Tauri Plugins Tùy chỉnh ​

3.4. Công cụ Phát triển ​

4. Kiến trúc ​

4.1. Giao tiếp IPC ​

4.2. Ngữ cảnh Ứng dụng (Application Context) ​

4.3. Cấu trúc Module ​

5. Cấu trúc Dự án ​

6. Các lệnh Tauri ​

6.1. Lệnh CRUD ​

6.2. Lệnh Tùy chỉnh ​

7. Plugins Tùy chỉnh ​

7.1. Plugin USB (tauri-plugin-usb) ​

7.2. Plugin Thanh toán (tauri-plugin-payment) ​

7.3. Plugin Màn hình Ngoài (tauri-plugin-external-display) ​

8. Lớp Dịch vụ (Services Layer) ​

8.1. Kiến trúc Dịch vụ ​

8.2. Mẫu Dịch vụ Cơ sở ​

9. Lớp Cơ sở dữ liệu ​

9.1. Cấu hình Datasource ​

9.2. Vị trí Cơ sở dữ liệu ​

9.3. Migrations ​

10. Vòng đời Ứng dụng ​

10.1. Luồng Khởi động ​

10.2. Sự kiện ​

11. Cấu trúc Workspace ​

11.1. Các thành viên Workspace ​

11.2. Các Crates Nội bộ ​

12. Các tính năng Đặc thù Nền tảng ​

12.1. Chỉ Desktop ​

12.2. Chỉ Mobile (Android) ​

13. Cấu hình Build ​

13.1. Profile Release ​

13.2. Artifacts Build ​

14. Phát triển ​

14.1. Điều kiện Tiên quyết ​

14.2. Biến Môi trường ​

15. Thống kê Mã nguồn ​

POS Terminal (Tiến trình Host)

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

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

3.1. Các phụ thuộc Cốt lõi

3.2. Tauri Plugins

3.3. Tauri Plugins Tùy chỉnh

3.4. Công cụ Phát triển

4. Kiến trúc

4.1. Giao tiếp IPC

4.2. Ngữ cảnh Ứng dụng (Application Context)

4.3. Cấu trúc Module

5. Cấu trúc Dự án

6. Các lệnh Tauri

6.1. Lệnh CRUD

6.2. Lệnh Tùy chỉnh

7. Plugins Tùy chỉnh

7.1. Plugin USB (`tauri-plugin-usb`)

7.2. Plugin Thanh toán (`tauri-plugin-payment`)

7.3. Plugin Màn hình Ngoài (`tauri-plugin-external-display`)

8. Lớp Dịch vụ (Services Layer)

8.1. Kiến trúc Dịch vụ

8.2. Mẫu Dịch vụ Cơ sở

9. Lớp Cơ sở dữ liệu

9.1. Cấu hình Datasource

9.2. Vị trí Cơ sở dữ liệu

9.3. Migrations

10. Vòng đời Ứng dụng

10.1. Luồng Khởi động

10.2. Sự kiện

11. Cấu trúc Workspace

11.1. Các thành viên Workspace

11.2. Các Crates Nội bộ

12. Các tính năng Đặc thù Nền tảng

12.1. Chỉ Desktop

12.2. Chỉ Mobile (Android)

13. Cấu hình Build

13.1. Profile Release

13.2. Artifacts Build

14. Phát triển

14.1. Điều kiện Tiên quyết

14.2. Biến Môi trường

15. Thống kê Mã nguồn