Chi tiết dự án
AuraType
AuraType là studio luyện gõ phím song ngữ Việt — Anh theo phong cách tối giản, chạy hoàn toàn ngay trên trình duyệt với dữ liệu luyện tập lưu cục bộ bằng IndexedDB (Dexie) và tùy chọn tạo đoạn văn bằng Gemini AI trên server.
Hình ảnh thực tế
Vấn đề & Động lực
Phần lớn trang luyện gõ phím chỉ tối ưu cho tiếng Anh hoặc xử lý bộ gõ tiếng Việt (Telex/VNI) theo từng keystroke rời rạc, dễ lệch vị trí ký tự khi IME đang compose dấu, đồng thời cho phép paste hoặc autofill làm sai lệch kết quả thực tế.
Giải pháp
Xây dựng typing engine tách theo grapheme chuẩn Unicode NFC kết hợp bộ lọc beforeinput để chặn paste/drop/autofill mà vẫn giữ nguyên luồng composition của Telex/VNI, đồng bộ timeline từng thao tác gõ (bao gồm xóa/sửa) cho Ghost replay và tính WPM/Accuracy chuẩn xác.
Tính năng cốt lõi
Nhập liệu Telex / VNI chuẩn Grapheme
Chuẩn hóa NFC và tách cụm grapheme giúp việc đối chiếu dấu thanh tiếng Việt với văn bản mẫu chính xác ngay cả trong quá trình IME đang ghép chữ.
Ghost Replay & Mục tiêu WPM
Đấu trực tiếp với bản ghi của lượt hoàn thành tốt nhất trên cùng đoạn văn và bộ quy tắc, hoặc chọn Ghost tốc độ ổn định từ 30–120 WPM.
Tạo đoạn văn bằng Gemini AI (Server-only)
API route sử dụng @google/genai phía server kết hợp Upstash Redis để giới hạn cooldown theo IP (30–60s), quota ngày/giờ và pool cache dùng chung theo 24 giờ.
Lưu trữ cục bộ & Journey Panel
Cài đặt, lịch sử luyện tập và bản ghi cá nhân lưu trong IndexedDB qua Dexie (hỗ trợ export backup), đi kèm bảng phân tích quá trình luyện tập (JourneyPanel) ngay trên trình duyệt.
Công nghệ sử dụng
- Next.js
- TypeScript
- Zustand
- Dexie
- Gemini AI
- Upstash Redis
Kiến trúc hệ thống
Engine Layer (engine/typingEngine.ts, inputAdapter.ts, replayEngine.ts)
Xử lý trạng thái từng ký tự/grapheme, đánh giá beforeinput chặn dán/kéo thả ngoài IME và phát lại timeline cho Ghost replay.
State & Local Persistence (Zustand + Dexie)
Quản lý phiên gõ theo thời gian thực bằng Zustand và lưu lịch sử cá nhân, bản ghi replay, cài đặt trong IndexedDB mà không cần đăng nhập.
AI Generation API (app/api/generate, services/geminiProvider.ts)
Server-side Gemini API với luân chuyển key khỏe trong quota group, không retry bão khi lỗi 429 và cache đoạn văn hợp lệ bằng Upstash Redis.
Thách thức kỹ thuật
Đồng bộ IME Tiếng Việt với con trỏ & độ chính xác
Bộ gõ Telex/VNI tạo sự kiện composition liên tục trước khi chốt ký tự. Giải pháp là tách evaluateBeforeInput để phân biệt composition hợp lệ với autofill/paste đa ký tự, đồng thời tính accuracy theo tổng số lần chèn ký tự để các lỗi đã sửa vẫn được phản ánh trung thực.
Kiểm soát chi phí và quota Gemini API công khai
Thay vì gọi trực tiếp từ client hoặc rate-limit lỏng lẻo trong bộ nhớ, server dùng atomic reservation trên Redis để cấp lease thực thi, chặn burst 429 và tái sử dụng các đoạn văn đã kiểm duyệt trong cache pool.
Bài học rút ra
- Luôn thiết kế cơ chế degradation rõ ràng: chế độ luyện gõ cốt lõi và Ghost replay hoạt động ngoại tuyến/không cần AI key, chỉ phần tạo đoạn văn AI mới phụ thuộc Redis & Gemini.
- Xử lý tiếng Việt trên web đòi hỏi kiểm thử trực tiếp với composition events và Unicode NFC thay vì dựa vào độ dài chuỗi UTF-16.
Phạm vi triển khai hiện tại
Phiên bản hiện tại chạy live tại auratype.duckdns.org với đầy đủ chế độ luyện gõ, Ghost replay, tùy chỉnh đoạn văn 150–1.400 ký tự và AI generation (tùy cấu hình server). Không có bảng xếp hạng công khai hay tài khoản cloud — toàn bộ lịch sử nằm trên thiết bị người dùng.