Exam Test Website

Hệ thống thi trực tuyến kiến trúc microservices, hỗ trợ nhiều loại câu hỏi, chấm điểm tự động và giám sát chống gian lận (proctoring) thời gian thực.

Mục lục

• Kiến trúc hệ thống
• Yêu cầu môi trường
• Bắt đầu nhanh (Docker)
• Chạy frontend riêng để phát triển
• Chạy không dùng Docker
• Kiểm thử (Testing)
• Database Migrations
• Tài liệu chi tiết
• Bảo mật

Kiến trúc hệ thống

Service	Vai trò	Cổng (local)
auth_service	Xác thực, JWT, quản lý người dùng	8000
question_service	Ngân hàng câu hỏi (MongoDB)	8001
exam_service	Quản lý kỳ thi, lịch thi, lượt làm bài	8002
realtime_service	WebSocket / Socket.IO đồng bộ trạng thái thi	8003
grading_service	Chấm điểm tự động (+ Celery worker)	8004
proctoring_service	Nhận & xử lý sự kiện giám sát, tính điểm rủi ro	8005
nginx	API Gateway, định tuyến /api/... tới các service trên	80 / 443

Hạ tầng dữ liệu: PostgreSQL (dữ liệu quan hệ), MongoDB (ngân hàng câu hỏi), Redis (cache, pub/sub, broker cho Celery).

Frontend: React 18 + TypeScript + Vite + Material UI, giao tiếp với backend qua API Gateway (nginx).

Sơ đồ kiến trúc chi tiết: docs/SoDoKienTrucTongThe.md

Yêu cầu môi trường

• Docker + Docker Compose (khuyến nghị — xem tại sao)
• Node.js 18+ nếu muốn chạy frontend độc lập ngoài Docker
• Python 3.11+ chỉ cần nếu chạy backend không qua Docker

Bắt đầu nhanh (Docker)

git clone https://github.com/CoderIshibuki/ExamTestWebsite.git
cd ExamTestWebsite

# Tạo file .env từ mẫu, điền giá trị thật (không commit file .env lên Git)
cp .env.example .env
cp frontend/.env.example frontend/.env

# Tạo SSL cert dev (tự sinh, không commit — xem phần Bảo mật)
python scripts/generate_ssl.py

# Dựng toàn bộ hệ thống
docker compose up --build

Sau khi chạy xong, truy cập:

• Ứng dụng: http://localhost (qua nginx gateway)
• Swagger docs của Auth service: http://localhost/docs

Hướng dẫn chi tiết từng bước, biến môi trường, và cách xử lý khi thiếu Docker: xem docs/SETUP.md.

Chạy frontend riêng để phát triển

Nếu chỉ cần sửa giao diện và có backend chạy sẵn ở nơi khác (VD: Docker ở máy chính, hoặc server dùng chung):

cd frontend
npm install
npm run dev

Xem thêm frontend/README.md.

Chạy không dùng Docker

Có thể chạy nhưng cần tự cài PostgreSQL, MongoDB, Redis và chạy tay từng service Python — xem hướng dẫn đầy đủ tại docs/SETUP.md.

Kiểm thử (Testing)

Backend

pytest backend/tests/

Frontend

cd frontend
npm run lint
npm run build

End-to-end (yêu cầu backend đang chạy qua Docker)

python scripts/e2e_test.py

Database Migrations

Migration được quản lý bằng Alembic, riêng cho từng service dùng PostgreSQL (auth_service, exam_service, grading_service, proctoring_service). Docker Compose tự khởi tạo DB khi chạy lần đầu; để chạy tay:

cd backend/<tên_service>
alembic upgrade head

Tài liệu chi tiết

Tài liệu	Nội dung
docs/SETUP.md	Hướng dẫn dựng môi trường dev đầy đủ (Docker & không Docker)
docs/ENV_VARS.md	Danh sách toàn bộ biến môi trường cần thiết cho từng service
docs/SoDoKienTrucTongThe.md	Sơ đồ kiến trúc tổng thể (Mermaid)
docs/SoDoLuongRealTime.md	Sơ đồ luồng real-time lúc thi (Mermaid sequence diagram)
docs/CongNgheSuDung.md	Danh sách công nghệ/thư viện sử dụng theo từng tầng
docs/ChucNang.docx	Đặc tả chức năng (Word)
CHANGELOG.md	Lịch sử thay đổi
SECURITY.md	Quy tắc xử lý secret & báo cáo lỗ hổng

Bảo mật

⚠️ Không commit file .env, SSL cert/key hoặc bất kỳ secret nào lên Git — xem SECURITY.md để biết chi tiết và sự cố đã xảy ra trước đây trong repo này.