PWA ôn TOEIC Listening & Reading, miễn phí 100%, đồng bộ Mac + iPhone.
Xem PLAN.md (lộ trình), DECISIONS.md (quyết định + lý do), PROGRESS.md (trạng thái hiện tại).
Repo là private nên bạn bè không đọc được file này. Copy tin nhắn dưới đây gửi họ:
App ôn TOEIC (miễn phí, không quảng cáo): https://toeic-app.huybndc-451.workers.dev
1. iPhone: mở bằng Safari → nút Chia sẻ → "Thêm vào MH chính". Mac/PC: mở bằng trình duyệt là được.
2. Tab "Sao lưu" → nhập email + mật khẩu → "Lần đầu dùng? Tạo tài khoản". Không tạo thì tiến độ
chỉ nằm trong trình duyệt đó, Safari có thể xoá nếu 7 ngày không mở.
3. Màn chính → "Bắt đầu" → chọn tầng từ hợp trình độ (800+ thì chọn Trung cấp/Cao cấp) → chấm 20 từ.
Sau đó mỗi lần mở app cứ bấm theo gợi ý ở ô "Hôm nay".
Dùng cùng tài khoản trên máy khác thì tiến độ tự đồng bộ.
Mỗi người chỉ thấy dữ liệu của chính mình (RLS — D56). Khi nào cần đóng đăng ký lại: xem D56.
npm install # chỉ lần đầu
npm run dev # mở http://localhost:5173
npm test # chạy test
npm run build # build ra dist/Áp dụng cho MỌI lần quay lại project, kể cả sau nhiều tuần.
Mở Claude Code với thư mục toeic-app (không phải thư mục cha). Claude tự đọc CLAUDE.md.
Đọc PROGRESS.md rồi tóm tắt: đang ở milestone nào, bước tiếp theo là gì, hôm nay nên làm gì.
Không cần kể lại gì thêm. Mọi thứ cần biết đã nằm trong PROGRESS.md, PLAN.md, DECISIONS.md.
Claude sẽ tự đối chiếu với git log để biết thực tế khớp tài liệu không.
- Muốn đổi hướng hoặc thêm ý tưởng: cứ nói. Nếu nằm ngoài milestone hiện tại, Claude sẽ ghi vào
mục Backlog trong
PLAN.mdthay vì làm ngay (ràng buộc #8). - Muốn đổi một quyết định đã ghi trong
DECISIONS.md: Claude phải hỏi lại trước khi đổi (ràng buộc #9).
- Khi Claude chủ động báo "đã lưu trạng thái, hãy
/clear". - Hoặc khi chuyển sang việc khác hẳn (ví dụ đang làm nội dung, giờ chuyển sang sửa giao diện).
Trước khi /clear, nếu Claude chưa tự làm thì gõ:
Cập nhật PROGRESS.md, chạy check_processes.sh, rồi commit và push.
Không mất gì. Phiên mới chỉ cần:
Chạy git status và git log --oneline -5, đối chiếu với PROGRESS.md xem có gì làm dở không.
Kèm đủ 2 thứ này thì Claude dò ra gần như ngay:
- Số hiệu bản build ở cuối màn chính (vd
bản 2026-09-19 12:19) — để biết có đang xem bản cũ không. - Nguyên văn dòng lỗi hiện trên màn hình, hoặc ảnh chụp.
Nếu lỗi ở app đã deploy: tải lại trang trước khi báo (Mac Cmd+Shift+R; iPhone đóng hẳn app rồi mở lại).
npm run build:vocab -- --limit 20 # thử 20 từ đầu trước cho chắc
npm run build:vocab # làm toàn bộ 1250 từ TSL
npm run validate:content # kiểm tra file nội dung theo schema
npm run audit:vocab # soi chất lượng + bốc 30 từ ngẫu nhiên để duyệtViệc chạy dài nên ghi log ra file để theo dõi được tiến độ, và nhớ dọn tiến trình nền khi xong:
npm run build:vocab > /tmp/vocab-run.log 2>&1 & # chạy nền, theo dõi bằng: tail -f /tmp/vocab-run.log
bash scripts/check_processes.sh # xem còn tiến trình nền nào khôngCần GEMINI_API_KEY trong .env (xem .env.example). Pipeline chạy lại được nhiều lần:
kết quả AI của từng từ được lưu ở pipeline/.cache/, chạy lại chỉ gọi AI cho từ còn thiếu —
quan trọng vì free tier giới hạn số lượt mỗi phút.
| Thư mục | Trách nhiệm |
|---|---|
src/logic/ |
Hàm thuần, không đụng DOM — test được bằng Node |
src/data/ |
IndexedDB, đồng bộ Supabase, tải nội dung |
src/ui/ |
Màn hình + router, chỉ nơi này được đụng DOM |
public/content/ |
Nội dung JSON đã kiểm định (từ vựng, câu hỏi) |
pipeline/ |
Script Node sinh nội dung, chạy trên máy (không chạy trong app) |
schemas/ |
JSON schema cho vocab / question / event |
tests/ |
Test Vitest cho src/logic và pipeline |
src/logic/ không bao giờ import từ src/ui/.
- TOEIC Service List (TSL) 1.2 — Browne, C. & Culligan, B. (2013), https://www.newgeneralservicelist.com. Phát hành theo CC BY-SA 4.0.
- New General Service List (NGSL) 1.2 — Browne, C., Culligan, B. & Phillips, J. (2013), cùng nguồn và cùng giấy phép.
Dữ liệu từ vựng trong public/content/ là bản phái sinh của hai danh sách trên nên cũng theo CC BY-SA 4.0
(xem DECISIONS.md — D18). Phần mã nguồn không thuộc phạm vi giấy phép này.