Tài Liệu Triển Khai Môi Trường Cục Bộ — Admin Dashboard Traffic Tools V2

1. Yêu Cầu Hệ Thống

1.1. Yêu Cầu Bắt Buộc

Node.js phiên bản >= 18.3.0 theo engines trong package.json. Khuyến nghị sử dụng NVM để quản lý phiên bản Node.js giữa các dự án.

npm phiên bản >= 9.x đi kèm Node.js 18, hoặc yarn 1.22.x. Không khuyến nghị pnpm do có thể phát sinh lỗi không tương thích với Naive UI.

Git phiên bản >= 2.30.0.

Hệ điều hành: Windows 10/11, macOS Sonoma, hoặc Ubuntu 22.04 LTS. Người dùng Windows nên cài WSL2 với Ubuntu để có môi trường bash tương thích.

1.2. Công Cụ Khuyến Nghị

Visual Studio Code với các extension: Vue - Official (Volar), ESLint, Prettier, Tailwind CSS IntelliSense, EditorConfig for VS Code.

Chrome hoặc Edge với extension Vue.js devtools để debug component và Pinia store.

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

2. Thiết Lập Lần Đầu

2.1. Thiết Lập SSH Key

Dự án sử dụng SSH để kết nối GitLab. Không sử dụng HTTPS Username/Password vì lý do bảo mật:

Sao chép nội dung public key và thêm vào GitLab tại Settings → SSH Keys.

2.2. Clone Repository

2.3. Cài Đặt Dependencies

Nếu gặp lỗi peer dependencies do xung đột phiên bản:

2.4. Cấu Hình Biến Môi Trường

File .env.development đã có sẵn trong repository:

NODE_MODE=development
VITE_API_SERVER=http://localhost:33001

Nếu Backend API Engine chạy ở port khác, tạo file .env.development.local (không commit vào Git) để override:

VITE_API_SERVER=http://localhost:PORT_KHAC

Hoặc chỉnh sửa public/runtime.config.js để override qua window.configs mà không cần restart dev server:

3. Khởi Chạy Môi Trường Phát Triển

3.1. Khởi Động Dev Server

Vite khởi động dev server với Hot Module Replacement (HMR). Lần đầu chạy mất khoảng 2-3 giây để pre-bundle dependencies bằng ESBuild. Các lần sau chỉ mất vài mili-giây nhờ cache.

Output mong đợi:

  VITE v5.x.x  ready in 1200 ms

  Local:   http://localhost:5173/
  Network: use --host to expose

Mở trình duyệt tại http://localhost:5173 để truy cập ứng dụng.

3.2. Xóa Cache Vite Khi Gặp Lỗi

Khi thay đổi dependencies hoặc gặp lỗi module không tìm thấy:

3.3. Chạy Với Expose Network

Để truy cập từ thiết bị khác trong cùng mạng LAN (ví dụ test trên điện thoại):

4. Các Lệnh Phát Triển Thường Dùng

4.1. Kiểm Tra Kiểu TypeScript

Chạy vue-tsc --build --force để kiểm tra toàn bộ kiểu TypeScript trong dự án, bao gồm cả file .vue với <script setup>. Nên chạy trước khi tạo Merge Request để phát hiện lỗi type sớm.

4.2. Kiểm Tra Và Sửa Lỗi Lint

Chạy ESLint trên toàn bộ file .vue, .ts, .tsx và tự động sửa các lỗi có thể sửa được. Husky sẽ tự động chạy lệnh này trên các file đã thay đổi khi commit thông qua lint-staged.

4.3. Định Dạng Code

Chạy Prettier trên toàn bộ thư mục src/ để đảm bảo định dạng code nhất quán giữa các thành viên trong team.

4.4. Build Cho Môi Trường Development

Tạo bản build tĩnh cho môi trường Development, chạy typecheck song song. Output trong thư mục dist/.

4.5. Xem Trước Bản Build

Khởi động server tĩnh phục vụ thư mục dist/. Dùng để kiểm tra bản build trước khi deploy, đặc biệt để phát hiện các vấn đề chỉ xuất hiện trong bản build production (tree-shaking, code splitting).

5. Cấu Trúc Commit

Dự án sử dụng Conventional Commits. Husky sẽ chặn commit không đúng format thông qua commitlint.

5.1. Format Commit Message

<type>(<scope>): <subject>

[optional body]

[optional footer]

Các type hợp lệ:

feat — Tính năng mới.

fix — Sửa lỗi.

docs — Thay đổi tài liệu.

style — Thay đổi định dạng code, không ảnh hưởng logic.

refactor — Tái cấu trúc code, không thêm tính năng hay sửa lỗi.

perf — Cải thiện hiệu suất.

test — Thêm hoặc sửa test.

chore — Thay đổi build process hoặc công cụ phụ trợ.

Ví dụ commit hợp lệ:

feat(proxy): add bulk delete functionality
fix(auth): handle token expiry during session restore
docs(readme): update local setup instructions
refactor(auto-search): extract keyword table logic to composable

5.2. Sử Dụng Commitizen

Thay vì viết commit message thủ công, sử dụng Commitizen để được hướng dẫn từng bước:

6. Cấu Hình VSCode

6.1. File .vscode/settings.json Khuyến Nghị

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "typescript.tsdk": "node_modules/typescript/lib",
  "vue.server.hybridMode": true
}

6.2. Extensions Bắt Buộc

Vue.volar — Vue Language Features (Volar): Hỗ trợ <script setup>, TypeScript trong template, type checking cho props và emits.

dbaeumer.vscode-eslint — ESLint: Hiển thị lỗi lint real-time trong editor.

esbenp.prettier-vscode — Prettier: Tự động format khi lưu file.

bradlc.vscode-tailwindcss — Tailwind CSS IntelliSense: Gợi ý class Tailwind và hiển thị CSS tương ứng.

EditorConfig.EditorConfig — EditorConfig: Chuẩn hóa tab/space và line endings giữa các thành viên.

7. Xử Lý Sự Cố Thường Gặp

7.1. Lỗi "Cannot find module" Sau Khi Pull Code

Nguyên nhân: Dependencies mới được thêm vào package.json nhưng chưa được cài đặt.

Giải pháp:

7.2. Lỗi TypeScript "Property does not exist"

Nguyên nhân: File types/auto-imports.d.ts hoặc types/components.d.ts chưa được tạo. Các file này được Vite tạo tự động khi chạy dev server lần đầu.

Giải pháp: Chạy npm run dev một lần để Vite tạo lại các file khai báo type tự động.

7.3. Lỗi "Module not found: @/..."

Nguyên nhân: Alias @/ chưa được cấu hình đúng trong tsconfig.json.

Kiểm tra tsconfig.json có chứa:

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"],
      "@api/*": ["./src/services/api/*"]
    }
  }
}

7.4. Trang Trắng Sau Khi Đăng Nhập

Nguyên nhân: sessionStorage.move_to_dashboard không được đặt thành 'true'.

Kiểm tra:

DevTools → Application → Session Storage → move_to_dashboard phải là 'true'.

Console → Tìm lỗi trong quá trình đăng nhập.

Network → Kiểm tra /api/user/login và /api/user/profile có trả về 200 không.

7.5. Hot Reload Không Hoạt Động

Nguyên nhân: Cache Vite bị hỏng hoặc file system watcher không hoạt động.

Giải pháp:

Trên Windows, nếu vẫn không hoạt động, thử thêm thư mục dự án vào whitelist của antivirus.

7.6. Lỗi CORS Khi Gọi API

Nguyên nhân: Backend API Engine chưa cấu hình CORS cho origin http://localhost:5173.

Giải pháp tạm thời: Sử dụng Vite proxy trong vite.config.ts:

Giải pháp lâu dài: Yêu cầu backend developer thêm http://localhost:5173 vào danh sách CORS allowed origins.

7.7. Lỗi Husky Khi Commit

Nguyên nhân: Husky hooks chưa được cài đặt sau khi clone repository.

Giải pháp:

Lệnh này chạy husky để cài đặt Git hooks vào thư mục .git/hooks/.

8. Quy Trình Làm Việc Hàng Ngày

8.1. Bắt Đầu Ngày Làm Việc

8.2. Trước Khi Tạo Merge Request

8.3. Quy Trình Tạo Tính Năng Mới

Tạo branch mới từ develop: git checkout -b feature/ten-tinh-nang.

Phát triển tính năng với npm run dev.

Commit theo Conventional Commits format.

Chạy npm run typecheck và npm run lint trước khi push.

Tạo Merge Request vào nhánh develop trên GitLab.

Sau khi được review và approve, merge vào develop.

Pipeline GitLab CI sẽ tự động deploy lên môi trường Develop.

8.4. Quy Trình Sửa Lỗi Khẩn Cấp

Tạo branch từ master: git checkout -b hotfix/mo-ta-loi.

Sửa lỗi và test kỹ.

Tạo Merge Request vào cả master và develop.

Sau khi merge vào master, pipeline sẽ tự động build và deploy lên Production.

Local

Tài Liệu Triển Khai Môi Trường Cục Bộ — Admin Dashboard Traffic Tools V2#

1. Yêu Cầu Hệ Thống#

1.1. Yêu Cầu Bắt Buộc#

1.2. Công Cụ Khuyến Nghị#

2. Thiết Lập Lần Đầu#

2.1. Thiết Lập SSH Key#

2.2. Clone Repository#

2.3. Cài Đặt Dependencies#

2.4. Cấu Hình Biến Môi Trường#

3. Khởi Chạy Môi Trường Phát Triển#

3.1. Khởi Động Dev Server#

3.2. Xóa Cache Vite Khi Gặp Lỗi#

3.3. Chạy Với Expose Network#

4. Các Lệnh Phát Triển Thường Dùng#

4.1. Kiểm Tra Kiểu TypeScript#

4.2. Kiểm Tra Và Sửa Lỗi Lint#

4.3. Định Dạng Code#

4.4. Build Cho Môi Trường Development#

4.5. Xem Trước Bản Build#

5. Cấu Trúc Commit#

5.1. Format Commit Message#

5.2. Sử Dụng Commitizen#

6. Cấu Hình VSCode#

6.1. File .vscode/settings.json Khuyến Nghị#

6.2. Extensions Bắt Buộc#

7. Xử Lý Sự Cố Thường Gặp#

7.1. Lỗi "Cannot find module" Sau Khi Pull Code#

7.2. Lỗi TypeScript "Property does not exist"#

7.3. Lỗi "Module not found: @/..."#

7.4. Trang Trắng Sau Khi Đăng Nhập#

7.5. Hot Reload Không Hoạt Động#

7.6. Lỗi CORS Khi Gọi API#

7.7. Lỗi Husky Khi Commit#

8. Quy Trình Làm Việc Hàng Ngày#

8.1. Bắt Đầu Ngày Làm Việc#

8.2. Trước Khi Tạo Merge Request#

8.3. Quy Trình Tạo Tính Năng Mới#

8.4. Quy Trình Sửa Lỗi Khẩn Cấp#

Tài Liệu Triển Khai Môi Trường Cục Bộ — Admin Dashboard Traffic Tools V2

1. Yêu Cầu Hệ Thống

1.1. Yêu Cầu Bắt Buộc

1.2. Công Cụ Khuyến Nghị

2. Thiết Lập Lần Đầu

2.1. Thiết Lập SSH Key

2.2. Clone Repository

2.3. Cài Đặt Dependencies

2.4. Cấu Hình Biến Môi Trường

3. Khởi Chạy Môi Trường Phát Triển

3.1. Khởi Động Dev Server

3.2. Xóa Cache Vite Khi Gặp Lỗi

3.3. Chạy Với Expose Network

4. Các Lệnh Phát Triển Thường Dùng

4.1. Kiểm Tra Kiểu TypeScript

4.2. Kiểm Tra Và Sửa Lỗi Lint

4.3. Định Dạng Code

4.4. Build Cho Môi Trường Development

4.5. Xem Trước Bản Build

5. Cấu Trúc Commit

5.1. Format Commit Message

5.2. Sử Dụng Commitizen

6. Cấu Hình VSCode

6.1. File .vscode/settings.json Khuyến Nghị

6.2. Extensions Bắt Buộc

7. Xử Lý Sự Cố Thường Gặp

7.1. Lỗi "Cannot find module" Sau Khi Pull Code

7.2. Lỗi TypeScript "Property does not exist"

7.3. Lỗi "Module not found: @/..."

7.4. Trang Trắng Sau Khi Đăng Nhập

7.5. Hot Reload Không Hoạt Động

7.6. Lỗi CORS Khi Gọi API

7.7. Lỗi Husky Khi Commit

8. Quy Trình Làm Việc Hàng Ngày

8.1. Bắt Đầu Ngày Làm Việc

8.2. Trước Khi Tạo Merge Request

8.3. Quy Trình Tạo Tính Năng Mới

8.4. Quy Trình Sửa Lỗi Khẩn Cấp