@cyberskill/cyber-editor 3.7.1 → 3.8.0

package/README.md

@@ -1,189 +1,233 @@
-# Hướng dẫn
+# Hướng Dẫn Sử Dụng Dự Án
 
-## Yêu cầu
+<!-- Mục lục -->
 
-- nvm (node version manager):
-    - MacOS: <https://github.com/nvm-sh/nvm>
-    - Windows: <https://github.com/coreybutler/nvm-windows>
-- Node: 20.15.0 (nvm sẽ tự động cài đặt phiên bản này nếu chưa có)
-    - MacOS: <https://nodejs.org/dist/v20.15.0/node-v20.15.0.pkg>
-    - Windows: <https://nodejs.org/dist/v20.15.0/node-v20.15.0-x64.msi>
-- Docker: <https://www.docker.com/products/docker-desktop>
-- Dùng npm, không dùng các công cụ khác để tránh xung đột
+- [Yêu Cầu](#yêu-cầu)
+- [Cài Đặt](#cài-đặt)
+- [Chạy Dự Án](#chạy-dự-án)
+    - [Chạy ở môi trường development với Docker](#chạy-ở-môi-trường-development-với-docker)
+    - [Chạy ở môi trường development (Local)](#chạy-ở-môi-trường-development-local)
+- [Các Script & Ý Nghĩa](#các-script--ý-nghĩa)
+- [Quy Ước Viết Code & Đặt Tên](#quy-ước-viết-code--đặt-tên)
+    - [Quy Ước Đặt Tên](#quy-ước-đặt-tên)
+    - [Quy Ước Đặt Tên Chung](#quy-ước-đặt-tên-chung)
+    - [Quy Ước Tiền Tố Trong TypeScript](#quy-ước-tiền-tố-trong-typescript)
+    - [Quy Ước Đặt Tên Type Trong GraphQL](#quy-ước-đặt-tên-type-trong-graphql)
+    - [Quy Ước Đặt Tên Biến Môi Trường](#quy-ước-đặt-tên-biến-môi-trường)
+    - [Quy Ước Khi Import](#quy-ước-khi-import)
+    - [Quy Ước Viết Code](#quy-ước-viết-code)
+    - [Quy Ước Đặt Commit Message](#quy-ước-đặt-commit-message)
+- [Cấu Trúc Thư Mục Và Ý Nghĩa](#cấu-trúc-thư-mục-và-ý-nghĩa)
+- [Quy Trình Làm Việc Với Git](#quy-trình-làm-việc-với-git)
 
-## Cài đặt
+---
 
-Sao chép file `.env.example` ra một file tương tự, đổi tên file thành `.env`
+## Yêu Cầu
 
-Chỉnh sửa một số trường `.env` cho phù hợp với môi trường máy cá nhân, có thể để như mặc định ở môi trường localhost
+- **nvm (Node Version Manager):**
+    - MacOS: [nvm-sh/nvm](https://github.com/nvm-sh/nvm)
+    - Windows: [coreybutler/nvm-windows](https://github.com/coreybutler/nvm-windows)
+- **Node.js:** 22.14.0
+  _(nvm sẽ tự động cài đặt phiên bản này nếu chưa có)_
+    - MacOS: [node-v22.14.0.pkg](https://nodejs.org/dist/v22.14.0/node-v22.14.0.pkg)
+    - Windows: [node-v22.14.0-x64.msi](https://nodejs.org/dist/v22.14.0/node-v22.14.0-x64.msi)
+- **Docker:** [Docker Desktop](https://www.docker.com/products/docker-desktop)
+- **Ghi chú:** Dùng **pnpm** để tránh xung đột với các công cụ khác.
 
-## Chạy ở môi trường development - Docker (cần bật Docker trước)
+---
+
+## Cài Đặt
+
+1. **Tạo file cấu hình môi trường:**
+   Sao chép file `.env.example` thành `.env`.
+2. **Chỉnh sửa file `.env`:**
+   Cập nhật các trường cần thiết phù hợp với môi trường máy.
+
+---
+
+## Chạy Dự Án
+
+### Chạy ở môi trường development với Docker
+
+_(Lưu ý: Hãy bật Docker trước khi chạy)_
 
 ```bash
 make build-development
 make start-development
 ```
 
-## Chạy ở môi trường development (cần bật mongodb trước)
+### Chạy ở môi trường development (Local)
 
 ```bash
-npm i -f
-npm run dev
+pnpm i -f
+pnpm run dev
 ```
 
-Khi thành công sẽ thấy terminal/console hiển thị thông báo:
+---
 
-```bash
-  VITE v5.4.10  ready in 223 ms
+## Các Script & Ý Nghĩa
 
-  ➜  Local:   http://localhost:8001/
-  ➜  Network: http://192.168.2.6:8001/
-  ➜  press h + enter to show help
-```
+Kiểm tra lỗi lint:
 
-## Kiểm tra lỗi (chạy thủ công)
+| Script           | Ý nghĩa                                 |
+| ---------------- | --------------------------------------- |
+| **lint**         | kiểm tra lỗi lint và typescript         |
+| **lint:fix**     | tự động sửa các lỗi có thể sửa          |
+| **lint:inspect** | xem chi tiết các lint rule đang dùng    |
+| **reset**        | cài đặt lại dependencies                |
+| **setup**        | nâng cấp dependencies                   |
+| **inspect**      | xem chi tiết các dependencies đang dùng |
 
-```bash
-npm run lint:check
-```
+---
 
-## Sửa lỗi (chạy thủ công)
+## Quy Ước Viết Code & Đặt Tên
 
-```bash
-npm run lint:fix
-```
+### Quy Ước Đặt Tên
 
-## Một số quy ước
+| Loại                   | Quy Ước      | Ví Dụ               |
+| ---------------------- | ------------ | ------------------- |
+| **Tên biến**           | `camelCase`  | `userName`          |
+| **Tên hàm**            | `camelCase`  | `getUserInfo()`     |
+| **Tên biến parameter** | `camelCase`  | `id, userData`      |
+| **Tên biến argument**  | `camelCase`  | `fetchData(userId)` |
+| **Tên biến private**   | `_camelCase` | `_isHidden`         |
+| **Tên class**          | `PascalCase` | `UserProfile`       |
+| **Tên hằng số**        | `UPPER_CASE` | `MAX_RETRY_COUNT`   |
+| **Tên file**           | `kebab-case` | `user-service.ts`   |
+| **Tên thư mục**        | `kebab-case` | `services/`         |
 
-### Quy ước đặt tên
+### Quy Ước Đặt Tên Chung
 
-- Tên biến: `camelCase`
-- Tên hàm: `camelCase`
-- Tên biến parameter: `camelCase`
-- Tên biến argument: `camelCase`
-- Tên biến private: `_camelCase`
-- Tên class: `PascalCase`
-- Tên hằng số: `UPPER_CASE`
-- Tên file: `kebab-case`
-- Tên thư mục: `kebab-case`
+| Loại                     | Tiền Tố       | Quy Tắc                       | Ví Dụ                       |
+| ------------------------ | ------------- | ----------------------------- | --------------------------- |
+| **Biến đại diện input**  | `I_Input_`    | Tiền tố + loại + kiểu dữ liệu | `interface I_Input_User`    |
+| **Biến đại diện output** | `I_Response_` | Tiền tố + loại + kiểu dữ liệu | `interface I_Response_User` |
 
-### Quy ước đặt tên chung
+### Quy Ước Tiền Tố Trong TypeScript
 
-- Tiền tố tuỳ thuộc vào từ khoá của typescript hoặc graphql
-- Quy tắc: Tiền tố + tên kiểu dữ liệu (ví dụ: `interface I_User`, `interface I_Role`)
-- Trường hợp biến đại diện cho input (kiểu dữ liệu đầu vào): Tiền tố + loại + tên kiểu dữ liệu (ví dụ: `interface T_Input_User` cho typescript, `input T_Input_CreateUser` cho graphql)
-- Trường hợp biến đại diện cho output (kiểu dữ liệu đầu ra): Tiền tố + loại + tên kiểu dữ liệu (ví dụ: `interface I_Response_User` cho typescript, `type T_Response_User` cho graphql)
+| Loại          | Tiền Tố | Ví Dụ              |
+| ------------- | ------- | ------------------ |
+| **Interface** | `I_`    | `interface I_User` |
+| **Type**      | `T_`    | `type T_User`      |
+| **Enum**      | `E_`    | `enum E_User`      |
 
-### Quy ước tiền tố typescript
+### Quy Ước Đặt Tên Type Trong GraphQL
 
-- Dùng tiền tố `I_` cho interface (ví dụ: `interface I_User`)
-- Dùng tiền tố `T_` cho type (ví dụ: `type T_User`)
-- Dùng tiền tố `E_` cho enum (ví dụ: `enum E_User`)
+| Loại      | Tiền Tố | Ví Dụ                |
+| --------- | ------- | -------------------- |
+| **Type**  | `T_`    | `type T_User`        |
+| **Input** | `I_`    | `input I_CreateUser` |
 
-### Quy ước đặt tên type graphql
+### Quy Ước Đặt Tên Biến Môi Trường
 
-- Dùng tiền tố `T_` cho type (ví dụ: `type T_User`)
-- Dùng tiền tố `I_` cho input (ví dụ: `input I_InputCreateUser`)
+| Loại        | Tiền Tố        | Ví Dụ                 |
+| ----------- | -------------- | --------------------- |
+| **React**   | `REACT_APP_`   | `REACT_APP_API_URL`   |
+| **Next.js** | `NEXT_PUBLIC_` | `NEXT_PUBLIC_API_KEY` |
+| **Vite**    | `VITE_`        | `VITE_API_SECRET`     |
+| **Node.js** | `NODE_`        | `NODE_ENV`            |
 
-### Quy ước đặt tên biến môi trường
+### Quy Ước Khi Import
 
-- Dùng tiền tố `REACT_APP_` cho biến môi trường của react
-- Dùng tiền tố `NEXT_PUBLIC_` cho biến môi trường của nextjs
-- Dùng tiền tố `VITE_` cho biến môi trường của vite
-- Dùng tiền tố `NODE_` cho biến môi trường của node
+1. Các thư viện bên ngoài **ở trên cùng**.
+2. Các module/hàm tiện ích **ở dưới**, cách một dòng trắng với phần trên.
+3. Định cấu hình đường dẫn để **import nhanh** trong `tsconfig.json`.
 
-### Quy ước khi import: Xem các file có sẵn
+```ts
+import React from 'react'; // Thư viện bên ngoài
 
-- Các thư viện cài đặt bên ngoài trên cùng
-- Các hàm tiện ích/module trong hệ thống ở dưới, cách một dòng trắng với các thư viện bên ngoài, cấu hình dường dẫn để import nhanh nằm ở file `tsconfig.json`
+import { formatDate } from '#shared/utils'; // Module nội bộ
+```
 
-### Quy ước viết code
+### Quy Ước Viết Code
 
-- Không dùng `var`
-- Không dùng `==`
-- Xóa `console.log` trước khi commit
-- Xóa `debugger` trước khi commit
-- Không dùng `any`, `unknown`, `never`
-- Không dùng `@ts-ignore`
-- Không dùng `@ts-nocheck`
+✅ **Làm**
 
-### Quy ước đặt commit message
+- Dùng `let` và `const` thay vì `var`.
+- Dùng `===` thay vì `==`.
+- Xóa `console.log`, `alert` và `debugger` trước khi commit.
 
-- Commit message có dạng: `type(module/entity): message` (ví dụ: `feat(user): add user feature`, `fix(user): cannot create user`)
+❌ **Không làm**
 
-## Cấu trúc thư mục và ý nghĩa
+- Không dùng `any`, `unknown`, `never`.
+- Không dùng `@ts-ignore`, `@ts-nocheck`.
 
-```text
-.
-├── .github => cấu hình workflow để chạy CI/CD cho github
-├── docker => cấu hình triển khai docker
-├── node_modules => thư mục chứa các thư viện ngoài
-├── public
-│   ├── assets => Chứa các asset như fonts, images, icons
-├── shared => Các file dùng chung
-│   └── components => Các component dùng chung
-│       ├── index.ts => import tất cả các component con vào index
-│   └── contexts => Các context dùng chung
-│       ├── index.ts => import tất cả các context con vào index
-│   └── hocs => Các hoc dùng chung
-│       ├── index.ts => import tất cả các hoc con vào index
-│   └── hooks => Các hook dùng chung
-│       ├── index.ts => import tất cả các hook con vào index
-│   └── i18n => Dịch thuật của hệ thống
-│   └── layouts => Các layout trong hệ thống
-│       ├── index.ts => import tất cả các layout con vào index
-│   └── typescript => Các typescript dùng chung
-│       ├── index.ts => import tất cả các typescript con vào index
-│   └── utils => Các hàm tiện ích dùng chung
-│       ├── index.ts => import tất cả các util con vào index
-├── .env => biến môi trường (copy từ .env.example)
-├── .env.example => mẫu biến môi trường
-├── .gitignore => cấu hình git
-├── .ncurc.cjs => cấu hình bỏ qua thư viện khi kiểm tra phiên bản mới
-├── .npmrc => cấu hình npm
-├── .nvmrc => phiên bản node
-├── .eslint.config.js => cấu hình kiểm tra cú pháp code
-├── index.html => file đầu vào
-├── Makefile => lệnh make dùng để chạy docker
-├── package-lock.json => cấu hình npm
-├── package.json => cấu hình npm
-├── README.md => hướng dẫn
-└── tsconfig.app.json => cấu hình typescript cho app
-└── tsconfig.json => cấu hình typescript
-└── tsconfig.node.json => cấu hình typescript cho server
-└── vite.config.ts => cấu hình vite
-```
+### Quy Ước Đặt Commit Message
 
-## Quy trình làm việc
+| Loại Commit       | Cú Pháp                 | Ví Dụ                                      |
+| ----------------- | ----------------------- | ------------------------------------------ |
+| **Tính năng mới** | `feat(module): message` | `feat(user): add user login`               |
+| **Sửa lỗi**       | `fix(module): message`  | `fix(auth): incorrect password validation` |
 
-### 1. Tách nhánh từ `develop`
+## Cấu trúc thư mục và ý nghĩa
 
-```bash
-git checkout -b branchName
+```text
+│── .github/                          # Cấu hình GitHub Actions hoặc tài liệu liên quan đến GitHub
+│── dist/                             # Thư mục build sau khi chạy `vite build`
+│── node_modules/                     # Thư viện và dependency của Node.js
+│── src/                              # Thư mục chứa mã nguồn chính
+│   ├── modules/                      # Các module chính trong ứng dụng
+│   │   ├── [module-name]/            # Tên module
+│   │   │   ├── module.scss           # Styles cho module
+│   │   │   ├── module.component.tsx  # Component của module
+│   │   │   ├── module.type.tsx       # Typescript của module
+│   │   │   ├── index.tsx             # Export các file ngang cấp
+│   ├── shared/                       # Các tài nguyên dùng chung
+│   │   ├── assets/
+│   │   │   ├── styles/               # CSS dùng trong dự án
+│   │   ├── components/               # Các component dùng chung giữa nhiều trang
+│   │   ├── configs/                  # Các file cấu hình
+│   │   │   ├── env.ts                # Cấu hình biến môi trường
+│   │   ├── constants/                # Các hằng số dùng trong dự án
+│   │   ├── providers/                # Providers chung của ứng dụng
+│   │   ├── typescript/               # Kiểu dữ liệu TypeScript dùng trong dự án
+│   ├── index.tsx              # File đầu vào của dự án
+│   ├── root.tsx                      # File khởi tạo React App
+│   ├── vite-env.d.ts                 # Cấu hình typescript cho Vite
+│── .env                              # File environment variables (bí mật, không commit lên Git)
+│── .env.example                      # Mẫu `.env` để tham khảo
+│── .gitignore                        # Danh sách các file cần bỏ qua khi commit
+│── .ncurc.cjs                        # Cấu hình kiểm tra cập nhật package
+│── .nvmrc                            # Cấu hình Node.js version manager
+│── .simple-git-hooks.json            # Cấu hình simple git hooks
+│── eslint.config.js                  # Cấu hình ESLint
+│── index.html                        # file html chính của dự án
+│── package.json                      # Danh sách dependencies và scripts của dự án
+│── pnpm-lock.yaml                    # File lock dependencies của pnpm
+│── README.md                         # Tài liệu mô tả dự án
+│── tsconfig.app.json                 # Cấu hình TypeScript cho ứng dụng
+│── tsconfig.json                     # Cấu hình TypeScript chung
+│── tsconfig.node.json                # Cấu hình TypeScript cho Node.js
+│── vite.config.ts                    # Cấu hình Vite
 ```
 
-### 2. Sau khi code, thêm file muốn đẩy lên git vào staged
+## Quy Trình Làm Việc Với Git
+
+1. **Tạo nhánh mới từ `develop`**:
 
 ```bash
-git add fileName
+git checkout develop
+git pull origin develop
+git checkout -b feature/new-feature
 ```
 
-hoặc thêm tất cả file
+2. **Commit theo chuẩn**:
 
 ```bash
-git add .
+git commit -m "feat(module): mô tả ngắn gọn"
 ```
 
-### 3. Đặt commit message
+3. **Rebase trước khi merge**:
 
 ```bash
-git commit -m "feat(user): add user feature"
+git checkout develop
+git pull origin develop
+git checkout feature/new-feature
+git rebase develop
 ```
 
-=> Chờ hệ thống kiểm tra lỗi, nếu xảy ra lỗi, giải quyết lỗi và quay lại bước 2
+4. **Tạo Pull Request (PR)** và đợi review trước khi merge vào `develop`.
 
-### 4. Đẩy code lên git
+---
 
-```bash
-git push
-```
+> **Ghi chú:** Nếu có bất kỳ thắc mắc nào, vui lòng liên hệ team phát triển!