Exercise with AI - Speak a Sentence

DomainsDOL EnglishUX5.848 words29 min read

draftbyDOL Product Design

Nói một câu (Speak a Sentence)

Purpose

Vấn đề: Bài luyện nói cũ chỉ yêu cầu repeat (đọc lại câu có sẵn), không buộc học viên tự tạo câu. Học viên thuộc lòng nhưng không biết xài cấu trúc khi cần nói tự do.
Đối tượng chính: Học viên đang học/ôn cấu trúc câu (Speak in Structure) trong chương trình Linearthinking.
Tín hiệu thành công: Học viên tự nói được 1 câu hoàn chỉnh đúng cấu trúc mục tiêu, với nội dung do chính mình tạo, phát âm được feedback và luyện lại ngay.

Ý tưởng tổng quan (Experience Narrative)

Speak a Sentence là dạng bài đơn giản nhất - luyện Speak in Structure. AI (Gemini) hỏi câu hỏi Part 1 → học viên nói 1 câu dùng đúng cấu trúc → AI highlight real-time kiểu karaoke (chế độ Dễ) hoặc nghe rồi fill kết quả (chế độ Khó). Cuối mỗi câu, AI check phát âm và mở popup luyện tập phát âm từng từ dở.

Có 2 chế độ: Dễ (cấu trúc hiện sẵn, chạy karaoke khi nói) và Khó (chỉ gợi ý tên cấu trúc, tự chọn và dùng). AI linh hoạt: nếu học viên dùng cấu trúc khác so với gợi ý nhưng vẫn hợp lệ trong kho knowledge → AI thay đổi khung và vẫn chấp nhận.

Nguồn dữ liệu

Kho đề: Generate random câu hỏi Part 1.
Knowledge base: File Linear 6.0S (mỗi band có kho cấu trúc khác nhau, nhập liệu sau). Chứa các sentence structures + word patterns phân loại theo loại câu hỏi (Why, Where, What, How…).
Demo hiện tại: https://speakasentence.dol.vn/

Product Model

Session fields

Field	Mô tả
`difficulty_mode`	`easy` hoặc `hard`
`narrator_language`	`vi` hoặc `en`, dùng cho lời dẫn/feedback của AI teacher
`mic_permission_status`	unknown, granted, denied
`current_question_id`	Câu hỏi Part 1 hiện tại
`question_text`	Câu hỏi hiển thị và được narrator đọc
`question_type`	Why, What, Where, How…, dùng để chọn cấu trúc phù hợp
`target_structure_id`	Cấu trúc mục tiêu AI muốn user luyện trong round
`target_structure_text`	Skeleton/cấu trúc đầy đủ, ví dụ `That will be ___`
`structure_options`	Danh sách option cấu trúc cho chế độ Khó
`active_option_id`	Option được nhận diện là user đã dùng đúng
`round_state`	waiting_teacher, ready, listening, analyzing, correct, incorrect, retrying
`heard_transcript`	Nội dung AI nghe được từ user
`feedback_message`	Nhận xét hiện tại của AI
`attempt_count`	Số lần user thử câu hiện tại

Tính năng (Features)

F0 - Entry & Mode Selection

Mở bài tập có thể yêu cầu quyền microphone trước khi vào luyện.
User chọn:
- độ khó: Dễ hoặc Khó;
- ngôn ngữ người dẫn truyện / AI teacher: Tiếng Việt hoặc Tiếng Anh.
Lựa chọn có thể đổi lại trong quá trình luyện nếu product muốn, nhưng đổi mode giữa round nên áp dụng từ câu tiếp theo để tránh reset câu đang nói.
narrator_language chỉ ảnh hưởng lời dẫn, feedback, và microcopy của AI teacher; câu hỏi và câu user cần nói vẫn là tiếng Anh.
Mode selection copy cần ngắn: Chọn chế độ luyện tập và ngôn ngữ của giáo viên hướng dẫn nhé.

F1 - Hai chế độ luyện tập

Chế độ Dễ (Gợi ý sẵn)

Cấu trúc hiện sẵn đầy đủ trên màn hình dạng gap-fill skeleton (ví dụ: The best part about ___ is that it allows me to ___).
User chỉ cần thêm từ/cụm từ của mình vào chỗ trống để hoàn thiện cấu trúc.
Khi học viên nói → AI tô xanh real-time từng từ kiểu karaoke - tạo cảm giác được lắng nghe và cấu trúc được “gạch” trước mắt.
Khi hết câu → AI fill phần thông tin thừa (vocabulary) vào các chỗ trống.
Nếu user nói đúng cấu trúc, input chuyển trạng thái xanh và AI tự động chuyển câu tiếp theo sau feedback ngắn.

Phạm vi Chế độ Dễ - chỉ kiểm 2 chiều: (1) bám skeleton có sẵn không, (2) từ điền vào blank có đúng đề không. Mode Dễ KHÔNG accept user dùng cấu trúc khác (kể cả khi cấu trúc đó hợp lệ trong knowledge base) - đó là phạm vi của Chế độ Khó. Chi tiết error cases trong Easy:

Case	Mô tả	Hành vi AI
Không bám cấu trúc gợi ý	User nói câu không theo skeleton (ví dụ: skeleton `That will be ___` nhưng user nói “I really enjoy reading books”)	Khung đỏ + feedback “Câu này chưa bám cấu trúc gợi ý. Em hãy nói theo `That will be ___` nhé.” → giữ câu hiện tại, retry
Lạc đề / từ điền sai	User bám đúng skeleton nhưng nội dung điền vào blank không liên quan đến câu hỏi (ví dụ: câu hỏi “What kind of book do you like?” + skeleton `That will be ___` + user nói “That will be a sandwich”)	Khung amber + feedback “Em đã bám đúng cấu trúc rồi, nhưng phần điền chưa khớp câu hỏi. Em thử nói lại với một loại sách nhé.” → giữ câu, retry
Sai ngôn ngữ	User nói tiếng Việt thay vì tiếng Anh	Khung đỏ + “Bạn hãy trả lời bằng tiếng Anh nhé.” → retry
Câu quá ngắn / thiếu phần cần điền	User nói skeleton nhưng bỏ trống blank hoặc nói quá ít	Khung đỏ nhẹ + “Câu này còn hơi ngắn. Thêm ý để câu rõ hơn nhé.” → retry
Đúng cấu trúc + lạc đề KHÔNG xảy ra cùng lúc	-	Lạc đề là sub-case của “đúng cấu trúc”; ưu tiên báo “lạc đề”

Chế độ Khó (Tự chọn cấu trúc)

Khung trả lời không hiện cấu trúc chính trong input. User được tự chọn hướng trả lời từ các option gợi ý bên dưới.
Các option là cấu trúc/phrase starter hợp với câu hỏi, ví dụ:
- A big part of the reason goes to the fact __
- nothing else if not __
- That'll be __
User có thể dùng option hoặc nói bất kỳ câu hợp lệ khác.
Nếu user nói đúng một option, option đó được active để user thấy mình đã dùng cấu trúc nào.
Nếu im lặng > 2 giây (hoặc nói “ừm ờ” không nhất quán) → AI có thể gợi ý bằng cách nhấn mạnh option phù hợp hoặc hiện vài từ đầu cấu trúc.
Khi học viên bắt đầu nói → AI nghe toàn bộ → generate câu hoàn chỉnh, tô xanh phần cấu trúc + đen phần vocabulary.

Chuyển chế độ

Có thể toggle giữa Dễ/Khó ở mọi scene.
Hoặc tách thành 2 app con cho các exercises khác nhau.

F2 - AI Teacher / Narrator Interaction

AI teacher hỏi câu hỏi bằng voice (TTS).
Từ đầu tiên của câu hỏi luôn được bold màu đỏ (để học viên nhận diện loại câu hỏi → chọn đúng cấu trúc).
AI teacher voice feedback sau mỗi câu theo narrator_language.
Nếu chọn Tiếng Việt, feedback giải thích bằng tiếng Việt nhưng giữ structure/câu mẫu bằng tiếng Anh.
Nếu chọn Tiếng Anh, feedback dùng tiếng Anh đơn giản, ngắn, phù hợp người học.

F2.1 - Listening, Transcript & Feedback

Khi user nói, hệ thống luôn tracking:
- trạng thái đang nghe;
- text AI nghe được (heard_transcript);
- trạng thái đang phân tích;
- feedback đúng/sai.
UI nên hiển thị rõ Đang lắng nghe bạn... khi recording và Đang phân tích... sau khi user bấm xong/dừng.
Khi AI nghe được nội dung, khung trả lời fill transcript vào câu/skeleton để user biết hệ thống đã nghe gì.
Nếu sai, khung trả lời chuyển trạng thái lỗi và AI nêu rõ cần sửa gì, ví dụ: Bạn hãy trả lời bằng tiếng Anh nhé. Hãy thử đọc "that will be psychology" nhé.
Nếu đúng, khung trả lời chuyển trạng thái đúng và AI tự động chuyển câu tiếp theo sau feedback ngắn.

F3 - Đổi cấu trúc linh hoạt (CHỈ áp dụng Chế độ Khó)

Scope: Đây là behavior riêng của Chế độ Khó - vì Khó cho user tự chọn cấu trúc (không có skeleton cho sẵn). Mode Dễ KHÔNG có behavior này; nói khác skeleton = báo “không bám cấu trúc gợi ý” + retry.

Trong Chế độ Khó, nếu học viên nói cấu trúc khác so với gợi ý option chips → AI check trong kho knowledge base:
- Hợp lệ: Accept cấu trúc khác + voice feedback “DOL thấy em đã dùng một cấu trúc Why khác so với gợi ý, nhưng cũng rất hay nè.” → chuyển câu mới (không cần active option).
- Không hợp lệ: Báo lỗi + bắt nói lại với cấu trúc khác hoặc dùng option gợi ý.

Trạng thái hiện tại: chưa làm tính năng này. Giữ spec ở đây làm reference cho roadmap. Cuối mỗi câu hiện tại chỉ check (cấu trúc + đề bài + ngôn ngữ + độ dài), KHÔNG check phát âm. Tính năng pronunciation feedback sẽ là phase sau (cả Mode Dễ + Khó).

Khi triển khai sẽ là:

Cuối mỗi câu, AI tự động check phát âm:
- Phát âm ổn: Chỉ feedback ngắn → chuyển câu tiếp.
- Phát âm dở: Mở popup luyện tập:
  1. Hiện lại cấu trúc + thông tin đã nói, làm mờ xám các phần không thuộc cấu trúc.
  2. Đi từng từ/cụm phát âm dở → Gemini voice cue: “Cùng DOL phát âm chữ part of nha.”
  3. Cue âm thanh “tinh tinh” → học viên nói → AI feedback (ví dụ: “Nhớ nối âm giữa part và of nhé”).
  4. Xong từ nào → tô xanh từ đó → chuyển sang từ tiếp.
  5. Xong hết → đóng popup → quay về giao diện cũ → nói lại cả câu 1 lần nữa (round này tắt nhận xét phát âm, tô xanh hết khi nghe được → chuyển câu).

Scene Flow

Scene 0: Check mic
    ├── Mic granted → Scene 1
    └── Mic denied → xin quyền mic / retry

Scene 1: Chọn chế độ + ngôn ngữ người dẫn
    ├── [Dễ + VI/EN] → Scene 2a
    └── [Khó + VI/EN] → Scene 2b

Scene 2a (Dễ):
    Gemini hỏi câu hỏi (voice + text, từ đầu bold đỏ)
    → Cấu trúc hiện sẵn dạng skeleton
    → HV nói → tracking heard transcript + karaoke tô xanh real-time
    → Hết câu → AI phân tích → fill vocabulary vào slots
    → Kết quả:
        ├── Đúng cấu trúc + đúng đề → khung xanh + feedback + tự động chuyển câu
        ├── Đúng cấu trúc nhưng từ điền lạc đề → khung amber + retry
        ├── Không bám cấu trúc gợi ý → khung đỏ + retry
        ├── Câu quá ngắn / thiếu phần điền → khung đỏ nhẹ + retry
        └── Sai ngôn ngữ (Việt thay vì Anh) → feedback + yêu cầu làm lại
    Note:
    - Chế độ Dễ KHÔNG accept cấu trúc khác skeleton (kể cả hợp lệ trong KB). Đó là Mode Khó.
    - Scene 4 (Pronunciation popup) hiện tại CHƯA TRIỂN KHAI - không check phát âm. Roadmap future.

Scene 2b (Khó):
    Gemini hỏi câu hỏi (voice + text, từ đầu bold đỏ)
    → Input trống + option chips gợi ý cấu trúc
    → HV nói ngay → AI nghe → generate + tô xanh/đen
    → Nếu match option → active option đó
    → HV im lặng > 2s → Nhấn mạnh option hoặc gợi ý vài từ đầu
    → Kết quả: giống Scene 2a

Scene 4 (Popup phát âm) - 🔮 FUTURE / chưa triển khai:
    [reserved cho roadmap - sẽ làm phase sau]
    Hiện câu đã nói, mờ phần không thuộc cấu trúc
    → Từng từ dở → Gemini cue → HV nói → tô xanh
    → Xong hết → đóng popup → nói lại cả câu
    → Chuyển câu tiếp

Scene 0 - Check mic

Bước	User làm gì	Hệ thống/AI phản hồi
0.1	Vào bài Speak a Sentence	Check quyền microphone
0.2	Chưa cấp quyền	Hiển thị màn xin quyền micro
0.3	Bấm cho phép microphone	Nếu granted, chuyển sang chọn chế độ
0.4	Từ chối quyền	Giữ ở màn check mic, hướng dẫn mở quyền mic

Scene 1 - Chọn chế độ

Bước	User làm gì	Hệ thống/AI phản hồi
1.1	Chọn `Dễ` hoặc `Khó`	Card được active, mô tả ngắn cách luyện
1.2	Chọn `Tiếng Việt` hoặc `Tiếng Anh`	Set `narrator_language` cho lời dẫn/feedback
1.3	Bắt đầu bài	Load giao diện tương ứng với mode đã chọn

Scene 2a - Chế độ Dễ

Bước	User làm gì	Hệ thống/AI phản hồi
1	Nghe Gemini hỏi câu hỏi	Voice + text, từ đầu bold đỏ
2	Nhìn cấu trúc skeleton trên khung	Skeleton hiện sẵn, ví dụ `That will be ___`
3	Nói 1 câu và điền nội dung vào skeleton	Karaoke: AI tô xanh từng phần cấu trúc khi nghe được
4	Bấm xong / hệ thống nhận hết câu	UI hiển thị transcript AI nghe được và chuyển `Đang phân tích...`
5a	- Đúng cấu trúc + đúng đề	Khung xanh + Gemini voice: “Tuyệt vời!” → tự động chuyển câu tiếp
5b	- Đúng cấu trúc nhưng từ điền lạc đề	Khung amber + Gemini: “Em đã bám đúng cấu trúc rồi, nhưng phần điền chưa khớp câu hỏi. Em thử nói lại với một [đối tượng đề bài] nhé.” → retry
5c	- Không bám cấu trúc gợi ý	Khung đỏ + Gemini: “Câu này chưa bám cấu trúc gợi ý. Em hãy nói theo `[skeleton]` nhé.” → retry
5d	- Sai ngôn ngữ (Việt thay vì Anh)	Khung đỏ + “Bạn hãy trả lời bằng tiếng Anh nhé.” → retry
5e	- Câu quá ngắn / thiếu phần điền	Khung đỏ nhẹ + “Câu này còn hơi ngắn. Thêm ý để câu rõ hơn nhé.” → retry

Không có ở Chế độ Dễ:

Dùng cấu trúc khác (hợp lệ hay không hợp lệ) - đó là phạm vi Chế độ Khó. Nếu user nói khác skeleton trong Easy → fallback về case 5c “không bám cấu trúc gợi ý”.

Pronunciation feedback / popup luyện phát âm - 🔮 chưa triển khai (cả 2 chế độ). Sẽ là roadmap future.

Scene 2b - Chế độ Khó

Bước	User làm gì	Hệ thống/AI phản hồi
1	Nghe Gemini hỏi câu hỏi	Voice + text, từ đầu bold đỏ
2	Nhìn input trống + option chips	Option chips là các cấu trúc user có thể dùng
3a	Nói ngay	AI nghe toàn bộ → fill câu user nói vào input
3b	Im lặng > 2s	AI nhấn mạnh/gợi ý option phù hợp hoặc vài từ đầu
4	AI phân tích câu nói	Match câu nói với knowledge base và option list
5a	Nói đúng một option	Active option đó + khung xanh + feedback → chuyển câu
5b	Nói đúng cấu trúc khác hợp lệ	Không cần active option; AI báo dùng cấu trúc khác hợp lệ → chuyển câu
5c	Nói sai/ngôn ngữ không đúng	Khung đỏ + feedback + yêu cầu nói lại
5d	~~Phát âm dở → Scene 4~~	🔮 Future / chưa triển khai

Trạng thái hiện tại: tính năng chưa làm. Bảng dưới giữ làm reference cho roadmap. Hiện tại không check phát âm sau câu nói - chuyển câu tiếp ngay khi pass các check khác (cấu trúc + đề + ngôn ngữ + độ dài).

Bước	User làm gì	Hệ thống/AI phản hồi
1	Nhìn popup (câu đã nói, mờ phần không cấu trúc)	Gemini: “Cùng DOL phát âm chữ [từ] nha. [từ].“
2	Nói từ đó	Cue “tinh tinh” → AI check
2a	- Đúng	Tô xanh từ đó → chuyển từ tiếp
2b	- Sai	Gemini feedback cách phát âm → nói lại
3	Lặp cho tất cả từ dở	Từng từ tô xanh dần
4	Xong hết → popup đóng	Quay về giao diện cũ
5	Nói lại cả câu 1 lần nữa	Karaoke tô xanh hết (round này không nhận xét phát âm)
6	Xong	Chuyển câu tiếp

AI Behavior & AI-UI Interaction

Trigger	AI action	Hiển thị trên UI
Entry
User chưa cấp mic	Request microphone permission	Màn `Vui lòng cho phép truy cập Microphone của bạn`
User chọn mode/language	Save `difficulty_mode` + `narrator_language`	Active cards ở màn chọn chế độ
Chế độ Dễ
HV đang nói	Gemini Live STT → match từng từ với cấu trúc	Karaoke: tô xanh real-time từng từ + `heard_transcript`
HV hết câu	Parse sentence → extract vocab → fill slots	`Đang phân tích...` rồi slots trống điền vocabulary
Đúng cấu trúc + từ điền đúng đề	Accept	Khung xanh + voice feedback + tự động chuyển câu
Đúng cấu trúc nhưng từ điền lạc đề	Reject content (skeleton OK)	Khung amber + feedback chỉ ra phần điền sai → retry, giữ skeleton
Không bám cấu trúc gợi ý (nói câu khác skeleton)	Reject	Khung đỏ + feedback “chưa bám cấu trúc” + nhắc lại skeleton → retry
Nói tiếng Việt thay vì tiếng Anh	Reject	Khung đỏ + “trả lời bằng tiếng Anh” → retry
Câu quá ngắn / thiếu phần điền	Reject	Khung đỏ nhẹ + “thêm ý” → retry
Chế độ Khó
HV im lặng > 2s	Chuyển sang option hint mode	Highlight option hoặc hiện vài từ đầu cấu trúc
HV bắt đầu nói	Nghe toàn bộ cho đến khi hoàn thiện	Loading → generate câu hoàn chỉnh
HV hết câu	Match câu nói với option/KB	Tô xanh phần cấu trúc + đen phần vocab
Câu nói match một option	Set `active_option_id`	Option chip active + khung xanh
Câu nói đúng nhưng ngoài option	Accept valid alternate structure	Feedback dùng cấu trúc khác hợp lệ
Câu nói sai	Reject	Khung đỏ + feedback + giữ nguyên câu hiện tại
Pronunciation (cả 2 chế độ) - 🔮 FUTURE / chưa triển khai
~~Cuối mỗi câu~~	~~Run prompt check phát âm~~	Hiện tại: skip pronunciation check; chuyển câu tiếp ngay khi pass các check khác
~~Trong popup~~	~~Voice cue từng từ dở~~	Roadmap future
~~Xong popup~~	~~Đóng popup → nói lại cả câu~~	Roadmap future
~~Nói lại cả câu~~	~~Tắt nhận xét phát âm, tô xanh hết~~	Roadmap future

Gemini Voice Script Examples

Tình huống	Gemini nói
Đúng cấu trúc + đúng đề (cả Easy + Hard)	“Tuyệt vời, em đã dùng đúng cấu trúc Why để trả lời câu hỏi này, giúp câu có độ phức cao mà lại không bị vấp! Chuyển sang câu sau nhé.”
Dùng cấu trúc khác hợp lệ (Khó only)	“DOL thấy em đã dùng một cấu trúc Why khác so với gợi ý, nhưng cũng rất hay nè. Chuyển sang câu mới nhé.”
Sai ngôn ngữ (cả 2 chế độ)	“Bạn hãy trả lời bằng tiếng Anh nhé. Thử nói lại câu này bằng tiếng Anh nha.”
Không bám cấu trúc gợi ý (Easy only)	“Câu này chưa bám cấu trúc gợi ý. Em hãy nói theo `[skeleton]` nhé.”
Lạc đề / từ điền sai (Easy only)	“Em đã bám đúng cấu trúc rồi, nhưng phần điền chưa khớp câu hỏi đang hỏi về `[chủ đề]`. Em thử nói lại nhé.”
Câu quá ngắn (cả 2 chế độ)	“Câu này còn hơi ngắn. Thêm ý để câu rõ hơn nhé.”
Cần gợi ý (Khó only)	“Đúng cấu trúc rồi nhé. Nhớ tập thêm để có thể phản xạ nhanh hơn mà không cần DOL nhắc vài từ đầu nhé! Câu tiếp theo nha.”
~~Phát âm dở~~	🔮 Future - chưa triển khai
~~Trong popup~~	🔮 Future - chưa triển khai

UI Message Catalog

Trường hợp	Message UI thân thiện	Hành vi
Chưa cấp mic	”Cho phép dùng micro để AI nghe bài nói của bạn nhé.”	Giữ ở check mic
Đang chờ AI teacher	”Đang chờ giáo viên”	Loading nhẹ
Đang nghe	”Đang lắng nghe bạn…”	Show waveform/listening indicator
Đang phân tích	”Đang phân tích…”	Disable next/skip trong giây ngắn
Nghe được transcript	Hiển thị câu AI nghe được trong input	Cho user thấy hệ thống nghe gì
Sai ngôn ngữ (cả 2 chế độ)	“Bạn hãy trả lời bằng tiếng Anh nhé.”	Yêu cầu nói lại
Không bám cấu trúc gợi ý (Easy only)	“Câu này chưa bám cấu trúc gợi ý. Em hãy nói theo `[skeleton]` nhé.”	Yêu cầu nói lại
Lạc đề / từ điền sai (Easy only)	“Em đã bám đúng cấu trúc rồi, nhưng phần điền chưa khớp câu hỏi.”	Yêu cầu nói lại
Câu quá ngắn (cả 2 chế độ)	“Câu này còn hơi ngắn. Thêm ý để câu rõ hơn nhé.”	Yêu cầu nói lại
Sai cấu trúc trong Khó	”Câu này chưa đúng cấu trúc mục tiêu. Em thử dùng option gợi ý hoặc cấu trúc Why khác nhé.”	Yêu cầu nói lại
Đúng ở mode Dễ	”Tuyệt vời, em đã hoàn thiện đúng cấu trúc này.”	Tự chuyển câu
Đúng ở mode Khó	”Tuyệt vời, em đã chọn đúng cấu trúc để trả lời.”	Active option nếu match
Option được active	Không cần message dài; option đổi state rõ ràng	Visual confirmation

Completion & Scoring

Per-sentence

Kết quả	Hiển thị	Hành vi tiếp
Đúng cấu trúc + đúng đề	Khung xanh, cấu trúc/vocabulary được fill rõ	Feedback ngắn → tự động chuyển câu tiếp
~~Đúng cấu trúc + phát âm dở~~	🔮 Future - chưa triển khai (pronunciation feature)	-
Đúng cấu trúc nhưng từ điền lạc đề (Easy only)	Khung amber + nhắc đề bài	Giữ câu hiện tại, yêu cầu nói lại
Không bám cấu trúc gợi ý (Easy only)	Khung đỏ + nhắc skeleton	Giữ câu hiện tại, yêu cầu nói lại
Match option ở chế độ Khó	Khung xanh + option chip active	Feedback ngắn → tự động chuyển câu tiếp
Cấu trúc khác hợp lệ (Khó only)	Load/ghi nhận cấu trúc mới + check phát âm	Theo trường hợp đúng hoặc phát âm dở
Cấu trúc không hợp lệ (Khó only)	Khung đỏ + nhắc dùng option hoặc cấu trúc Why khác	Giữ câu hiện tại, yêu cầu nói lại
Sai ngôn ngữ	Khung đỏ + nhắc trả lời bằng tiếng Anh	Giữ câu hiện tại, yêu cầu nói lại
Không nghe được / quá ngắn	Giữ khung đang luyện + message nhẹ	User nói lại, không tính hoàn thành

Session completion

Mỗi câu hỏi = 1 round. Xong → chuyển câu hỏi mới.
Kho đề: random câu hỏi Part 1, không giới hạn.
Tracking tối thiểu:
- số câu hoàn thành;
- difficulty_mode;
- narrator_language;
- số lần thử (attempt_count);
- có dùng hint/option không;
- có phải luyện phát âm không;
- lỗi cuối cùng nếu round chưa hoàn thành.

UI / Behavior

Layout

Khu vực	Nội dung
Trên	Câu hỏi Part 1, từ đầu bold đỏ; avatar/voice của AI teacher
Giữa - Dễ	Khung skeleton có blank, ví dụ `That will be ___`; transcript được fill vào blank sau khi nghe
Giữa - Khó	Khung trả lời trống + option chips bên dưới; option được active khi user dùng đúng
Feedback	Bubble của AI teacher: listening, analyzing, đúng/sai, retry
Dưới/Góc	Mode selector, narrator language, progress dots, quay về/bỏ qua

States - Chế độ Dễ

State	Khung trả lời
Waiting teacher	Hiện `Đang chờ giáo viên` trước khi TTS/câu hỏi sẵn sàng
Ready	Skeleton cấu trúc, mic sẵn sàng; CTA `Nói lại`/`Xong` chỉ hiện khi cần
Listening	Waveform + `Đang lắng nghe bạn...`; karaoke tô xanh real-time nếu match được từ
Analyzing	Transcript đã nghe được được fill vào khung; hiện `Đang phân tích...`
Correct	Khung xanh + feedback ngắn; tự động chuyển câu tiếp
Incorrect - Không bám cấu trúc	Khung đỏ + nhắc lại skeleton; giữ câu để user nói lại
Incorrect - Lạc đề / từ điền sai	Khung amber + chỉ ra phần điền chưa khớp đề; giữ skeleton, retry
Incorrect - Sai ngôn ngữ	Khung đỏ + “trả lời bằng tiếng Anh”; giữ câu để retry
Incorrect - Câu quá ngắn	Khung đỏ nhẹ + “thêm ý”; giữ câu để retry
~~Pronunciation issue~~	🔮 Future - chưa triển khai (popup Scene 4 reserved cho roadmap)
~~Re-speak after popup~~	🔮 Future - chưa triển khai

States - Chế độ Khó

State	Khung trả lời
Waiting teacher	Hiện `Đang chờ giáo viên` trước khi TTS/câu hỏi sẵn sàng
Ready	Input trống `Nói câu của bạn...` + option chips gợi ý cấu trúc
Silence > 2s	Nhấn mạnh option phù hợp hoặc hiện vài từ đầu; không ép user chọn
Listening	Waveform + transcript đang nghe nếu có
Analyzing	`Đang phân tích...`, giữ input ổn định
Correct + match option	Khung xanh + option chip active
Correct + alternate	Khung xanh; không active option, feedback nói user dùng cấu trúc khác hợp lệ
Incorrect	Khung đỏ + feedback cụ thể; giữ câu hiện tại để retry
~~Pronunciation issue~~	🔮 Future - chưa triển khai (popup Scene 4 reserved cho roadmap)

Design Cases & Guardrails

Case	UI/logic nên làm	Không nên làm
Chưa cấp mic	Chặn vào luyện, hướng dẫn cấp quyền mic	Cho vào màn nói rồi báo lỗi muộn
User chọn mode/language	Lưu lựa chọn; áp dụng ngay trước khi bắt đầu round	Reset giữa lúc đang nghe user nói
User đổi mode giữa round	Áp dụng từ câu tiếp theo hoặc hỏi xác nhận nếu cần reset	Đổi skeleton/option khi transcript đang phân tích
User nói tiếng Việt (cả 2 chế độ)	Feedback: `Bạn hãy trả lời bằng tiếng Anh nhé.`	Chấm sai chung chung
User nói quá ngắn (cả 2 chế độ)	Feedback: `Câu này còn hơi ngắn. Thêm ý để câu rõ hơn nhé.`	Tự suy diễn thành câu đúng
(Easy) User nói câu không bám skeleton	Khung đỏ + feedback nhắc lại skeleton, cho retry	Accept câu khác skeleton dù hợp lệ trong KB - đó là Mode Khó
(Easy) User bám đúng skeleton nhưng từ điền lạc đề	Khung amber + chỉ ra phần điền sai khớp đề bài, cho retry	Accept câu vô nghĩa dù bám skeleton đúng
(Khó) User dùng option đúng	Active option chip, khung xanh	Chỉ hiện text feedback mà không có xác nhận trực quan
(Khó) User dùng cấu trúc hợp lệ ngoài option	Accept, giải thích ngắn là cấu trúc khác vẫn đúng	Bắt dùng đúng option nếu câu vẫn hợp lệ
(Khó) User dùng cấu trúc không hợp lệ	Khung đỏ + nhắc dùng option hoặc cấu trúc Why khác	Mute reject mà không hint
AI đang phân tích	Giữ UI ổn định, disable chuyển câu trong thời gian ngắn	Cho user tạo nhiều trạng thái chồng nhau

Spec layout reserved cho roadmap. Hiện tại không có popup phát âm.

Khu vực	Nội dung
Background	Giao diện gốc mờ đi
Popup	Câu đã nói - mờ xám phần không thuộc cấu trúc
Focus	Từng từ/cụm phát âm dở, lần lượt
Dưới	Gemini voice cue + cue âm thanh “tinh tinh”

Lưu ý quan trọng từ Brief

Karaoke highlight (chế độ Dễ) là function quan trọng nhất - không được bỏ qua.
Mode Dễ scope rất hẹp: chỉ check (1) bám skeleton có sẵn, (2) từ điền có khớp đề. KHÔNG accept user dùng cấu trúc khác (kể cả hợp lệ trong KB).
Cơ chế đổi cấu trúc linh hoạt (§F3) CHỈ áp dụng Chế độ Khó - vì Khó không có skeleton, user tự chọn structure.
🔮 Pronunciation feedback / popup luyện phát âm - CHƯA TRIỂN KHAI ở phase hiện tại (cả 2 chế độ). Sẽ là roadmap future. Hiện tại không check phát âm sau câu nói; chuyển câu tiếp ngay khi pass các check khác (cấu trúc + đề bài + ngôn ngữ + độ dài).
Mode Dễ và Khó khác nhau ở scope check, không chỉ mức hỗ trợ:
- Dễ: bám skeleton + đúng đề (binary). Accept rất hẹp.
- Khó: dùng option, hoặc cấu trúc Why khác hợp lệ trong KB. Accept rộng hơn.
- Cả hai đều buộc user tự nói một câu hoàn chỉnh bằng tiếng Anh.
narrator_language không đổi ngôn ngữ câu trả lời; đây chỉ là ngôn ngữ hướng dẫn/feedback.

References

./PRA_EXAI_Speaking_00_Overview.md
./PRA_EXAI_Speaking_Knowledge_Base.md - Bảng sentence structures + word patterns theo loại câu hỏi
Brief: docs/Command/Resources/Documents/Exercise with AI 2026/Speaking/Brief - Speaking LMS New.pdf
Demo: https://speakasentence.dol.vn/

Change log

2026-04-26 (afternoon): Pronunciation feature deferred to roadmap (per user clarification: “ở dạng bài này cũng không có luyện phát âm luôn nhé. Chúng ta chưa làm tính năng này”). §F4 Pronunciation Feedback marked 🔮 FUTURE / chưa triển khai. Scene Flow Scene 4 marked future. User Actions Scene 2a row 5b “Đúng cấu trúc + phát âm dở” removed (now 5a “Đúng + đúng đề” → auto next). Scene 2b row 5d “Phát âm dở → Scene 4” marked future. AI Behavior Pronunciation section marked future. States Easy + States Khó “Pronunciation issue” + “Re-speak after popup” rows marked future. Completion & Scoring “phát âm dở” row marked future. Pronunciation Popup (Scene 4) layout section marked future-reserved. Gemini Voice Script + UI Message Catalog “phát âm dở” rows marked future. Lưu ý quan trọng updated to clarify pronunciation chưa làm.
2026-04-26 (morning): Phân định scope Easy vs Hard rõ ràng (correction từ user feedback Figma audit). §F1 Chế độ Dễ thêm bảng error sub-cases (không bám cấu trúc / lạc đề / sai ngôn ngữ / câu quá ngắn). §F3 “Đổi cấu trúc linh hoạt” scope về Hard mode only - vì Dễ không accept cấu trúc khác skeleton. Scene Flow 2a, User Actions 2a, AI Behavior table, Completion & Scoring, States table, Design Cases & Guardrails, Lưu ý quan trọng từ Brief - tất cả đều update để loại bỏ swap behavior khỏi Easy + thêm “lạc đề” case.
2026-04-24: Bổ sung flow chọn độ khó/ngôn ngữ narrator, skeleton fill ở mode Dễ, option chips ở mode Khó, transcript tracking, correct/incorrect states, active option, và guardrail cho các case thiết kế chính.
2026-04-21: Refresh Brief source path sau khi import tài liệu vào Speaking/.
2026-04-08: Rewrite theo Brief PDF - bổ sung 2 chế độ (Dễ/Khó), Scene Flow, Karaoke highlight, Pronunciation Popup (Scene 4), Gemini voice scripts, đổi cấu trúc linh hoạt.
2026-04-06: Rewrite - bổ sung Features, User Actions, AI Behavior, Completion & Scoring.
2026-04-06: Khởi tạo draft từ meeting note.