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.1-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 | ~6.0.2 | 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
Màn hình BO nằm trong src/screens/ theo hai tầng định tuyến: các module quản trị cấp root/organizer (auth/root/, 29 thư mục module) và một không gian làm việc theo từng merchant (auth/merchant/$merchant-id/). Mỗi module thường cung cấp các chế độ xem danh sách / tạo / sửa (hoặc xem chi tiết). Tên module bên dưới là tên thư mục nguồn thực tế; cột đường dẫn phản ánh hằng số route trong src/constants/routes.ts.
5.1. Định danh & Truy cập
| Module | Đường dẫn | Mô tả |
|---|---|---|
organizer | /organizer | Quản lý tổ chức (thực thể cha) |
merchant | /merchants | Quản lý hồ sơ merchant |
user | /user | Tài khoản người dùng nền tảng |
merchant-user | /merchant-user | Tài khoản người dùng theo merchant |
role | /role | Quản lý vai trò |
permission | /permission | Quản lý quyền hạn |
policy-definition | /policy-definition | Định nghĩa policy Casbin |
5.2. Danh mục & Cấu hình
| Module | Đường dẫn | Mô tả |
|---|---|---|
categories-product | /categories-product | Danh mục sản phẩm |
category-template | /category-template | Mẫu danh mục tái sử dụng |
unit-of-measure | /unit-of-measure | Đơn vị tính |
tax-group | /tax-group | Cấu hình nhóm thuế |
settings | /settings | Cài đặt toàn ứng dụng |
5.3. Gói Đăng ký & Cấp phép
| Module | Đường dẫn | Mô tả |
|---|---|---|
subscription-plan | /subscription-plan | Danh mục gói đăng ký |
license | /license | Bản ghi giấy phép |
activation | /activation | Bản ghi kích hoạt giấy phép |
onboarding | /onboarding | Luồng khởi tạo merchant |
5.4. Outreach
| Module | Đường dẫn | Mô tả |
|---|---|---|
outreach-inquiry | /outreach-inquiry | Yêu cầu outreach đến |
outreach-subscriber | /outreach-subscriber | Người đăng ký outreach |
5.5. Help Desk
| Module | Đường dẫn | Mô tả |
|---|---|---|
agent | /agent | Nhân viên hỗ trợ |
agent-group | /agent-group | Nhóm nhân viên |
assignment-rule | /assignment-rule | Quy tắc phân công ticket |
sla-policy | /sla-policy | Chính sách SLA |
hd-ticket-category | /hd-ticket-category | Danh mục ticket |
hd-ticket-tag | /hd-ticket-tag | Nhãn ticket |
5.6. Tồn kho & Thiết bị
| Module | Đường dẫn | Mô tả |
|---|---|---|
vendors | /inventory-vendors | Quản lý nhà cung cấp |
locations | /inventory-locations | Địa điểm kho |
devices | /device | Đăng ký thiết bị |
5.7. Trang chủ & Báo cáo
| Module | Đường dẫn | Mô tả |
|---|---|---|
home | / | Trang chủ bảng điều khiển |
report | /report | Báo cáo doanh thu và vận hành |
5.8. Không gian Làm việc Merchant
Phạm vi dưới /merchant/:merchantId/ và được nạp từ merchant đã chọn (auth/merchant/$merchant-id/):
| Module | Đường dẫn | Mô tả |
|---|---|---|
sale | /sale-order, /transaction, /sale-channel | Đơn bán hàng, giao dịch, kênh bán hàng |
finance | /finance-category, /finance-account, /finance-voucher | Danh mục, tài khoản, chứng từ tài chính |
report | /ledger, /revenue/by-day, /revenue/by-product, /revenue/by-category | Sổ cái và báo cáo doanh thu |
role | /role | Vai trò theo merchant |
setting-general | /general | Cài đặt chung của merchant |
merchant | /merchant/:merchantId | Chi tiết merchant (tạo / sửa) |
5.9. Xác thực
| Module | Đường dẫn | Mô tả |
|---|---|---|
sign-in | /sign-in | Màn hình đăng nhập (no-auth/) |
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 (nhóm theo module), 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 | 10 module không gian merchant (vận hành POS) + luồng onboarding/organizer | 29 module quản trị cấp root/organizer + 6 module không gian 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