# Hướng dẫn triển khai QuizLab trên GitHub Pages

## A. Tạo repository

1. Đăng nhập GitHub bằng tài khoản bạn muốn sử dụng.
2. Mở https://github.com/new, chọn **Repository name:** `quizlab`.
3. Chọn **Public** để GitHub Pages miễn phí trên repo cá nhân hoạt động theo cách phổ biến; lưu ý câu hỏi sẽ công khai.
4. Nhấn **Create repository**. Có thể để trống README vì bộ nguồn này đã có sẵn.
5. Giải nén `QuizLab_GitHub_Pages.zip`, sau đó tải **toàn bộ các file và folder bên trong** lên **thư mục gốc** của repo: `index.html`, `assets/`, `data/`, `docs/`, `tests/`, v.v. Không tải nguyên file ZIP lên và không lồng thêm một thư mục `QuizLab_GitHub_Pages/`.
6. Commit các file trên nhánh `main`.

## B. Bật GitHub Pages

1. Trong repo, mở **Settings → Pages**.
2. Ở **Build and deployment → Source**, chọn **Deploy from a branch**.
3. Chọn **Branch: main**, thư mục **/(root)**, nhấn **Save**.
4. Xem đường dẫn trang tại **Settings → Pages** khi GitHub thông báo hoàn tất (thường có dạng `https://USERNAME.github.io/quizlab/`).

Hướng dẫn chính thức: https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site

## C. Cấp quyền kết nối GitHub cho ChatGPT

1. Mở cấu hình kết nối GitHub trong ChatGPT hoặc màn hình cấp quyền GitHub App.
2. Chọn repository `quizlab` trong **Repository access** (hoặc tất cả repositories theo ý bạn).
3. Bảo đảm kết nối có quyền ghi nội dung khi bạn muốn trợ lý commit cập nhật.
4. Trong hội thoại: yêu cầu trợ lý thêm câu hỏi và cập nhật file `data/questions.js` trong `USERNAME/quizlab`.

Hiện trạng lúc tạo bộ nguồn: trợ lý nhìn thấy username `hughtrinh` nhưng chưa thấy repository nào được cấp quyền trong GitHub App. Không có thay đổi nào được đẩy lên GitHub trong quá trình tạo bộ nguồn này.

## D. Cập nhật 10 câu mới

1. Tìm bộ đề gốc và xác minh **đầy đủ lựa chọn trả lời**, không tự tạo phương án nhiễu.
2. Giữ nguyên văn nội dung câu hỏi và lựa chọn của đề.
3. Kiểm tra đáp án đúng; thêm giải thích tiếng Việt trong `explanation`.
4. Thêm 10 object vào mảng `questions` trong `data/questions.js` với `id` không trùng.
5. Sửa `version` và `updatedAt`, commit thay đổi.
6. Làm mới trang để thấy đề mới; không cần tải HTML lại.

Mẫu:

```js
{
  "id": "cnn-w4-001",
  "topic": "Week 4 · Special applications",
  "week": 4,
  "text": "Exact original English question?",
  "options": ["Exact option A", "Exact option B", "Exact option C", "Exact option D"],
  "correct": [1],
  "explanation": "Giải thích bằng tiếng Việt.",
  "source": "starter"
}
```

**Chú ý**: `correct` là mảng index từ 0. `[1]` = đáp án B, `[0, 2]` = A và C. Một `id` duy trì ổn định để giữ đúng tiến độ giữa các lần cập nhật. Nếu lựa chọn/đáp án thay đổi thì ứng dụng đặt lại tiến độ câu tương ứng nhằm tránh chấm sai.

## E. Lưu và chuyển tiến độ

- Trang web lưu `localStorage` trong trình duyệt hiện tại, không chia sẻ dữ liệu tự động giữa thiết bị.
- Trước khi đổi từ HTML offline cũ sang website, chọn **Sao lưu dữ liệu (.json)** ở bản cũ; tại website mới vào **Nạp câu hỏi → Chọn tệp .json** để khôi phục lịch sử nếu cấu trúc bản sao tương thích.
- Tính năng Nạp câu hỏi trong website là **nạp cục bộ**, không cập nhật repository.
- Nếu muốn đồng bộ lịch sử nhiều máy trong tương lai cần backend và đăng nhập.

## F. Xử lý lỗi thường gặp

- 404: `index.html` cần ở root và Pages chọn đúng nhánh `main`.
- Trang trống: kiểm tra `data/questions.js`, lỗi dấu `,` khi thêm object.
- Chưa thấy câu mới: làm mới trang; kiểm tra commit đã ở `main`, trạng thái Pages và `version/updatedAt`.
- Hình không hiện: hình của đề Detection sử dụng URL nguồn bên ngoài; người cung cấp ảnh có thể thay đổi quyền truy cập/hotlink.
