Tài liệu kỹ thuật: Linear Tool (Technical Proposal)

Bối cảnh & lý do

Linear Tool là dạng bài thứ hai trong nhóm Speaking có AI (Exercise AI), học viên mở từ “My Classes” theo từng khóa học. Khác với Dạng 1 — “Speak a Sentence”, nơi học viên nói từng câu rời — ở Linear Tool học viên dựng dàn ý cho câu trả lời trước, rồi mới luyện nói cả bài.

Bài vận hành quanh một sự phân vai rõ ràng: học viên lo phần ý, AI lo phần câu. Học viên cho từng ý ngắn bằng tiếng Việt; AI viết lại thành câu tiếng Anh hoàn chỉnh, rồi ghép cả dàn ý thành một đoạn nói mạch lạc để học viên luyện.

Bài không nhằm kiểm tra, mà để rèn cho học viên thói quen triển khai ý có cấu trúc (câu trả lời chính → nguyên nhân → hệ quả → mô tả) và sự tự tin nói trọn một đoạn. Vì vậy bài cố tình không chấm điểm số: sau mỗi lần nói, học viên chỉ nhận một mức xếp loại định tính (ví dụ “Good”) để tự định vị mình đang ở đâu — không có con số hay phần trăm.

✅ Đã chốt: không hiện điểm số — chỉ xếp loại định tính · không có độ khó · tối đa 4 ý chính mỗi bài · người soạn chỉ nhập câu hỏi gốc, phần còn lại AI sinh ngay lúc học viên làm bài · hoàn thành 1 câu = nói trọn cả bài 1 lần (xếp loại KHÔNG tính vào điều kiện hoàn thành) · luyện từng thẻ là tùy chọn · cả bài xong khi câu cuối cùng xong · chọn ngôn ngữ giáo viên ở đầu bài · BỐI CẢNH do AI sinh từ câu hỏi gốc · khi luyện nói cả bài, dàn ý bên trái ở chế độ chỉ-đọc.

Ai dùng & khi nào

• Người dùng: học viên trong một khóa học trên LMS.
• Khi nào: học viên tự luyện theo nhịp của mình. Một bài gồm nhiều câu hỏi làm lần lượt — thiết kế hiện để 15 câu, giao diện hiển thị tiến độ “Đã làm 3 / 15” cùng điều hướng “Câu trước” / “Câu [n]”. Mỗi câu là một vòng khép kín: dựng dàn ý → luyện nói → qua câu.

Ràng buộc — Không được làm / Ngoài phạm vi

Không được:

• Không hiện điểm số dạng con số hay phần trăm cho kết quả cuối của cả bài (bước 2b) — chỉ dừng ở mức xếp loại định tính (ví dụ “Điểm luyện nói: Good”). ✅ (Đã chốt 2026-07-02: quy tắc này KHÔNG áp dụng cho bước luyện từng câu lẻ — 2a — nơi thiết kế cho hiện điểm phần trăm làm phản hồi luyện tập; xem “Giai đoạn 2”.)
• Lỗi kỹ thuật không bao giờ được tính là một lần thất bại của học viên — mic trục trặc, hệ thống không nhận ra giọng, hay AI lỗi đều không làm học viên mất lượt.
• Không cho làm lại một bài đã hoàn thành.
• Không có khái niệm “Độ khó” ở dạng bài này.

Ngoài phạm vi:

• Ba dạng Speaking còn lại — mỗi dạng một PRD riêng trong nhóm “Exercise AI”.
• Màn soạn nội dung (data-entry) — đã có PRD riêng; tài liệu này chỉ nhắc đến dữ liệu mà bài cần.
• Lựa chọn mô hình AI, dịch vụ nhận diện giọng nói (STT), ngưỡng độ trễ, cách viết prompt, hợp đồng với backend — để lúc triển khai quyết.
• Lưu ý rủi ro: độ trễ, chi phí mỗi lượt gọi AI, và độ an toàn của câu AI sinh ra là phần mới hoàn toàn với sản phẩm — cần Eng đánh giá kỹ trước khi cam kết (xem “Những điểm cần chốt”).

Luồng làm bài

Bài chia làm hai giai đoạn, học viên chuyển qua lại bằng thanh điều hướng dưới đáy: “Lên ý tưởng” (dựng dàn ý) và “Luyện nói cả bài”. Trong đó, Giai đoạn 1 tự nó có một cổng chấm AI (dàn ý phải được AI xác nhận “đạt” trước khi khóa lại để luyện nói), và Giai đoạn 2 thực chất là hai bước nhỏ nối tiếp (luyện từng câu — tùy chọn — rồi luyện cả bài — bắt buộc). Sơ đồ dưới đây vẽ đầy đủ các bước đó; chi tiết từng bước ở các mục bên dưới.

Xếp loại định tính chỉ là phản hồi hiển thị sau khi nói — không nằm trong điều kiện rẽ nhánh “hợp lệ” ở trên; điều kiện hoàn thành chỉ là nói trọn bài một lần với bản ghi nghe được. ✅ Nhánh “Triển khai ý tưởng” là bước bắt buộc trước khi mở khóa luyện nói (đã chốt 2026-07-02) — sơ đồ trên phản ánh đúng thứ tự này.

Trước khi vào — chọn ngôn ngữ giáo viên + kiểm tra mic

Ở đầu bài, học viên chọn ngôn ngữ giáo viên AI (như Dạng 1 — luồng chung). Sau đó qua bước kiểm tra mic (dùng lại từ Dạng 1) để chắc thiết bị sẵn sàng trước khi bắt đầu.

💡 Chỉ test 1 lần. Theo ghi chú của designer trên Figma: hệ thống ghi nhớ theo học viên + dạng bài, nên lần sau vào lại dạng bài này thì không phải test mic lại nữa — không phải test mỗi lần mở bài. (Nguồn: ghi chú thiết kế, chưa phải yêu cầu PRD chính thức — nên xác nhận với PO trước khi triển khai.)

Ảnh chụp Figma (node 3743:183545).

Giai đoạn 1 — Dựng dàn ý

Mỗi câu mở ra với một thẻ câu trả lời chính — loại Answer (nhãn nền đỏ) — ở vị trí #1, nơi học viên đặt câu trả lời cốt lõi cho đề. Từ thẻ gốc này, học viên tỏa nhánh bằng các thẻ ý phát triển để làm dày lập luận; mỗi thẻ thuộc một trong ba loại:

Answer là thẻ gốc chứ không phải một loại ý để thêm — nên phần thống kê ở giai đoạn nói chỉ đếm ba loại phát triển (Description / Cause / Effect).

Ảnh chụp Figma (node 2798:43758) — khung này trong thiết kế gộp chung canvas với đoạn văn tổng hợp của Giai đoạn 2; lúc học viên mới bắt đầu, khung AI bên phải chỉ có khối BỐI CẢNH, chưa có đoạn văn/nhãn đếm.

Tạo một ý. Học viên gõ ý của mình bằng tiếng Việt, thật ngắn (ví dụ “rạp chiếu phim hiện đại”, “dễ ngủ hơn”) rồi bấm ✓ “Nhấn hoàn thành”. Ngay lúc đó AI viết lại ý thành một câu tiếng Anh hoàn chỉnh trên thẻ. Nếu học viên đổi loại của thẻ, AI viết lại câu cho khớp vai trò mới. Đây chính là trục chính của trải nghiệm — học viên chỉ cần nghĩ ý, câu chữ để AI lo.

Thêm nhánh mới — AI gợi ý hoặc tự viết. Bấm nút + mở bảng “Chọn Linear Tool phát triển” với hai tab: “AI gợi ý” (mặc định — AI đề xuất sẵn 3 thẻ mẫu, mỗi loại kèm câu ví dụ và câu hỏi gợi mở) và “Tự viết” (học viên tự gõ ý, không cần gợi ý). Nếu học viên gõ xong một thẻ rồi ngồi im ~4 giây chưa tạo nhánh tiếp, một tooltip nhắc xuất hiện: “Tạo nhánh linear — Tạo thêm nhánh mới để hoàn thiện bài trả lời của bạn theo Linear Thinking nhé.”

Ảnh chụp Figma (node 2700:41928). Tài liệu thiết kế còn nhắc một trạng thái thứ ba — “AI chưa load xong” — nhưng chưa tìm thấy khung hiển thị cụ thể; xem “Những điểm cần chốt”.

Ảnh chụp Figma (node 3101:100703).

Dàn ý lớn lên theo hai chiều:

• Chiều ngang là mạch lập luận chính — các ý lớn nối tiếp nhau, đánh số #1 → #2 → #3 → #4, thêm bằng nút + bên phải. Mạch này tối đa 4 ý; khi đủ 4, nút + khóa lại (biểu tượng ⊘) kèm lời nhắc “Đã đạt giới hạn nha, 4 nhánh là nhiều rồi.”
• Chiều dọc là đào sâu một ý — từ một ý chính mở rộng xuống thành ý con, đánh số #n.A → #n.B, thêm bằng nút + bên dưới.

Ảnh chụp Figma (node 3003:127620), tooltip khớp đúng chữ trong PRD.

✅ Đã chốt 2026-07-02 (PO): giới hạn là 4, đúng như khung khóa giới hạn ở trên. Khung “Full sample” trong cùng file Figma (node 3766:188679), vẽ 5 thẻ chính, là khung tham chiếu cũ/lỗi thời — không dùng làm chuẩn.

Chặn tạo thêm nhánh khi có lỗi chưa sửa — khác với giới hạn 4 nhánh. Ngay cả khi chưa chạm giới hạn 4, nếu một nhánh phía trước bị AI đánh giá lỗi (xem “Triển khai ý tưởng” bên dưới) mà học viên chưa sửa, nút + để tạo nhánh mới cũng khóa lại cho tới khi nhánh lỗi đó được xử lý xong.

Ảnh chụp Figma (node 2830:64523).

Sửa và xóa. Bấm vào một thẻ để mở bảng “Đổi tool hoặc xóa nhánh” — đổi loại ý, hoặc xóa nhánh. Lưu ý quan hệ cha–con: xóa thẻ cha sẽ mất theo cả nhánh con bên dưới; xóa thẻ con thì chỉ mất đúng thẻ đó. Cả hai thao tác đều có xác nhận riêng: xóa nhánh hỏi “Xóa nhánh này? — Thao tác sẽ xóa cả nhánh con của nó. Không thể hoàn tác.”; đổi loại hỏi “Bạn sẽ bị mất nội dung của nhánh hiện tại.” (Nguồn hai câu xác nhận: ghi chú thiết kế “Note các trường hợp tạo nhánh”, node 3098:99563 — xem toàn bộ chu trình nút bấm bên dưới.)

Ảnh chụp Figma (node 2598:23368) — bảng thực tế là danh sách chọn kiểu radio cho cả 3 loại (Description/Cause/Effect), loại hiện tại được đánh dấu, cộng nút “Xóa nhánh” riêng màu đỏ.

Hỗ trợ trên canvas. Thanh công cụ nổi có 4 nút: Thu nhỏ, Xem đầy đủ, Toàn màn hình, và “Fit to screen” ✅ (đã chốt 2026-07-02) — zoom vừa khít để cả dàn ý hiện trọn trong khung nhìn.

Khung AI bên phải không chỉ là một khối tóm tắt tĩnh — nó là cả một khu làm việc “Triển khai ý tưởng”, mở đầu bằng khối “BỐI CẢNH” (tóm tắt chủ đề bài nói, ví dụ “Bài nói về việc người dân thành phố đi xem phim vào cuối tuần…”). Khi học viên chưa nhập gì, khung chờ với dòng “Tiếp tục chờ ý tưởng của bạn…”.

Triển khai ý tưởng — AI chấm dàn ý theo phiên bản

⚠️ Toàn bộ mục này được phát hiện khi rà lại thiết kế Figma sau bản PRD đầu — trước đó tài liệu chỉ mô tả khung này là “hiển thị BỐI CẢNH”. Thực tế đây là một cơ chế lớn hơn nhiều — có giới hạn lượt dùng, một cổng chấm AI, và lịch sử phiên bản — cần PO/Eng xác nhận phạm vi trước khi triển khai; xem thêm “Những điểm cần chốt”.

Sau khi có ít nhất một ý trên canvas, nút “Triển khai ý tưởng (n)” (n = số lượt còn lại) sáng lên — trước đó bị khóa với tooltip “Bạn cần có ít nhất một idea để có thể triển khai.”

Ảnh chụp Figma (node 4829:506150).

Bấm vào nút mở modal xác nhận: “Xác nhận triển khai ý tưởng — Bạn muốn dùng một lượt triển khai ý tưởng?” (Huỷ / Xác nhận). Khi lượt còn lại thấp, một nhãn cảnh báo riêng hiện thêm cạnh nhãn phiên bản — ví dụ “Chỉ còn 3 lần” bên cạnh “Version 2”.

✅ Đã chốt 2026-07-02: lượt chỉ bị trừ khi AI chấm “Đã đạt” — lúc đó ý được tạo thành thẻ và học viên qua bước tiếp theo. Nếu AI chấm “CHƯA ĐẠT”, hệ thống chỉ hiện feedback lỗi để sửa — KHÔNG trừ lượt. Học viên có thể sửa và bấm “Triển khai ý tưởng” lại bao nhiêu lần tùy ý cho tới khi đạt, chỉ lần đạt mới tính vào số lượt đã dùng.

Ảnh chụp Figma (node 4863:116931). Modal tương tự cho “Tiếp tục phát triển ý” (node 4829:517288) có lỗi đánh máy trong Figma (“Tiếp tục triển trai ý tưởng”) — không phải chữ chính thức, chỉ nêu để designer sửa.

Ảnh chụp Figma (node 4829:524192).

Sau khi AI chấm xong, khung hiện một trong hai kết quả:

Ảnh chụp Figma (node 4829:509811).

Ảnh chụp Figma (node 4829:514978).

✅ Đã chốt 2026-07-02 (PO): chữ feedback lỗi (cả nội dung trên thẻ lẫn nhãn góc thẻ) do AI sinh động lúc chạy, backend trả về nguyên văn — FE chỉ hiển thị y nguyên, KHÔNG cần enum/whitelist cố định ở phía FE. Bảng dưới đây là ví dụ minh họa lấy từ tài liệu spec của designer, không phải danh sách phải cứng vào code; số lượng và chữ chính xác sẽ khác nhau theo từng trường hợp AI sinh ra.

Tài liệu spec của designer liệt kê một số ví dụ loại lỗi, mỗi loại kèm điều kiện, chữ mẫu hiển thị trên thẻ, và nhãn góc thẻ mẫu — ghi rõ danh sách này còn dang dở (“Bàn cùng designer hoàn thiện thêm (Nếu cần)”, kèm link một wiki ngoài Figma mà tài liệu này không truy cập được), nhưng theo quyết định ở trên, việc “hoàn thiện danh sách” không còn là việc FE cần chờ — đây chỉ là ví dụ để hình dung, không phải spec cần implement cứng:

Ảnh chụp Figma (node 3098:101552).

✅ Hai điểm từng tưởng là “lệch chữ giữa spec và khung thiết kế thực tế” — (1) chữ trên thẻ thực tế cho lỗi “quá ngắn” khác chữ trong bảng ví dụ ở trên; (2) nhãn “LẠC ĐỀ” trên canvas khác tên với “Chưa sát đề” trong bảng ví dụ — không còn là vấn đề cần chốt nữa: vì chữ do AI sinh động, hai khung Figma này vốn chỉ là hai lần sinh chữ khác nhau cho cùng một loại lỗi, không phải một bản chữ “sai” cần sửa.

Ảnh chụp Figma — minh họa điểm lệch nhãn (2) ở trên.

Phiên bản (Version) và quay lại bản cũ. ✅ Đã chốt 2026-07-02 (PO): ở lần “Triển khai ý tưởng” đầu tiên đạt, khung CHƯA hiện nhãn phiên bản nào — chưa có gì để phân biệt. Khái niệm phiên bản chỉ xuất hiện khi học viên bấm nút sửa (“Tiếp tục phát triển ý”) để quay lại chỉnh dàn ý sau khi đã có một bản đạt: lúc đó hệ thống đánh dấu bản trước là “Version 1”, và bản đang chỉnh trở thành “Version 2”. Từ Version 2 trở đi, học viên mở được danh sách phiên bản (Version 1–6 trong ảnh thiết kế) và quay lại xem/dùng một bản cũ (nút “Về version 3”).

Ảnh chụp Figma (node 4829:525855).

Khóa phiên bản khi bắt đầu luyện nói. Khi học viên bấm “Luyện nói cả bài” từ một phiên bản đã đạt, hệ thống hỏi xác nhận: “Bạn sẽ không được sửa idea khi bắt đầu ‘luyện nói cả bài’. Bạn chắc chắn muốn luyện nói version 1?” — phiên bản dùng để luyện nói sẽ bị khóa lại, không sửa được nữa. Đây chính là cơ chế đứng sau quy tắc đã chốt “dàn ý bên trái ở chế độ chỉ-đọc khi luyện nói cả bài”.

Ảnh chụp Figma (node 4829:528890).

Giai đoạn 2 — Luyện nói (2 bước nối tiếp)

⚠️ Phát hiện khi rà lại Figma: bản PRD đầu mô tả Giai đoạn 2 như một bước duy nhất (“luyện nói cả bài”). Thực tế thiết kế chia rõ hai bước nối tiếp — luyện từng câu (tùy chọn) trước, luyện cả bài (bắt buộc) sau — mỗi bước có màn hình, cách chấm, và loại kết quả khác nhau. Cập nhật lại dưới đây.

Một khi phiên bản dàn ý đã đạt và bị khóa lại (xem “Triển khai ý tưởng” ở trên), học viên chuyển sang luyện nói.

2a. Luyện nói từng câu (tùy chọn)

Mỗi thẻ ý trên dàn ý có thể luyện nói riêng lẻ trước khi ghép cả đoạn: bấm vào thẻ → ghi âm câu đó → hệ thống chấm và trả về điểm phần trăm (ví dụ “60%”) kèm tô màu sửa lỗi ngay trên câu (chỗ phát âm chưa chuẩn), cùng hai lựa chọn “Nghe lại” / “Luyện lại”.

Ảnh chụp Figma (node 3092:104457).

Ghi chú thiết kế mô tả đầy đủ chu trình một thẻ: Mặc định → Hover → Focus → Đang ghi âm → Đang chấm → Kết quả — xem ảnh chụp toàn bộ chu trình bên dưới.

Ảnh chụp Figma (node 3084:97776).

Điểm phần trăm ở bước này KHÔNG mâu thuẫn với quy tắc “không chấm điểm.” ✅ Đã chốt 2026-07-02 (PO): quy tắc “không hiện điểm số dạng con số hay phần trăm” chỉ áp dụng cho kết quả cuối của cả bài (bước 2b) — điểm phần trăm ở bước luyện từng câu (2a) đứng ngoài phạm vi quy tắc này, dùng làm phản hồi luyện tập, không phải kết quả cuối.

Khi rê chuột vào một đoạn được tô màu trong đoạn văn tổng hợp (bước 2b), tooltip hiện tên loại ý của đoạn đó (Cause/Description/Effect).

2b. Luyện nói cả bài (bắt buộc)

Khi dàn ý đã có nội dung, AI ghép câu tiếng Anh của tất cả các thẻ thành một đoạn văn hoàn chỉnh, mỗi phần được tô màu theo loại ý mà nó bắt nguồn — để học viên nhìn ra mạch bài mình vừa dựng. Đầu khung có các nhãn đếm số ý từng loại (ví dụ “DESCRIPTION: 2 · CAUSE: 3 · EFFECT: 3”).

Ảnh chụp Figma, khung tên gốc “Luyện nói cả bài” (node 2798:43758) — cùng khung với ảnh canvas ở Giai đoạn 1, nay đã có đoạn văn + nhãn đếm + dải nhắc điều kiện hoàn thành màu vàng.

🔒 Ở bước này, dàn ý bên trái ở chế độ chỉ-đọc (PO chốt) — vì phiên bản đã bị khóa lại khi bắt đầu luyện nói (xem modal khóa phiên bản ở trên). Muốn chỉnh ý, học viên quay lại “Lên ý tưởng” — nhưng lưu ý điều đó có thể đồng nghĩa tạo một phiên bản mới, cần chạy lại “Triển khai ý tưởng”.

Từ đây học viên luyện nói cả đoạn, ghi âm một lượt liên tục (khác bước 2a — ghi từng câu):

• “Luyện nói” (nút chính, biểu tượng mic) — ghi âm cả bài.
• “Nghe mẫu” (nút phụ, biểu tượng loa) — nghe máy đọc mẫu đoạn văn bằng giọng đọc tự động, có thanh tiến trình phát.

Ảnh chụp Figma (node 2827:311744).

Trước khi nói lần đầu, một dải nhắc màu vàng cho học viên biết điều kiện hoàn thành: “Bạn cần luyện nói đầy đủ câu trả lời để hoàn thành bài tập này.”

Trong lúc nói, giao diện hiện sóng âm và nút dừng; nói xong, hệ thống xử lý một chút rồi trả kết quả: một mức xếp loại định tính — “Điểm luyện nói: Good” (các bậc định tính, không phải con số — khác hẳn điểm phần trăm của bước 2a), kèm hai lựa chọn “Nghe lại” và “Nói lại”. Màn kết quả cũng hiện điều hướng đa câu (”← Câu trước” / “Câu N →” cùng “Đã làm n/tổng”).

Ảnh chụp Figma (node 2827:319587).

Nút “Tiếp tục phát triển ý” đưa học viên quay về canvas để chỉnh dàn ý.

Khi nào một câu — và cả bài — được tính là xong

Một câu hoàn thành khi học viên đã dựng dàn ý và được AI xác nhận “Đã đạt” (qua “Triển khai ý tưởng” — bắt buộc, đã chốt 2026-07-02) và nói trọn cả bài ít nhất một lần (bước 2b) với bản ghi hợp lệ (đủ dài, nghe được). Chỉ cần nói trọn bài một lần là câu được tính xong — xếp loại định tính KHÔNG nằm trong điều kiện hoàn thành: nó chỉ là phản hồi hiển thị sau khi nói, không có ngưỡng chất lượng nào chặn việc qua câu. Hoàn thành câu hiện tại mới mở khóa câu kế; lúc đó hệ thống mời: “Bạn có thể làm câu tiếp theo, hoặc tiếp tục luyện tập câu hỏi hiện tại.”

Luyện từng câu lẻ (bước 2a) là TÙY CHỌN — một cách chuẩn bị, không bắt buộc; điều kiện qua câu chỉ là nói trọn cả bài một lần ở bước 2b. Học viên được nói lại bao nhiêu lần tùy thích.

Cả bài hoàn thành khi câu cuối cùng hoàn thành.

Khi ghi âm trục trặc

Tinh thần xuyên suốt: trục trặc kỹ thuật không bao giờ làm học viên mất lượt.

Ảnh chụp Figma (node 3006:156660) — đây là khung tài liệu hoá kèm chú thích dev, phần canvas bên trái trong khung chỉ là ô xám placeholder chứ chưa phải canvas dàn ý thật.

✅ Đã chốt 2026-07-02: needs_retry chỉ áp dụng cho bước 2b (luyện cả bài) — KHÔNG áp dụng cho bước 2a (luyện từng câu).

Màn kết thúc

Khi câu cuối hoàn thành, hiện màn kết thúc — tiêu đề “Chúc mừng bạn làm xong bài tập!” — với 3 thẻ chỉ số nỗ lực (không có điểm số chất lượng):

Ảnh chụp Figma (node 3081:96330).

Kèm hai nút “Về trang chủ” và “Làm tiếp”, phần “N HV đã làm” (social proof), và thanh điều hướng câu hỏi vẫn ở chân màn. (Số liệu trên thiết kế là dữ liệu mẫu — spec mô tả ý nghĩa từng chỉ số, không phải con số cụ thể.)

Tiêu chí nghiệm thu

• Đầu bài có bước kiểm tra mic; bài không bắt đầu nếu mic chưa sẵn sàng. Lần sau vào lại dạng bài này (cùng học viên) không phải test mic lại.
• Canvas mở ra với thẻ Answer (đỏ) ở vị trí #1; cho thêm thẻ phát triển Description / Cause / Effect đúng màu nhãn.
• Học viên gõ ý ngắn tiếng Việt, bấm “Nhấn hoàn thành” → AI sinh câu tiếng Anh cho thẻ đó.
• Bấm + mở bảng chọn cách phát triển nhánh mới với 2 tab “AI gợi ý” (mặc định) / “Tự viết”; ngồi im ~4s sau khi điền thẻ → hiện tooltip nhắc tạo nhánh.
• Đổi loại của một thẻ → AI viết lại câu theo loại mới; xác nhận mất nội dung nhánh hiện tại trước khi đổi.
• Mạch ngang chặn ở 4 ý: nút + khóa (⊘) và hiện nhắc “Đã đạt giới hạn nha, 4 nhánh là nhiều rồi.”
• Nút + cũng khóa (khác lý do trên) khi một nhánh phía trước còn lỗi AI chưa sửa.
• Thêm được ý con theo chiều dọc, đánh số đúng (#n.A, #n.B).
• Xóa thẻ cha mất cả nhánh con; xóa thẻ con chỉ mất đúng thẻ đó; có xác nhận “Không thể hoàn tác” trước khi xóa.
• Khung AI hiện khối “BỐI CẢNH”; khi chưa có ý, hiện dòng chờ “Tiếp tục chờ ý tưởng của bạn…”.
• Nút “Triển khai ý tưởng (n)” khóa khi chưa có ý nào; mở khóa + hiện số lượt còn lại khi đã có ít nhất 1 ý.
• Bấm “Triển khai ý tưởng” → modal xác nhận → AI chấm → hiện “Đã đạt” (trừ 1 lượt, mở khóa Luyện nói cả bài) hoặc “CHƯA ĐẠT” (không trừ lượt, chỉ có “Sửa lại ý”, kèm feedback trên từng thẻ lỗi).
• Sửa ý theo feedback và bấm “Triển khai ý tưởng” lại sau khi “CHƯA ĐẠT” → không bị trừ thêm lượt nào cho tới khi đạt.
• Lượt “Triển khai ý tưởng” còn thấp → hiện nhãn cảnh báo dạng “Chỉ còn N lần”.
• Lần “Triển khai ý tưởng” đạt đầu tiên KHÔNG hiện nhãn version; bấm nút sửa (“Tiếp tục phát triển ý”) sau đó mới bắt đầu đánh số Version 1, 2, 3…
• Có lịch sử phiên bản (Version N) xem/chọn lại được (từ Version 2 trở đi); mỗi phiên bản gắn nhãn đạt/chưa đạt.
• Bắt đầu “Luyện nói cả bài” từ một phiên bản đã đạt → modal xác nhận khóa phiên bản đó lại (không sửa được idea nữa).
• 2a — Luyện nói từng câu (tùy chọn): luyện một thẻ riêng → trả điểm phần trăm + tô màu sửa lỗi + “Nghe lại”/“Luyện lại”.
• 2b — Luyện nói cả bài: đoạn văn ghép từ tất cả các thẻ, tô màu đúng loại ý; nhãn đếm đúng ba loại phát triển; ghi âm một lượt liên tục (khác 2a).
• “Nghe mẫu” phát giọng đọc tự động; “Luyện nói” bắt đầu ghi âm; có dải nhắc điều kiện hoàn thành trước khi nói lần đầu.
• Nói xong cả bài (bản ghi hợp lệ) → hiện xếp loại định tính (“Điểm luyện nói: …”), không có con số hay phần trăm, kèm “Nghe lại” / “Nói lại”.
• Tab/nút “Luyện nói cả bài” không mở được cho tới khi “Triển khai ý tưởng” trả về “Đã đạt” — không có đường tắt nào khác vào 2b.
• Nói trọn cả bài một lần (bản ghi hợp lệ, bước 2b, sau khi đã “Đã đạt”) → câu được tính xong và mở khóa câu kế, bất kể xếp loại; luyện từng câu ở 2a KHÔNG bắt buộc.
• Cả bài tính hoàn thành khi câu cuối cùng hoàn thành.
• “Tiếp tục phát triển ý” đưa học viên về đúng canvas dàn ý đang dựng.
• Giao diện hiện tiến độ “Đã làm n / tổng” và điều hướng giữa các câu.
• Trạng thái “Cần nói lại” hiện đúng nội dung, không trừ lượt; nút “Thử lại” hoạt động.
• Mọi trục trặc kỹ thuật (mic / nhận diện giọng / AI) không làm học viên mất tiến độ.
• Đầu bài có bước chọn ngôn ngữ giáo viên.
• Khi luyện nói cả bài, dàn ý bên trái ở chế độ chỉ-đọc; muốn sửa phải quay lại “Lên ý tưởng”.
• Màn kết thúc hiện 3 thẻ (ĐÃ HOÀN THÀNH / AI HỖ TRỢ / LUYỆN NÓI %) + “Về trang chủ” / “Làm tiếp”; LUYỆN NÓI % là chỉ số độ phủ, không phải điểm chất lượng.

Dữ liệu & đầu vào

Người soạn chỉ nhập câu hỏi gốc cho mỗi câu (soạn ở công cụ data-entry riêng — có PRD riêng).

Mọi thứ còn lại do AI sinh ngay lúc học viên làm bài, không soạn trước:

• Câu tiếng Anh cho từng thẻ — viết từ ý ngắn tiếng Việt học viên nhập.
• Đoạn văn tổng hợp — ghép câu của tất cả các thẻ thành một bài nói hoàn chỉnh.
• Giọng đọc mẫu (“Nghe mẫu”) — máy đọc tự động đoạn văn tổng hợp.
• Xếp loại định tính — AI đánh giá sau khi học viên nói.
• BỐI CẢNH — đoạn tóm tắt chủ đề bài nói, do AI sinh từ câu hỏi gốc lúc chạy (không phải một trường người soạn nhập riêng).

Các giá trị do hệ thống/Eng đặt:

• Số ý chính tối đa: 4 ✅ (đã chốt theo thiết kế; khung “Full sample” 5-nhánh là tham chiếu lỗi thời, không dùng).
• “Dựng xong dàn ý” không dựa trên số thẻ tối thiểu cố định — AI đánh giá ý đã đủ hay chưa lúc chạy; cổng kiểm tra này nằm ở backend, không phải hằng số phía FE. Cụ thể hơn: cổng này chính là kết quả “Đã đạt / CHƯA ĐẠT” của bước “Triển khai ý tưởng” (xem Giai đoạn 1).
• Điều kiện yêu cầu nói lại: khi ghi dưới ~2 giây hoặc im lặng quá ~5 giây (tạm theo thiết kế, Eng rà lại).
• Cách trừ lượt “Triển khai ý tưởng” ✅ (đã chốt 2026-07-02): chỉ trừ lượt khi AI chấm “Đã đạt”; chấm “CHƯA ĐẠT” không trừ lượt, học viên sửa và thử lại tự do. Phạm vi lượt ✅ (đã chốt): tính theo từng câu — mỗi câu trong số 15 câu có lượt riêng, không dùng chung một kho cho cả bài. Tổng số lượt mỗi câu ✅ (đã chốt): 10 lượt, cảnh báo khi còn 3. Hành vi khi hết lượt mà vẫn CHƯA ĐẠT vẫn còn để mở — xem “Những điểm cần chốt”.
• Chữ feedback lỗi AI chấm ✅ (đã chốt 2026-07-02): do AI sinh động, backend trả nguyên văn — FE không cần enum/whitelist cố định, chỉ hiển thị lại. Các loại lỗi ví dụ (Ý hơi lạc đề / Ý quá ngắn / Ý quá mơ hồ / nhầm loại thẻ / Effect chưa ra hệ quả — xem bảng ở Giai đoạn 1) chỉ để hình dung, không phải danh sách implement cứng.

Đề xuất khác thiết kế — Hiển thị phản hồi sau khi nói

💡 Phần này tài liệu cố ý đề xuất khác thiết kế gốc. Cách làm: triển khai theo đề xuất trước → demo → đối chiếu trực tiếp với thiết kế → PO/designer quyết định.

Thiết kế gốc đang làm gì: sau khi học viên nói cả bài, hệ thống so khớp lời nói với đoạn văn mục tiêu rồi tô xanh những từ khớp được (từ không khớp để màu đen).

Vì sao nên cân nhắc lại:

• Cách này trộn lẫn hai chuyện khác hẳn nhau — học viên có nói ra từ đó không với nói có chuẩn không. Học viên rất dễ hiểu nhầm “xanh = phát âm tốt”.
• Từ màu đen không kèm lời giải thích, học viên không biết mình sai ở đâu hay phải làm gì.
• Màu xanh lại trùng với màu của loại ý Description — gây rối thị giác.
• Khi đã có một xếp loại tổng định tính, tô màu từng từ thành ra chi tiết thừa.
• Việc nhận diện giọng vốn là tín hiệu yếu: học viên nói chuẩn vẫn có thể bị tô đen chỉ vì máy nghe nhầm.

Đề xuất (làm trước): bỏ tô màu từng từ; giữ lại xếp loại định tính (“Điểm luyện nói: …”) cùng hai nút “Nghe lại” / “Nói lại”. Nhẹ nhàng, không bắt học viên giải mã màu sắc, đúng tinh thần luyện-tập-không-điểm-số.

Nâng cấp về sau (nếu cần phản hồi cụ thể hơn): để đoạn văn trung tính, chỉ đánh dấu nhẹ vài chỗ máy chưa nghe rõ kèm một câu thân thiện — “Mình chưa nghe rõ mấy chỗ này, thử lại nhé” — diễn đạt là “chưa nghe rõ”, không phải “sai”.

Những điểm cần chốt

⚠️ Các quyết định còn mở, kèm người phụ trách:

Đã chốt 2026-06-30 (đã cập nhật ở các phần trên): số thẻ tối thiểu → AI đánh giá lúc chạy (BE) · nguồn BỐI CẢNH → AI sinh · chọn ngôn ngữ giáo viên ở đầu bài · trạng thái stale → dàn ý chỉ-đọc khi luyện nói · màn kết thúc → 3 thẻ chỉ số nỗ lực.

Đã chốt 2026-07-02 (đã cập nhật ở các phần trên): nút thứ tư trên thanh công cụ canvas → “Fit to screen” (zoom vừa khít cả dàn ý) · giới hạn nhánh → 4 là chuẩn, khung “Full sample” 5-nhánh là tham chiếu lỗi thời.

• Khả thi phần AI lúc chạy — trong một phiên làm bài, AI phải viết câu cho từng ý, ghép đoạn văn, nhận diện giọng nói và trả xếp loại. Cần đánh giá độ trễ, chi phí mỗi lượt và độ an toàn của câu AI sinh trước khi cam kết phạm vi. (Eng — quan trọng)
• Đề xuất bỏ tô màu từng từ — chờ demo và đối chiếu thiết kế gốc rồi quyết. (PO/designer)
• Vị trí trong My Classes — đường dẫn cuối cùng của bài. (Eng)

Phát hiện thêm 2026-07-02 khi rà lại toàn bộ section “Linear tool” trên Figma — cơ chế “Triển khai ý tưởng” (AI chấm dàn ý + versioning + rate limit) và việc Giai đoạn 2 thực chất có 2 bước nhỏ trước đó hoàn toàn chưa có trong bản PRD đầu. Các câu hỏi mở dưới đây là hệ quả trực tiếp:

Đã chốt 2026-07-02 (đã cập nhật ở các phần trên): cách trừ lượt — chỉ trừ khi AI chấm “Đã đạt” (tạo ý + qua bước tiếp theo), “CHƯA ĐẠT” không trừ lượt, thử lại tự do · phạm vi quy tắc “không chấm điểm số/phần trăm” — chỉ áp dụng cho kết quả cuối cả bài (2b), KHÔNG áp dụng cho điểm phần trăm ở bước luyện từng câu (2a) · needs_retry — chỉ áp dụng cho bước 2b, không áp dụng cho 2a · “Triển khai ý tưởng” là bước bắt buộc trước khi mở khóa “Luyện nói cả bài” — không có đường tắt khác vào 2b · quy tắc tạo phiên bản — lần đạt đầu tiên KHÔNG có nhãn version; bấm nút sửa (“Tiếp tục phát triển ý”) sau đó mới bắt đầu đánh số Version 1, 2, 3… · phạm vi lượt — tính theo từng câu, không dùng chung cho cả bài · chữ feedback lỗi AI — do AI sinh động, BE trả nguyên văn, FE không cần enum cố định (giải quyết luôn hai chỗ “lệch chữ” từng nêu — chỉ là hai lần sinh chữ khác nhau, không phải lỗi cần sửa).

Đã chốt 2026-07-02: tổng số lượt “Triển khai ý tưởng” mỗi câu = 10 (giữ nguyên số liệu trên thiết kế), cảnh báo khi còn 3 lần.

• Học viên hết lượt mà vẫn CHƯA ĐẠT thì sao? — chưa có hướng giải quyết (kẹt lại / tự động cho qua / có cơ chế cấp thêm lượt nào đó). (Eng/PO — quan trọng)
• Trạng thái “AI chưa load xong” của bảng chọn nhánh mới (tab thứ 3 cạnh “AI gợi ý” / “Tự viết”) — có ghi trong tài liệu chú thích nhưng chưa tìm thấy khung thiết kế thực tế thể hiện trạng thái này. (designer — để nguyên, chưa cần rượt tiếp)

Thiết kế tham chiếu

• Figma là nguồn chuẩn (cập nhật khi thiết kế đổi): mở section “Linear tool”.
• Tài liệu kỹ thuật bổ trợ: Exercise AI — Linear Tool (Technical Proposal).
• Tệp Figma đầy đủ: Exercise with AI — Exercise 2026.

Node-id các khung chính (gắn 2026-07-02, xác nhận bằng ảnh chụp — xem ảnh minh họa trong từng phần ở trên; đợt rà soát thứ hai cùng ngày bổ sung toàn bộ nhóm “Triển khai ý tưởng” + 2a/2b sau khi phát hiện đợt đầu bỏ sót):

Sweep 2026-07-02 chỉ mới đi hết các frame cấp cao nhất (top-level) trong section “Linear tool” (82 frame con của node 2577:23259) — chưa drill sâu vào từng popover/dropdown lồng bên trong. Nếu cần đối chiếu chi tiết hơn khi triển khai, nên rà lại trực tiếp trên Figma thay vì chỉ dựa bảng này.