Kiến Trúc Hệ Thống — Admin Dashboard Traffic Tools V2

1. Tổng quan

Admin Dashboard là SPA thuần túy, render hoàn toàn phía client. Không có SSR, không có middleware nào giữa trình duyệt và Backend API Engine.

Sau khi build, ứng dụng tạo ra tập hợp file tĩnh (HTML, CSS, JS) được phục vụ bởi Nginx. Mọi logic điều hướng, xác thực và hiển thị dữ liệu đều chạy trong trình duyệt.

1.1. Công nghệ sử dụng

Tầng	Công nghệ	Phiên bản	Vai trò
Framework UI	Vue 3	^3.4.31	Core framework, Composition API với `<script setup>`
Bundler	Vite	^5.3.3	Build tool và dev server, dùng ESBuild
Ngôn ngữ	TypeScript	~5.5.2	Kiểu dữ liệu tĩnh toàn bộ mã nguồn
State management	Pinia	^2.1.7	Thay thế Vuex, hỗ trợ Composition API
Persist store	pinia-plugin-persistedstate	^3.2.1	Đồng bộ store với localStorage
UI library	Naive UI	^2.38.2	Bộ component UI cho Vue 3
Biểu đồ chính	Apache ECharts + vue-echarts	^5.5.1 / ^7.0.3	Biểu đồ thống kê và phân tích hiệu suất
Biểu đồ phụ	Chart.js	^4.5.1	Biểu đồ bổ sung cho một số màn hình
Trực quan hóa	D3.js	^7.9.0	Trực quan hóa dữ liệu phức tạp
HTTP client	Axios	^1.7.2	Giao tiếp với Backend API Engine
CSS utilities	Tailwind CSS	^3.4.4	Utility-first CSS
CSS preprocessor	SASS	^1.77.8	SCSS cho các style phức tạp
Xuất Excel	xlsx + xlsx-js-style	^0.18.5 / ^1.2.0	Xuất báo cáo `.xlsx` có định dạng màu sắc
Vue utilities	@vueuse/core	^10.11.0	Composables: clipboard, event bus, URL params
Đa ngôn ngữ	vue-i18n	^9.13.1	Tiếng Việt và Tiếng Anh
Router	vue-router	^4.4.0	Điều hướng SPA với History Mode
Icon	@iconify/vue	^4.1.2	Thư viện icon đa dạng
Validation	zod	^3.23.8	Schema validation cho form data
Utilities	lodash	^4.17.21	Xử lý mảng, object, chuỗi

1.2. Công cụ chất lượng mã

Công cụ	File cấu hình	Chức năng
ESLint	`.eslintrc.cjs`	Phân tích tĩnh, phát hiện lỗi cú pháp và anti-pattern.
Prettier	`.prettierrc.json`	Tự động định dạng code theo chuẩn nhất quán.
Husky	`.husky/`	Git hooks — chặn commit nếu code không qua lint.
lint-staged	`.husky/lintstagedrc.js`	Chỉ lint các file đã thay đổi, tối ưu thời gian commit.
Commitizen + cz-git	`cz.config.js`	Enforce chuẩn Conventional Commits.
commitlint	`commitlint.config.ts`	Kiểm tra format commit message theo Angular convention.
vue-tsc	—	Kiểm tra kiểu TypeScript cho file `.vue` với `<script setup>`.

2. Kiến trúc module

2.1. Sơ đồ phụ thuộc giữa các lớp

src/views/          ← Màn hình nghiệp vụ
      |
      | sử dụng
      v
src/composables/    ← Logic tái sử dụng
      |
      +---------------------------+
      |                           |
      v                           v
src/stores/         ← Pinia state     src/services/api/  ← Axios API calls
      |                           |
      +---------------------------+
                    |
                    v
            src/configs/axios.ts  ← HTTP layer (interceptors, auth headers)
                    |
                    v
            Backend API Engine

2.2. Kiến trúc router

Tầng 1 — Route ngoài layout:
/login, /signup và các trang lỗi (404, 403). Không dùng LayoutDefault, không yêu cầu xác thực. Định nghĩa trong src/router/modules/remaining.ts.

Tầng 2 — Route trong layout (protected):
Tất cả trang nghiệp vụ đều bọc trong LayoutDefault.vue và chịu sự kiểm soát của router.beforeEach. Các route module được tự động nạp:

Tầng 3 — Child routes (nested routing):
Các màn hình phức tạp dùng nested routing để quản lý tab nội bộ:

/auto-search → google-search, coccoc-search, server-performance, location

/system-management → server-management, proxy-management, backup-proxy-management, proxy-package-management, proxy-provider-management

/dashboard1 → click-ads, negative-seo, search-ads, traffic-natural

/user-management → users, activities

2.3. Service layer

Mỗi module có một file service riêng trong src/services/api/, tất cả dùng Axios instance từ src/configs/axios.ts:

File service	API prefix	Các phương thức chính
`auth.ts`	`/user`	`login`, `getMe`, `refreshToken`, `signup`, `generateGoogleAuthenticator`, `verifyGoogleAuthenticator`
`autoSearch.ts`	`/keywords`	`getList`, `getDetail`, `create`, `update`, `updateStatus`, `autoFire`, `reset`, `delete`, `exportExcel`, `historyKeyword`
`servers.ts`	`/server`	`getList`, `getDetail`, `create`, `update`, `changeStatus`, `delete`, `bulkDelete`
`serverPerformance.ts`	`/server/report`	`getList`, `getDetail`
`proxies.ts`	`/proxy`	`getList`, `getDetail`, `create`, `update`, `delete`, `updateActive`, `uploadProxy`, `bulkDelete`
`backup-proxies.ts`	`/backup-proxy`	`getList`, `create`, `update`, `delete`, `testProxy`, `importFromProxifly`, `healthCheck`, `bulkDelete`
`package.ts`	`/proxy-packages`	`getList`, `getDetail`, `create`, `update`, `delete`, `bulkDelete`
`provider.ts`	`/proxy-providers`	`getList`, `getDetail`, `create`, `update`, `delete`, `updateSort`, `getDataUsage`, `bulkDelete`
`campain.ts`	`/campaign`	`getList`, `getDetail`, `create`, `update`, `delete`, `getStatistics`, `exportData`
`users.ts`	`/user`	`getList`, `getDetail`, `create`, `update`, `delete`, `updateActive`, `changePassword`
`activities.ts`	`/activity`	`getList`
`location.ts`	`/location`	`getList`, `getDetail`, `create`, `update`, `delete`
`profiles.ts`	`/profile`	`getList`, `getDetail`, `create`, `update`, `delete`
`task.ts`	`/project`	`getList`, `getDetail`, `create`, `update`, `delete`, `updateStatus`, `updateDomainStatus`
`reports.ts`	Nhiều endpoint	Class `ReportApiService` với các phương thức static

3. Quản lý trạng thái

3.1. Cấu trúc Pinia stores

src/stores/
├── authStore.ts       ← Token, Profile, 2FA logic, logout
├── appStore.ts        ← UI settings (locale, sidebar, breadcrumbs)
└── reportStore.ts     ← Dữ liệu tạm cho màn hình báo cáo
    report/
    └── (các store con cho module báo cáo)

3.2. authStore

State:

Trường	Kiểu	Persist	Mô tả
`authToken`	`Auth.AuthToken \| null`	Có (localStorage)	JWT token, refresh token và device token.
`profile`	`Auth.UserProfile \| null`	Không	Thông tin người dùng đang đăng nhập.
`is_2fa`	`boolean`	Không	Trạng thái 2FA từ server.
`message`	`string`	Không	Thông điệp phản hồi từ API.

Actions:

Action	API endpoint	Mô tả
`login(data)`	`POST /api/user/login`	Đăng nhập, nhận AuthToken, cập nhật `is_2fa`.
`getMe()`	`GET /api/user/profile`	Lấy thông tin profile. Tự kiểm tra localStorage nếu store trống.
`signUp(data)`	`POST /api/user/register`	Đăng ký tài khoản mới (chỉ dùng ở môi trường dev).
`logout()`	—	Xóa token, profile, sessionStorage và redirect về login.
`refreshToken()`	`POST /api/user/refresh`	Làm mới token, cập nhật store và localStorage.

Kiểu dữ liệu AuthToken:

Kiểu dữ liệu UserProfile:

3.3. appStore

State persist vào localStorage:

sideBarCollapsed: boolean — Trạng thái thu gọn sidebar. Mặc định false.

i18nLocale: I18nLocalesKey — Ngôn ngữ hiện tại. Mặc định 'vi-VN'.

State không persist:

isLoadingWebsite: boolean — Cờ loading toàn trang.

breadcrumbs: Breadcrumb[] — Cập nhật sau mỗi lần chuyển route.

Actions:

setLocale(locale) — Cập nhật i18nLocale và đồng bộ i18n.global.locale.value.

3.4. reportStore

Lưu dữ liệu tạm cho module báo cáo: thống kê tổng quan từ API, trạng thái filter và phân trang, cache dữ liệu biểu đồ để tránh gọi API lại khi chuyển tab.

4. Lớp HTTP

4.1. Cấu hình Axios instance

Hàm init() phải được gọi trong src/main.ts sau khi Pinia khởi tạo để interceptor có thể truy cập useAuthStore().

4.2. Timeout đặc biệt

URL chứa /import-all: 300,000ms (5 phút) — import proxy hàng loạt từ Excel.

URL chứa /get-data-report: 60,000ms (1 phút) — tổng hợp báo cáo lớn.

Mọi request khác: 10,000ms.

4.3. Hàng đợi request khi refresh token

Khi token hết hạn và đang refresh, các request mới không bị hủy mà được đưa vào hàng đợi this.requests. Sau khi có token mới, tất cả request trong hàng đợi được thực thi lại. Cờ this.isRefreshing ngăn gọi refresh token nhiều lần đồng thời.

4.4. Phân loại lỗi HTTP

Mã HTTP	Xử lý trong Admin
400	Reject Promise, component gọi `showMessageError()` để hiển thị lỗi validation.
401	Interceptor tự động gọi `authStore.logout()` và redirect về login.
403	Reject Promise, component hiển thị thông báo không có quyền.
404	Reject Promise, component hiển thị thông báo không tìm thấy.
408 / Timeout	Axios tự reject sau khi vượt quá timeout.
500	Reject Promise, component hiển thị lỗi server.
Network Error	Axios reject với `error.message = 'Network Error'`.

5. Component và Composable

5.1. Composables cốt lõi

src/composables/utils.ts:

Hàm	Mô tả
`useHelper()`	Trả về `getCatchMsg()` và `showMessageError()` để xử lý lỗi API.
`useEnv(key)`	Đọc biến môi trường từ `window.configs` trước, fallback về `import.meta.env`.
`useDownload(blob, fileName)`	Tạo link tải file từ Blob response và kích hoạt download.
`useDownloadUrl(url, fileName)`	Tải file từ URL bên ngoài bằng Axios rồi kích hoạt download.
`useCopyToClipboard()`	Copy text vào clipboard với fallback cho trình duyệt cũ.
`useEnsureHttp()`	Đảm bảo URL luôn có tiền tố `http://` hoặc `https://`.

src/composables/useBulkSelection.ts:

Composable generic useBulkSelection<T> quản lý chọn nhiều bản ghi trong bảng:

getRowKey(row) — Bắt buộc. Lấy key định danh duy nhất của mỗi dòng.

onBulkDelete(selectedRows) — Callback xử lý xóa hàng loạt.

onBulkExport(selectedRows) — Callback xử lý xuất dữ liệu hàng loạt.

onBulkUpdate(selectedRows, updates) — Callback xử lý cập nhật hàng loạt.

State: selectedRowKeys, isProcessing, hasSelection, selectionCount.

Các composable khác:

format.ts — Định dạng số, ngày tháng, trạng thái cho bảng và biểu đồ.

render.ts — Tạo cột bảng Naive UI Data Table dạng động (button, tag màu, tooltip).

toggle.ts — Quản lý isOpen, isLoading, isEditing trong modal và form.

router.ts — replaceParamsInPath() để thay thế tham số động trong đường dẫn route.

5.2. Components dùng chung

BulkActions.vue — Thanh công cụ hiển thị khi có bản ghi được chọn (xóa, xuất, cập nhật hàng loạt).

pagination/ — Component phân trang tùy chỉnh tích hợp với Naive UI Pagination.

common/ — DateRangePicker, SearchInput, StatusTag dùng trên nhiều màn hình.

6. Build và phân phối

6.1. Các lệnh build

Lệnh	Môi trường	Mô tả
`npm run dev`	Development	Khởi động Vite Dev Server với HMR.
`npm run build:dev`	Development	Build tĩnh cho môi trường Development.
`npm run build:stg`	Staging	Build tĩnh cho môi trường Staging.
`npm run build:release`	Release	Build tĩnh cho môi trường Release.
`npm run build:prod`	Production	Build tĩnh cho Production, chạy typecheck sau khi build.
`npm run build:prod:docker`	Production	Build cho Production trong Docker, không chạy typecheck riêng.
`npm run typecheck`	—	Chạy `vue-tsc --build --force` kiểm tra kiểu dữ liệu.
`npm run lint`	—	Chạy ESLint và tự sửa lỗi trên toàn bộ file `.vue`, `.ts`.

6.2. Output build

Vite tạo ra thư mục dist/ với:

index.html — Entry point HTML.

assets/ — Các file .js, .css, hình ảnh đã được hash tên file để cache-busting tự động.

Tên file theo pattern: assets/[name].[hash].js. Hash thay đổi mỗi khi nội dung thay đổi.

6.3. Phân tách bundle

Vite tách bundle thành các chunk riêng để tối ưu cache:

naiveUI — Toàn bộ Naive UI (~1MB, ít thay đổi).

lodash — Lodash và lodash-es.

vue — Vue core (ổn định nhất).

Ba thư viện này chiếm phần lớn kích thước bundle nhưng hiếm khi thay đổi. Tách riêng giúp browser cache lại và không cần tải lại khi code nghiệp vụ thay đổi.

6.4. Yêu cầu môi trường phát triển

Node.js >= 18.3.0.

Backend API Engine phải đang chạy và cho phép CORS từ http://localhost:5173.

7. Module báo cáo

7.1. Cấu trúc service

Module báo cáo có kiến trúc service phức tạp nhất, tách thành nhiều file trong src/services/api/reports/:

src/services/api/reports/
├── useReportRequest.ts      ← Hàm request() wrapper với base URL riêng
├── useReportEndpoints.ts    ← Các endpoint đặc thù của module báo cáo
├── useReportCrud.ts         ← CRUD cơ bản: getReports, createReport, deleteReport
└── useReportStats.ts        ← Thống kê: getDashboardStats, getPlatformPerformance

ReportApiService trong reports.ts là class static tổng hợp tất cả phương thức, cung cấp interface thống nhất cho các component.

7.2. Kiểu dữ liệu báo cáo

PCReportData — Dữ liệu báo cáo tổng hợp:

ReportDomainItem — Một domain đang được theo dõi:

8. Đa ngôn ngữ

locales/
├── vi-VN.json    ← Chuỗi Tiếng Việt (mặc định)
├── en-US.json    ← Chuỗi Tiếng Anh
└── _schema.json  ← Schema kiểm tra cấu trúc file ngôn ngữ

Cấu hình plugin:

9. Webhook

File src/configs/webhook-axios.ts cung cấp một Axios instance riêng cho các request đến webhook endpoint, tách biệt với instance chính để tránh ảnh hưởng về cấu hình timeout và header. Dùng để gửi thông báo đến các hệ thống bên ngoài (Slack, Telegram) khi có sự kiện quan trọng.

10. Tổng kết kiến trúc

Điểm mạnh:

Tách biệt rõ ràng giữa các lớp: View, Composable, Store, Service, Config.

Auto-import giảm boilerplate và đảm bảo nhất quán.

TypeScript namespace tổ chức theo module nghiệp vụ, dễ tìm kiếm và bảo trì.

Axios interceptor tập trung xử lý xác thực và lỗi.

Pinia store tối giản, chỉ lưu dữ liệu thực sự cần chia sẻ toàn cục.

Các quyết định kỹ thuật quan trọng:

Dùng <script setup lang="ts"> thay vì Options API để có type inference tốt hơn.

Dùng import.meta.glob để tự động nạp route modules.

Dùng window.configs injection để override biến môi trường mà không cần build lại.

Dùng multi-stage Docker build để giảm kích thước image production.

Dùng pinia-plugin-persistedstate để đồng bộ store với localStorage theo cách khai báo.

System Architecture

Kiến Trúc Hệ Thống — Admin Dashboard Traffic Tools V2#

1. Tổng quan#

1.1. Công nghệ sử dụng#

1.2. Công cụ chất lượng mã#

2. Kiến trúc module#

2.1. Sơ đồ phụ thuộc giữa các lớp#

2.2. Kiến trúc router#

2.3. Service layer#

3. Quản lý trạng thái#

3.1. Cấu trúc Pinia stores#

3.2. authStore#

3.3. appStore#

3.4. reportStore#

4. Lớp HTTP#

4.1. Cấu hình Axios instance#

4.2. Timeout đặc biệt#

4.3. Hàng đợi request khi refresh token#

4.4. Phân loại lỗi HTTP#

5. Component và Composable#

5.1. Composables cốt lõi#

5.2. Components dùng chung#

6. Build và phân phối#

6.1. Các lệnh build#

6.2. Output build#

6.3. Phân tách bundle#

6.4. Yêu cầu môi trường phát triển#

7. Module báo cáo#

7.1. Cấu trúc service#

7.2. Kiểu dữ liệu báo cáo#

8. Đa ngôn ngữ#

9. Webhook#

10. Tổng kết kiến trúc#