Cài đặt môi trường
Yêu cầu hệ thống
| Công cụ | Phiên bản tối thiểu | Ghi chú |
|---|---|---|
| Node.js | >= 20.0.0 | Khuyến nghị dùng LTS |
| pnpm | >= 10.0.0 | Package manager chính của dự án |
| PostgreSQL | >= 15 | Database chính |
| Redis | >= 7 | Cache, session, queue |
| Docker | >= 24 | Chạy Redis qua Docker Compose |
| Git | >= 2.40 | Quản lý source code |
Clone và cài đặt
# Clone repository
git clone <repo-url> smartck-hub
cd smartck-hub
# Cài đặt dependencies cho toàn bộ monorepo
pnpm install
pnpm
Dự án sử dụng pnpm workspace + Turborepo. Chỉ cần chạy pnpm install tại thư mục gốc, tất cả packages và apps sẽ được cài đặt tự động.
Cấu hình biến môi trường
# Copy file mẫu
cp apps/backend/.env.example apps/backend/.env
Mở apps/backend/.env và cập nhật các biến quan trọng:
# Database - thay user/password/db phù hợp
DATABASE_URL="postgresql://user:password@localhost:5432/smartck_erp?schema=public"
# Redis
REDIS_ENABLED=false # Đặt true nếu đã chạy Redis
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=smartck_redis_pass
# JWT - đổi secret cho production
JWT_SECRET=your-secret-key-change-in-production
JWT_EXPIRES_IN=15m
JWT_REFRESH_EXPIRES_IN=7d
# S3-Compatible Storage (MinIO/AWS S3)
S3_ENDPOINT=http://localhost:9000
S3_ACCESS_KEY_ID=your-access-key
S3_SECRET_ACCESS_KEY=your-secret-key
S3_BUCKET=smartck-uploads
# SMTP (fallback khi chưa cấu hình trong Settings)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USERNAME=
SMTP_PASSWORD=
Khởi tạo database
# Tạo Prisma Client từ schema
pnpm db:generate
# Đẩy schema lên database (không tạo migration file)
pnpm db:push
# Seed dữ liệu mẫu (22 seed files)
pnpm db:seed
Thứ tự quan trọng
Luôn chạy db:generate trước db:push và db:seed. Nếu thay đổi schema, chạy lại cả 3 lệnh theo thứ tự.
Chạy Redis
Redis được cấu hình sẵn trong Docker Compose tại apps/backend/docker-compose.yml:
# Chạy Redis + Redis Commander (Web UI)
cd apps/backend
docker compose up -d
| Service | URL | Mô tả |
|---|---|---|
| Redis | localhost:6379 | Cache & session |
| Redis Commander | http://localhost:8081 | Web UI quản lý Redis |
Chạy development server
# Từ thư mục gốc - chạy cả backend + frontend đồng thời
pnpm dev
Lệnh pnpm dev sử dụng Turborepo để khởi động song song cả hai app.
Truy cập ứng dụng
| Service | URL | Mô tả |
|---|---|---|
| Frontend | http://localhost:5173 | Giao diện React |
| Backend API | http://localhost:3000 | NestJS REST API |
| Swagger UI | http://localhost:3000/api/docs | Tài liệu API tương tác |
| Prisma Studio | Chạy pnpm db:studio | GUI quản lý database |
Tài khoản test mặc định
Tất cả tài khoản test sử dụng mật khẩu: Admin@123
| Username | Vai trò | |
|---|---|---|
admin | SUPER_ADMIN | admin@smartckhub.com |
bod_cogo | CO-GO | cogo@smartckhub.com |
bod_director | BOD | bod@smartckhub.com |
hr_manager | ADMIN (HR) | hr@smartckhub.com |
dept_manager | DEPARTMENT_LEADER | dept.manager@smartckhub.com |
team_lead | POD_LEADER | team.lead@smartckhub.com |
employee1 | SPECIALIST | employee1@smartckhub.com |
intern1 | INTERN | intern1@smartckhub.com |
Tài khoản POD
Ngoài ra còn có các tài khoản pod1_member2, pod2_member2, pod3_lead, ... dùng để test chức năng quản lý POD. Xem chi tiết trong apps/backend/prisma/seeds/users.seed.ts.
Các lệnh hữu ích
pnpm dev # Chạy dev server (cả BE + FE)
pnpm build # Build production
pnpm test # Chạy toàn bộ test
pnpm lint # Kiểm tra linting
pnpm format # Format code với Prettier
pnpm db:studio # Mở Prisma Studio
pnpm db:reset # Reset database (xóa + seed lại)
pnpm api:generate # Tạo lại API client từ Swagger