Client Back Office

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

Thuộc tính	Giá trị
Gói	@nx-app/client
Phiên bản	0.0.2-37
Loại	Ứng dụng Web (SPA)
Runtime	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 Client là giao diện quản trị cho nền tảng BANA. Nó cung cấp cho các chủ doanh nghiệp, người vận hành và quản trị viên hệ thống các công cụ toàn diện để quản lý toàn bộ hoạt động của họ thông qua trình duyệt web.

2.2. Mục tiêu

• Quản lý Toàn diện: Kiểm soát hoàn toàn sản phẩm, danh mục, merchant, nhân viên và báo cáo.
• Trực quan hóa Dữ liệu: Biểu đồ và bảng phong phú cho thông tin kinh doanh chuyên sâu.
• Thiết kế Phản hồi (Responsive): Hoạt động tốt trên trình duyệt Máy tính để bàn, Máy tính bảng và Điện thoại di động.
• An toàn kiểu dữ liệu (Type Safety): An toàn kiểu đầu cuối với TypeScript và xác thực Zod.

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

3.1. Framework Cốt lõi

Công nghệ	Phiên bản	Mục đích
React	^19.2.1	Thư viện Thành phần UI
React DOM	^19.2.1	Kết xuất DOM
React Router	^7.9.4	Định tuyến phía Client
TypeScript	~5.9.3	An toàn kiểu dữ liệu

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	Liên kết React-Redux
TanStack Query	^5.90.5	Trạng thái Server & Caching
ra-core	^5.13.2	Lõi Framework Admin

3.3. Thành phần UI

Công nghệ	Phiên bản	Mục đích
@nx-app/admin-ui-kit	workspace:*	Thư viện Thành phần UI dùng chung
Radix UI	Various	Các thành phần cơ sở dễ tiếp cận
Tailwind CSS	^4.1.16	Utility-first Styling
Lucide React	^0.552.0	Thư viện Biểu tượng
next-themes	^0.4.6	Chuyển đổi Giao diện (Theme)

3.4. Biểu mẫu & Xác thực

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	Tích hợp Xác thực Schema
Zod	^4.1.12	Xác thực Schema thời gian chạy

3.5. Bảng Dữ liệu & Kéo-Thả

Công nghệ	Phiên bản	Mục đích
TanStack Table	^8.21.3	Bảng dữ liệu Headless
TanStack Virtual	^3.13.12	Danh sách ảo hóa
@dnd-kit/core	^6.3.1	Lõi Kéo-Thả
@dnd-kit/sortable	^10.0.0	Danh sách có thể sắp xếp

3.6. Build & Phát triển

Công nghệ	Phiên bản	Mục đích
Vite	^7.1.7	Công cụ Build & Dev Server
@vitejs/plugin-react	^5.0.4	Tích hợp React
vite-plugin-pwa	^1.1.0	Hỗ trợ PWA
ESLint	^9.36.0	Kiểm tra lỗi mã nguồn (Linting)
Prettier	3.6.2	Định dạng mã nguồn

4. Kiến trúc

4.1. Các lớp Ứng dụng

Yêu cầu Trình duyệt

→

React Router

→

Thành phần Màn hình

→

Dịch vụ API

→

Backend API

4.2. Context Providers

Ứng dụng bao bọc các thành phần với nhiều context providers để tiêm phụ thuộc (dependency injection) và quản lý trạng thái:

ApplicationContext
├── CoreApplicationContext (DI Container)
│   └── ReduxProvider (Quản lý Trạng thái)
│       └── ThemeProvider (Chế độ Tối/Sáng)
│           └── ActiveThemeProvider (Tùy chỉnh Giao diện)
│               └── App (Routes & Layout)

4.3. Tích hợp Core Admin

Ứng dụng sử dụng ra-core (React Admin Core) với các provider tùy chỉnh:

Provider	Triển khai	Mục đích
dataProvider	Custom REST Provider	Giao tiếp API
authProvider	Lớp AuthProvider	Luồng Xác thực
i18nProvider	Triển khai tùy chỉnh	Đa ngôn ngữ

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

apps/client/
├── src/
│   ├── application/              # DI Container & Providers
│   │   ├── decorators/           # Decorator tùy chỉnh
│   │   ├── providers/            # Auth & Data Providers
│   │   └── services/             # Dịch vụ API
│   │       ├── apis/             # API Client theo miền (25 files)
│   │       └── networks/         # Cấu hình Mạng
│   ├── components/               # Thành phần UI tái sử dụng
│   │   └── core/                 # Thành phần Cốt lõi
│   │       ├── breadcrumb/       # Breadcrumbs điều hướng
│   │       ├── common/           # Thành phần chung
│   │       ├── input/            # Thành phần nhập liệu Form
│   │       ├── notification/     # Thông báo Toast
│   │       ├── table/            # Thành phần Bảng dữ liệu
│   │       │   ├── base/         # Triển khai Bảng cơ sở
│   │       │   ├── data/         # Biến thể Bảng dữ liệu
│   │       │   └── view/         # Biến thể Bảng xem
│   │       └── title/            # Tiêu đề trang
│   ├── constants/                # Hằng số Ứng dụng
│   │   ├── screens/              # Hằng số cho Màn hình
│   │   └── sub-screens/          # Hằng số cho Màn hình phụ
│   ├── helpers/                  # Các hàm tiện ích
│   ├── hooks/                    # React Hooks tùy chỉnh
│   │   ├── api/                  # API Hooks
│   │   ├── table/                # Table Hooks
│   │   └── view/                 # View Hooks
│   ├── interfaces/               # Giao diện TypeScript (35 files)
│   │   └── product/              # Giao diện liên quan Sản phẩm
│   ├── layout/                   # Thành phần Bố cục
│   │   └── main/                 # Bố cục chính
│   ├── libs/                     # Cấu hình Thư viện ngoài
│   │   └── tanstack/             # Cấu hình TanStack Query
│   ├── redux/                    # Redux Store
│   │   └── slices/               # Redux Slices (5 slices)
│   ├── screens/                  # Thành phần Màn hình (23 modules)
│   └── themes/                   # Cấu hình Giao diện
├── scripts/                      # Script Build
└── public/                       # Tài sản Tĩnh

6. Màn hình & Định tuyến

6.1. Module Màn hình

Ứng dụng chứa 23 module màn hình, mỗi module tuân theo cấu trúc nhất quán:

Module	Đường dẫn	Thao tác	Mô tả
home	/	Dashboard	Bảng điều khiển chính với thống kê
product	/product	List, Create, Edit	Quản lý sản phẩm
category	/category	List, Create, Edit	Quản lý danh mục
category-template	/category-template	List, Create, Edit	Mẫu danh mục
organizer	/organizer	List, Create, Edit	Quản lý tổ chức
merchant	/merchant	List, Create, Edit	Quản lý merchant
user	/user	List, Create, Edit	Quản lý người dùng hệ thống
user-employee	/employee	List, Create, Edit	Quản lý nhân viên
customer	/customer	List, Create, Edit	Quản lý khách hàng
role	/role	List, Create, Edit	Vai trò & quyền hạn
device	/device	List, Create, Edit	Quản lý thiết bị POS
terminal	/terminal	List, Create, Edit	Quản lý terminal thanh toán
sale-channel	/sale-channel	List, Create, Edit	Cấu hình kênh bán hàng
order	/order	List, Show	Xem đơn hàng
transaction	/transaction	List, Show	Lịch sử giao dịch
invoice	/invoice	List	Quản lý hóa đơn điện tử
report	/report/*	Revenue, Order	Báo cáo kinh doanh
settings	/settings/*	Profile, Password	Cài đặt người dùng
sign-in	/login	Login	Xác thực
sign-up	/sign-up	Register	Đăng ký người dùng
errors	/401, /403, /404	Error Pages	Trang lỗi HTTP

6.2. Mẫu Cấu trúc Màn hình

Mỗi module màn hình tuân theo cấu trúc thư mục nhất quán:

screens/{module}/
├── index.ts                    # Module exports
├── list/
│   └── index.tsx               # Thành phần xem danh sách
├── create/
│   └── index.tsx               # Thành phần form tạo mới
├── edit/
│   └── index.tsx               # Thành phần form chỉnh sửa
├── show/
│   └── index.tsx               # Thành phần xem chi tiết (tùy chọn)
├── form/
│   └── index.ts                # Cấu hình form chung
├── common/
│   └── index.ts                # Tiện ích chung
└── actions/
    └── index.ts                # Các hành động riêng của màn hình

7. Dịch vụ API

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

Tất cả các dịch vụ API đều kế thừa BaseApiService cung cấp các thao tác CRUD tiêu chuẩn:

export class BaseApiService extends BaseService {
  protected resource: string;

  constructor(opts: { scope: string; resource: string }) {
    super({ scope: opts.scope });
    this.resource = opts.resource;
  }
}

7.2. Các Dịch vụ API Có sẵn

Dịch vụ	Tài nguyên	Mô tả
AuthApi	/auth	Các thao tác xác thực
OAuth2Api	/oauth2	Tích hợp OAuth2
UserApi	/users	Quản lý người dùng
UserConfigurationApi	/user-configurations	Tùy chọn người dùng
EmployeeApi	/employees	Các thao tác nhân viên
OrganizerApi	/organizers	Quản lý tổ chức
MerchantApi	/merchants	Các thao tác merchant
MerchantTypeApi	/merchant-types	Định nghĩa loại merchant
ProductApi	/products	Danh mục sản phẩm
ProductVariantApi	/product-variants	Biến thể sản phẩm
VariantApi	/variants	Định nghĩa biến thể
CategoryApi	/categories	Quản lý danh mục
SaleChannelApi	/sale-channels	Kênh bán hàng
DeviceApi	/devices	Thiết bị POS
RoleApi	/roles	Quản lý vai trò
OrderApi	/orders	Các thao tác đơn hàng
TransactionApi	/transactions	Lịch sử giao dịch
InvoiceApi	/invoices	Quản lý hóa đơn
CustomerApi	/customers	Dữ liệu khách hàng
ReportApi	/reports	Báo cáo kinh doanh
BucketApi	/buckets	Lưu trữ tệp
MetaLinkApi	/meta-links	Metadata tài sản
StaticAssetsApi	/static-assets	Phục vụ tệp tĩnh

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

8.1. Cấu hình Redux Store

Redux store được cấu hình với nhiều reducer và middleware:

const appReducer = combineReducers({
  route: routeReducer,
  temporary: temporaryReducer,
  common: commonReducer,
  product: productReducer,
  listView: listViewReducer,
});

8.2. Redux Slices

Slice	Mục đích	Trạng thái Chính
route	Trạng thái điều hướng	Route hiện tại, lịch sử
temporary	Dữ liệu tạm thời	Bản nháp form, thay đổi chưa lưu
common	Trạng thái ứng dụng chung	Cờ UI, cài đặt toàn cục
product	Trạng thái chỉnh sửa sản phẩm	Tab hoạt động, ngữ cảnh merchant
listView	Tùy chọn xem bảng	Bộ lọc, sắp xếp, phân trang

8.3. Trạng thái Server với TanStack Query

Trạng thái server (dữ liệu API) được quản lý riêng bằng TanStack Query:

Hook	Mục đích	Sử dụng
useGetData	Lấy một tài nguyên	Trang chi tiết
useInfiniteGetData	Cuộn vô tận	Danh sách dài
useMutationData	Tạo/Cập nhật/Xóa	Gửi form
useRefresh	Vô hiệu hóa cache	Sau khi thay đổi
useVirtualAutocomplete	Tìm kiếm ảo hóa	Trường tự động hoàn thành

9. Giao diện TypeScript

9.1. Giao diện Cốt lõi

Ứng dụng định nghĩa hơn 35 tệp giao diện để đảm bảo an toàn kiểu dữ liệu:

Tệp Giao diện	Mục đích
common.interface.ts	Các loại tiện ích chung
redux.interface.ts	Các loại action/state Redux
result.interface.ts	Các loại phản hồi API
table.interface.ts	Các loại thành phần bảng
sidebar.interface.ts	Các loại điều hướng

9.2. Giao diện Miền

Tệp Giao diện	Miền
product.interface.ts	Quản lý sản phẩm
product/addon.interface.ts	Sản phẩm addon
product/combo.interface.ts	Sản phẩm combo
product/quota.interface.ts	Hạn ngạch sản phẩm
product/product-variant.interface.ts	Biến thể sản phẩm
product/product-feature.interface.ts	Tính năng sản phẩm
category.interface.ts	Quản lý danh mục
category-template.interface.ts	Mẫu danh mục
merchant.interface.ts	Dữ liệu merchant
merchant-type.interface.ts	Loại merchant
organizer.interface.ts	Dữ liệu tổ chức
user.interface.ts	Quản lý người dùng
role.interface.ts	Định nghĩa vai trò
permission.interface.ts	Các loại quyền
order.interface.ts	Dữ liệu đơn hàng
invoice.interface.ts	Dữ liệu hóa đơn
transaction.interface.ts	Bản ghi giao dịch
customer.interface.ts	Dữ liệu khách hàng
device.interface.ts	Thiết bị POS
terminal.interface.ts	Terminal thanh toán
sale-channel.interface.ts	Kênh bán hàng
variant.interface.ts	Biến thể sản phẩm
bucket.interface.ts	Lưu trữ tệp
meta-link.interface.ts	Metadata tài sản

10. Custom Hooks

10.1. API Hooks

Nằm trong src/hooks/api/:

Hook	Mục đích
useGetData	Lấy dữ liệu với caching
useInfiniteGetData	Lấy dữ liệu phân trang
useMutationData	Thay đổi dữ liệu
useRefresh	Làm mới cache truy vấn
useVirtualAutocomplete	Tự động hoàn thành ảo hóa
useVirtualAutocompleteArray	Tự động hoàn thành đa chọn

10.2. Table Hooks

Nằm trong src/hooks/table/:

Hook	Mục đích
useDataTableController	Quản lý instance bảng
useDataTableState	Đồng bộ hóa trạng thái bảng

10.3. View Hooks

Nằm trong src/hooks/view/:

Hook	Mục đích
useViewConfig	Cấu hình view
useViewState	Quản lý trạng thái view

10.4. Utility Hooks

Hook	File	Mục đích
useDataProviderHeaders	useDataProviderHeaders.ts	Tiêm header API
useWarnUnsavedChanges	useWarnUnsavedChanges.ts	Cảnh báo thay đổi chưa lưu
useLogout	useLogout.ts	Xử lý đăng xuất

11. Luồng Xác thực

11.1. Auth Provider

Lớp AuthProvider kế thừa DefaultAuthProvider và triển khai:

Phương thức	Mục đích
login()	Xử lý đăng nhập với thông tin xác thực
logout()	Xóa trạng thái auth và chuyển hướng
checkAuth()	Xác minh tính hợp lệ của token
checkError()	Xử lý lỗi HTTP (401, 403)
getIdentity()	Lấy người dùng hiện tại
getPermissions()	Lấy quyền người dùng
getRoles()	Lấy vai trò người dùng

11.2. Trạng thái Xác thực

1. Người dùng gửi thông tin đăng nhập
2. AuthProvider.login() gọi REST API
3. Thành công: lưu token, userId, username
4. Chuyển hướng đến dashboard
5. checkAuth() xác thực trên mỗi route được bảo vệ
6. Lỗi 401/403 kích hoạt đăng xuất

12. Hệ thống Giao diện (Theme System)

12.1. Theme Provider Stack

ThemeProvider (next-themes)
└── ActiveThemeProvider (Custom)
    └── Tailwind CSS v4 (Chế độ tối qua class)

12.2. Tính năng Giao diện

• Chế độ Tối/Sáng: Chuyển đổi qua next-themes
• Tùy chọn Hệ thống: Tôn trọng cài đặt hệ điều hành
• Lưu trữ: Lưu tùy chọn trong localStorage
• Biến CSS: Thuộc tính tùy chỉnh của Tailwind CSS

13. Build & Triển khai

13.1. Script Build

Script	Lệnh	Mục đích
dev	vite --mode dev	Development server
build	sh ./scripts/build.sh	Build sản xuất
build:develop	sh ./scripts/rebuild.sh development	Build phát triển
build:production	sh ./scripts/rebuild.sh production	Build sản xuất
preview	vite preview --port 4173	Xem trước build sản xuất
lint	sh ./scripts/lint.sh	Chạy ESLint

13.2. Triển khai Docker

# Giai đoạn Build
FROM node:20-alpine AS builder
COPY . .
RUN bun install && bun run build

# Giai đoạn Runtime
FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/nginx.conf

13.3. Cấu hình Môi trường

Biến môi trường được tải qua hệ thống env của Vite:

Biến	Mục đích
VITE_NODE_ENV	Chế độ môi trường
VITE_API_BASE_URL	Điểm cuối Backend API
VITE_AUTH_ENDPOINT	Điểm cuối xác thực

14. Phụ thuộc

14.1. Phụ thuộc Nội bộ

Gói	Mục đích
@nx-app/admin-ui-kit	Thành phần UI dùng chung
@nx-app/core	Tiện ích & locales dùng chung

14.2. Cơ sở hạ tầng Bên ngoài

Gói	Mục đích
@minimaltech/ra-core-infra	Cơ sở hạ tầng React Admin
@venizia/ignis-inversion	IoC Container
@loopback/filter	Xây dựng bộ lọc truy vấn

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

Chỉ số	Số lượng
Tệp Nguồn	~637
Module Màn hình	23
Dịch vụ API	25
Giao diện TypeScript	35+
Redux Slices	5
Custom Hooks	15+
Thành phần React	100+