🔥 0
🛠️

Content Admin Lite

Tải template Excel mẫu, upload file .xlsx để validate + convert, rồi tải JSON về commit.

🌱 Thông tin phát hành

Website phục vụ tự học cho học sinh tiểu học lớp 3–5, phát hành phiên bản 1.0 ngày 14/02/2026 cho bạn Đỗ Nhật Minh (Lớp SN3A, Trường Tiểu học Ngọc Linh) tự luyện tập.

❓ Liên hệ góp ý, nâng cao chất lượng Website?

Share liên hệ để hoàn thiện, bổ sung chất lượng các bài học:

📧 Email: bach.eps@gmail.com

📱 SĐT: 0969.5969.89 (Bố Nhật Minh)

📘 Math Excel Guideline

Quy tắc nhập liệu marker {{m: ...}} cho KaTeX, ví dụ nhanh, checklist và lỗi thường gặp.

PHASE 3B

1) Marker math bắt buộc

  • Dùng inline marker: {{m: ...}}
  • Bên trong marker là LaTeX chuẩn KaTeX
  • Chỉ render phần trong marker, text thường giữ nguyên
  • Với fill_blank: đặt ____ ngoài marker math

Ví dụ 1: Tính {{m: \frac{3}{4} + \frac{1}{4}}}

Ví dụ 2: Giải: {{m: x + \frac{1}{4} = \frac{9}{4}}}; {{m: x =}} ____

2) Checklist trước khi convert

  • id không trùng trong cùng module
  • topic không rỗng, đặt tên nhất quán
  • level dùng 1|2|3|ALL (thiếu = ALL)
  • Câu trắc nghiệm: answer ∈ choices

3) Lỗi thường gặp + chất lượng nội dung

  • Quên bọc marker math cho phân số/biểu thức.
  • Đặt ____ bên trong marker math (không hợp lệ).
  • LaTeX sai cú pháp (thiếu ngoặc {}, escape sai).
  • Câu hỏi lặp mẫu chỉ thay số, gây nhàm chán cho trẻ.
  • explain_vi quá kỹ thuật, khó hiểu với học sinh tiểu học.

Nguồn guideline chi tiết: docs/MATH_EXCEL_GUIDELINE.md

💻 CLI: Convert trực tiếp từ Terminal

Chạy convert .xlsx → JSON trực tiếp từ Terminal (Windows/Mac/Linux) với đầy đủ options.

PHASE 6 Lite

1) Cú pháp cơ bản

npx tsx tools/content-pipeline/convert_xlsx_to_json.ts \
  --input=path/to/file.xlsx \
  --output=./content \
  --sheets=Grammar,Vocabulary \
  --skip-validation=duplicate,blank \
  --dry-run

2) Options

  • --input=<path> — File .xlsx đầu vào (bắt buộc)
  • --output=<dir> — Thư mục output (mặc định: ./content)
  • --sheets=<list> — Danh sách sheet cần convert (mặc định: tất cả)
  • --skip-validation=<list> — Bỏ qua validation rules
  • --dry-run — Chỉ validate, không ghi file
  • --help — Hiển thị hướng dẫn đầy đủ

3) Validation rules có thể skip

  • duplicate — Bỏ kiểm tra prompt trùng lặp
  • blank — Bỏ kiểm tra blank placement (fill_blank)
  • math — Bỏ kiểm tra marker math (KaTeX)
  • grammar-blank — Bỏ kiểm tra Grammar blank length
  • reading-passage — Bỏ kiểm tra Reading passage required

4) Ví dụ thực tế

Convert tất cả sheets:

npx tsx tools/content-pipeline/convert_xlsx_to_json.ts --input=temp/english_v3.xlsx

Convert chỉ Grammar và Vocabulary, bỏ check duplicate:

npx tsx tools/content-pipeline/convert_xlsx_to_json.ts \
  --input=temp/english_v3.xlsx \
  --sheets=Grammar,Vocabulary \
  --skip-validation=duplicate

Dry-run để kiểm tra trước khi ghi file:

npx tsx tools/content-pipeline/convert_xlsx_to_json.ts --input=temp/math_v2.xlsx --dry-run

🔊 English Audio CLI (Azure Speech)

Convert audio cho quiz_grammar.json + quiz_vocabulary.json theo mode incremental bằng manifest hash (engine: Azure Speech).

PHASE 5/6 Lite

1) Quick start (làm theo đúng thứ tự)

set AZURE_SPEECH_KEY=<your_key> và set AZURE_SPEECH_REGION=<your_region> (CMD)

$env:AZURE_SPEECH_KEY="<your_key>" và $env:AZURE_SPEECH_REGION="<your_region>" (PowerShell)

npm run audio:voices — xem voice preset nhanh

npm run audio:gen:dry — chạy thử, không ghi file

npm run audio:gen -- --voice=en-US-GuyNeural --rate=-8% --fill-rate=-20% --retry=4 --retry-delay-ms=2000 --sleep-ms=300 — generate thật toàn bộ pending

Nếu dữ liệu rất lớn, dùng batch: thêm --limit=20. Mỗi lần chạy sẽ lấy 20 câu pending tiếp theo (không lặp 20 câu đầu).

2) Ý nghĩa tham số dễ nhớ

  • --voice=en-US-GuyNeural: giọng Mỹ nam
  • --rate=-8%: chậm hơn 8% cho câu thường
  • --fill-rate=-20%: chậm hơn 20% cho câu fill_blank
  • --limit=20: chạy theo lô 20 câu pending/lần
  • --retry, --retry-delay-ms, --sleep-ms: giảm lỗi 403/rate-limit

3) Nếu gặp lỗi 403

  • Đổi voice: en-US-ChristopherNeural hoặc en-US-EricNeural
  • Giảm tải: thêm --limit=20 (batch theo pending)
  • Chờ 1–3 phút rồi chạy lại
  • Dùng retry/backoff: --retry=4 --retry-delay-ms=2000 --sleep-ms=300
  • Khi log báo Pending generate: 0 là đã xong toàn bộ.

4) Output + incremental policy

  • Không cần tự tạo thư mục audio (script tự tạo).
  • Audio file: public/audio/english/grammar/<id>.mp3 và public/audio/english/vocabulary/<id>.mp3
  • Manifest: content/english/audio_manifest.json
  • ID mới hoặc hash đổi → generate; hash không đổi + file tồn tại → skip
  • Prompt có blank dạng ____ hoặc bất kỳ chuỗi _{2,} đều được đọc bằng pause (không đọc "underscore"); riêng fill_blank đọc chậm hơn.
⬇️ Tải template Excel mẫuGồm 8 sheet: 2 English Quiz (Grammar, Vocabulary) + 4 Math Quiz + 2 Vietnamese MVP (Quiz + Learn)

🔍 Tùy chọn kiểm tra chất lượng:

Mặc định: tích hết. Bỏ tích rule không cần để bỏ qua cảnh báo.

Không ghi file lên server. Kết quả dùng để tải JSON về máy.