Back Office (Quản lý Merchant)
1. Kiểm soát Tài liệu
| Thuộc tính | Giá trị |
|---|---|
| Gói | @nx-app/bo |
| Phiên bản | 0.0.0 |
| Loại | Ứng dụng Web (SPA) |
| Môi trường chạy | Trình duyệt / Bun (dev) |
| Triển khai | Docker / Nginx |
2. Phạm vi & Mục tiêu
2.1. Phạm vi
Back Office (bo) là giao diện quản lý merchant cho nền tảng BANA. Ứng dụng cung cấp cho chủ doanh nghiệp, nhân viên vận hành và quản trị viên hệ thống các công cụ để quản lý merchant, sản phẩm, danh mục, tồn kho, hóa đơn, tài chính và hoạt động nhân sự thông qua trình duyệt web.
2.2. Mục tiêu
- Quản lý Merchant: Quản lý toàn bộ vòng đời của merchant, tổ chức và mối quan hệ nhà cung cấp.
- Vận hành Toàn diện: Sản phẩm, danh mục, tồn kho, đơn mua hàng, đơn bán hàng, hóa đơn và quản lý tài chính.
- Phân quyền theo Vai trò: Các màn hình được kiểm soát quyền truy cập cho từng vai trò người dùng khác nhau.
- Trực quan hóa Dữ liệu: Báo cáo doanh thu, đơn hàng và hiệu suất sản phẩm.
- Thiết kế Responsive: Hỗ trợ trình duyệt trên máy tính, máy tính bảng và thiết bị di động.
3. Công nghệ Sử dụng
3.1. Framework Chính
| Công nghệ | Phiên bản | Mục đích |
|---|---|---|
| React | ^19.2.1 | Thư viện UI Component |
| React DOM | ^19.2.1 | Render DOM |
| React Router | ^7.9.4 | Định tuyến phía Client |
| TypeScript | ~5.9.3 | Kiểm tra kiểu dữ liệu |
| Vite | ^7.1.7 | Công cụ Build & Dev Server |
3.2. Quản lý Trạng thái
| Công nghệ | Phiên bản | Mục đích |
|---|---|---|
| Redux Toolkit | ^2.9.1 | Quản lý trạng thái toàn cục |
| React Redux | ^9.2.0 | Kết nối React-Redux |
| TanStack Query | ^5.90.5 | Trạng thái Server & Bộ nhớ đệm |
| TanStack Table | ^8.21.3 | Quản lý Bảng dữ liệu |
| ra-core | ^5.13.2 | Lõi Admin Framework |
3.3. Thành phần Giao diện
| Công nghệ | Phiên bản | Mục đích |
|---|---|---|
| @nx-app/admin-ui-kit | workspace:* | Thư viện UI Component dùng chung |
| Radix UI | ^1.4.3 | Primitive hỗ trợ truy cập |
| Tailwind CSS | ^4.1.16 | CSS tiện ích |
| Lucide React | ^0.552.0 | Thư viện biểu tượng |
| next-themes | ^0.4.6 | Chuyển đổi giao diện |
3.4. Biểu mẫu & Xác thực dữ liệu
| Công nghệ | Phiên bản | Mục đích |
|---|---|---|
| React Hook Form | ^7.66.0 | Quản lý trạng thái biểu mẫu |
| @hookform/resolvers | ^5.2.2 | Cầu nối xác thực Schema |
| react-phone-number-input | ^3.4.14 | Nhập số điện thoại |
| react-number-format | ^5.4.4 | Định dạng số |
| react-day-picker | ^9.13.2 | Chọn ngày |
3.5. Tiện ích
| Công nghệ | Phiên bản | Mục đích |
|---|---|---|
| @dnd-kit | Nhiều | Kéo-thả (sắp xếp) |
| xlsx | ^0.18.5 | Nhập/Xuất Excel |
| papaparse | ^5.5.3 | Phân tích CSV |
| compressorjs | ^1.2.1 | Nén hình ảnh |
| dayjs | ^1.11.18 | Định dạng ngày tháng |
| sonner | ^2.0.7 | Thông báo Toast |
4. Kiến trúc
4.1. Khởi tạo Ứng dụng
Ứng dụng BO mở rộng AdminUiKitApplication thông qua RaApplication:
typescript
class RaApplication extends AdminUiKitApplication {
// Initializes 18+ API services:
// Auth, Merchant, Product, Category, User, Employee,
// SaleChannel, SaleOrder, Invoice, Inventory, Finance,
// Payment, Transaction, Role, Device, Report, etc.
}ApplicationContext bao bọc ứng dụng với:
CoreApplicationContext— Ngữ cảnh Admin framework- Redux
Provider— Trạng thái toàn cục ThemeProvider— Chế độ sáng/tốiTooltipProvider— Tooltip toàn cục
4.2. Cấu hình
| Cấu hình | Nguồn | Mặc định |
|---|---|---|
| API Base URL | VITE_BASE_URL | http://localhost:3000/api |
| OAuth URL | VITE_NX_OAUTH_BASE_URL | — |
| Tên ứng dụng | package.json | @nx-app/bo |
4.3. Tầng Dữ liệu
- DefaultRestDataProvider cho toàn bộ giao tiếp API
- DefaultAuthService cho xác thực JWT
- TanStack Query cho bộ nhớ đệm trạng thái server và vô hiệu hóa cache
- Redux cho trạng thái UI (sidebar, bộ lọc, tùy chọn)
5. Các Module Màn hình
Ứng dụng BO bao gồm 29 module màn hình, mỗi module cung cấp các chế độ xem danh sách/tạo/đọc/cập nhật/xóa:
5.1. Nghiệp vụ Chính
| Module | Đường dẫn | Mô tả |
|---|---|---|
merchant | /merchants | Quản lý hồ sơ merchant |
organizer | /organizers | Quản lý tổ chức (thực thể cha) |
vendor | /vendors | Quản lý nhà cung cấp |
settings | /settings | Cài đặt toàn ứng dụng |
5.2. Danh mục Sản phẩm
| Module | Đường dẫn | Mô tả |
|---|---|---|
product | /products | CRUD sản phẩm và danh mục |
category | /categories | Phân cấp danh mục |
category-template | /category-templates | Mẫu danh mục tái sử dụng |
sale-channel | /sale-channels | Cấu hình đa kênh bán hàng |
5.3. Bán hàng & Đơn hàng
| Module | Đường dẫn | Mô tả |
|---|---|---|
sale-order | /sale-orders | Quản lý đơn bán hàng |
purchase-order | /purchase-orders | Vòng đời đơn mua hàng |
invoice | /invoices | Tạo và theo dõi hóa đơn |
transaction | /transactions | Bản ghi giao dịch thanh toán |
5.4. Tồn kho & Kho hàng
| Module | Đường dẫn | Mô tả |
|---|---|---|
inventory | /inventory | Quản lý tồn kho |
inventory-tracking | /inventory-tracking | Theo dõi biến động kho |
importation | /importations | Thao tác nhập kho |
5.5. Tài chính
| Module | Đường dẫn | Mô tả |
|---|---|---|
finance | /finance | Giao dịch tài chính, danh mục, ví |
5.6. Nhân sự
| Module | Đường dẫn | Mô tả |
|---|---|---|
customer | /customers | Cơ sở dữ liệu khách hàng |
user | /users | Tài khoản người dùng |
user-employee | /employees | Quản lý nhân viên |
role | /roles | Quản lý vai trò & quyền hạn |
5.7. Thiết bị & Báo cáo
| Module | Đường dẫn | Mô tả |
|---|---|---|
terminal | /terminals | Quản lý máy POS |
devices | /devices | Đăng ký thiết bị |
report | /reports | Báo cáo doanh thu, đơn hàng và sản phẩm |
5.8. Xác thực
| Module | Đường dẫn | Mô tả |
|---|---|---|
sign-in | /sign-in | Màn hình đăng nhập |
sign-up | /sign-up | Màn hình đăng ký |
home | / | Trang chủ bảng điều khiển |
6. Hệ thống Bố cục
6.1. Bố cục Chính
Bố cục có xác thực với thanh điều hướng bên có thể thu gọn (29 mục menu), header với hồ sơ người dùng và vùng nội dung.
6.2. Bố cục Biểu mẫu
BaseFormLayout cung cấp các trang biểu mẫu chuẩn hóa với:
- Thanh bộ lọc — Bộ lọc TextField, dropdown trạng thái
- Nút hành động — Lưu, Hủy, các hành động tùy chỉnh
- RouteContextProvider — Ngữ cảnh định tuyến cấp màn hình
6.3. Bố cục Không xác thực
Bố cục tối giản cho màn hình đăng nhập/đăng ký không có thanh điều hướng bên.
7. Custom Hooks
7.1. API Hooks
| Hook | Mục đích |
|---|---|
useGetData | Lấy dữ liệu với TanStack Query |
useInfiniteGetData | Lấy dữ liệu cuộn vô hạn |
useMutationData | Mutation tạo/cập nhật/xóa |
useRefresh | Buộc làm mới dữ liệu |
useVirtualAutocomplete | Autocomplete ảo hóa (đơn) |
useVirtualAutocompleteArray | Autocomplete ảo hóa (nhiều) |
7.2. State Hooks
| Hook | Mục đích |
|---|---|
useAppDispatch | Redux dispatch có kiểu |
useAppSelector | Redux selector có kiểu |
useUserPreferences | Lưu trữ tùy chọn người dùng |
useUserProfile | Dữ liệu hồ sơ người dùng hiện tại |
useLogout | Luồng đăng xuất |
useWarnUnsavedChanges | Cảnh báo thay đổi chưa lưu |
7.3. Table Hooks
| Hook | Mục đích |
|---|---|
useDataTableController | Trạng thái bảng + lấy dữ liệu |
useDataTableState | Trạng thái cột/bộ lọc của bảng |
useBaseTableAutosave | Tự động lưu chỉnh sửa trực tiếp |
8. Build & Triển khai
8.1. Cấu hình Vite
- Tách mã: Chunk thủ công cho gói infra
- Cảnh báo kích thước chunk: Giới hạn 600KB
- PWA: Chiến lược tự động cập nhật, không có manifest
- Dev server: Cổng 3000, strict port, bật HMR
8.2. Build Docker
Build đa giai đoạn:
dockerfile
# Stage 1: Dependencies (bun:1-alpine)
# Stage 2: Build (bun run build:production)
# Stage 3: Production (nginx:1.27-alpine)8.3. Cấu hình Nginx
| Tính năng | Cài đặt |
|---|---|
| Nén | Bật Gzip (text, JS, CSS, JSON, SVG) |
| Header Bảo mật | X-Frame-Options, X-Content-Type-Options, X-XSS-Protection |
| Cache Tài nguyên | 1 năm (immutable) |
| Service Worker | Cache 1 giờ |
| Định tuyến SPA | Chuyển hướng tất cả về index.html |
| File Ẩn | Từ chối (ngoại trừ .well-known) |
8.4. Scripts
| Script | Lệnh | Mục đích |
|---|---|---|
dev | vite --mode dev | Server phát triển |
build | sh ./scripts/build.sh | Build production |
build:develop | sh ./scripts/rebuild.sh development | Build development |
build:production | sh ./scripts/rebuild.sh production | Build production |
preview | vite preview --port 4173 | Xem trước bản build production |
lint | sh ./scripts/lint.sh | ESLint + Prettier |
9. Khác biệt so với Ứng dụng Client
| Khía cạnh | Client (@nx-app/client) | BO (@nx-app/bo) |
|---|---|---|
| Mục đích | Bảng điều khiển quản trị (quản lý toàn nền tảng) | Quản lý tập trung vào merchant |
| Phạm vi | Quản trị toàn bộ nền tảng | Vận hành merchant |
| Modules | 29 màn hình | 29 màn hình (hướng merchant) |
| Công cụ bổ sung | — | Nhập/xuất Excel, phân tích CSV, nén hình ảnh, kéo-thả |
10. Tài liệu Liên quan
- Ứng dụng Client — Back Office Client
- Admin UI Kit — Thư viện component dùng chung
- Dịch vụ Identity — Người dùng & xác thực
- Dịch vụ Commerce — Danh mục sản phẩm