Vocabulary - Logic

Purpose

• Xác định phạm vi, nguyên tắc và luồng hoạt động của Sổ từ vựng: lưu/ôn/tiến độ, quản lý list, chia sẻ cộng đồng (đã duyệt), và các ràng buộc UI.

Principles

• Tối giản: giảm cognitive load, ưu tiên resume theo policy.
• Tự chủ: không deadline cứng; user học khi muốn.
• Phản hồi rõ: mini-stats theo 3 bucket (Chưa học/Đang ôn/Thành thạo), streak, weekly goal.
• An toàn: kiểm duyệt khi chia sẻ công khai.

Người dùng & mục tiêu

• Đối tượng: tất cả người dùng đã đăng nhập trên nền tảng DOL Academy.
• Mục tiêu: xem các item/kiến thức đã lưu và có nơi để học lại; cung cấp tính năng học tập nhằm tạo thói quen quay lại (chi tiết phương pháp học sẽ bàn riêng).

Phạm vi

• Đa môn: quản lý item/kiến thức theo chương trình/môn (IELTS, SAT, Math, Physics, Chemistry…).

• List-centric: trung tâm là List; không cho phép chuyển item giữa các List.

• AI generation + moderation: tạo list bằng AI, auto-moderation trước khi chia sẻ public.

• Không có deadline cứng cho việc học; user học khi muốn. Gợi ý theo chính sách của List (policy-based), không ép hạn.

• Học theo phiên: mặc định gợi ý ~15 phút/phiên (configurable; cho phép bật/tắt giới hạn thời gian); user có thể bấm “Bắt đầu học” nhiều lần trong ngày.

• List Groups: nhóm đặt tên, trộn list hệ thống và list tự tạo (tích hợp trong My Lists).

• Xoá List → Archived (khôi phục được).

• Hiển thị tiến độ học ở trang danh sách và chi tiết List.

• Trình bày UI cụ thể sẽ quyết định sau.

• Weekly Goal: cho phép đặt mục tiêu số item/kiến thức mỗi tuần; hệ thống track số item review đúng trong tuần.

• Monetization: hiển thị rõ credit AI còn lại, trạng thái gói all-in-one, và gợi ý mua credit/gói khi cần.

Kiến trúc thông tin

• Thực thể tối thiểu
  • KnowledgeItem: id, type, subject, meaning/explanation, createdAt.
  • List: owner, visibility (private/shared/public), subject, language?, sourceType (user|system|practice_suggested), editable (true nếu user tạo), moderationStatus, status (active|archived), itemMovePolicy: no-move-between-lists.
  • ListGroup: nhóm đặt tên chứa nhiều List (mix system/user).
  • UserItemState: F, D, successCount, failCount, learnedAt, lastReviewedAt; mức 6 bậc Hạt giống → Nở Hoa compute từ F_now.
  • ProgressSnapshot: tổng số, chưa học, đang ôn, thành thạo (per-List).
  • WeeklyGoal: { targetPerWeek: number, completedThisWeek: number, weekStartISO: string }
  • CreditLedger: { profileId, balance, history[{ id, action: “consume”|“grant”|“refund”, amount, feature, listId?, createdAt, operator }] }
  • SubscriptionStatus: { profileId, isAllInOneActive, expiryDate, includedPrograms[] }
• Bề mặt
  • List (mini-stats), Item Detail (stats), Review Queue.
  • AI Generate, Moderation Queue.
  • Archived Lists (ít ưu tiên trong UI), List Groups.
  • Progress Overview (Progress Lite) thay thế bản chi tiết; tập trung counters/achievements đơn giản.
  • Vocabulary Streak: heatmap theo ngày + current/best streak + lịch sử reset.
  • Home sections: Header, Subnav, Action Hub, My Lists (Control Bar: Search/Create/Group filter/Subject Tabbar; hỗ trợ List/Group view, bucket “Ungrouped”, nhớ trạng thái collapse/expand từng group), Community Highlights, Progress Overview (global + per-subject + in-progress + mini chart + Year Heatmap với bộ lọc năm), Archived, Streak (tuỳ chọn).
  • Layout: max width 1144px, center; responsive theo DOL DS.

Quy tắc

• Không chuyển item giữa các List.

• Xoá List → chuyển vào Archived; có thể Restore.

• ListGroup: tạo/đổi tên/xoá trong My Lists; xoá group không xoá list (list sang “Ungrouped”); nhớ trạng thái group mở/đóng.

• Chia sẻ public phải qua auto-moderation (có thể bổ sung duyệt thủ công).

• Ôn tập theo phiên auto (SRS): hệ thống tự chọn item để ôn/học mới dựa trên trạng thái nhớ (spaced repetition), không yêu cầu user chọn loại phiên.

• Một List = 1 môn (subject); 1 Item theo đúng format của môn đó; không hiển thị đa ngôn ngữ/môn trên 1 Item.

• Quyền chỉnh sửa: List sourceType=user cho phép sửa nội dung; system|practice_suggested không cho sửa nội dung Item (vẫn cho quản lý nhóm).

• Ôn tập cho phép Skip.

• Hiển thị tiến độ ở List Index và List Detail.

• Phân biệt System List vs User List bằng badge/label.

• Hiển thị trạng thái duyệt (pending/approved/rejected) cho chủ sở hữu List.

• Community Highlights thay cho AI list suggestion.

• Weekly Goal: tính theo tuần (locale/timezone), reset tự động đầu tuần; chỉ đếm item đúng.

• Progress (hiển thị):

  • 6 mức Hạt giống → Nở Hoa (derive từ F_now).
  • Tổng quan gộp 3 bucket: Chưa học · Đang ôn · Thành thạo.

Monetization & Credits

• All-in-one subscription: unlock unlimited explain/review AI + video trong phạm vi chương trình; quota hiển thị theo kỳ, reset khi renew.
• AI Credit: dùng cho Explain, AI Generate, Future AI Tools; tiêu hao theo bảng giá (ví dụ Explain = 5 credit, Generate list = 20 credit).
• Credit prioritization: nếu user có quota subscription còn lại → dùng quota trước, hết quota → trừ credit cá nhân.
• Balance display: header Home + modal trigger hiển thị Credit còn lại và Quyền all-in-one; parent xem được tất cả profile.
• Purchasing: link Mua credit mở modal checkout (lite vs all-in-one); parent phải xác nhận PIN khi trừ credit cho con.
• Logging: mọi lần tiêu hao ghi vào CreditLedger (feature, listId, amount, timestamp) để hiện lịch sử trong Account.
• Refund policy: nếu AI thất bại (timeout/đánh giá fail) → tự động hoàn credit, toast “Đã hoàn 20 credit”.
• Promotion: upsell combo program khi parent chỉ sở hữu 1 gói all-in-one; hiển thị badge Tiết kiệm khi thêm SAT.
• Grace period: khi subscription sắp hết hạn (7 ngày) → banner warning + CTA renew; hết hạn → chuyển sang trạng thái credit-only (Disable unlimited).

Pro access patterns (Vocabulary Notebook)

• Mục tiêu chung: logic Pro của Sổ từ vựng phải nhất quán với Pro logic toàn DOL Academy (xem thêm Payment/PAY_Product_Catalog.md, docs/Features/FEATURE_Subscription_Management.md).
• Hai hướng triển khai chính (TBD, tuỳ chương trình):
  • Option A – Trial lists full-feature
    • Mỗi chương trình có 1–2 list được gắn cờ trial.
    • Với list trial: mọi user (kể cả free) dùng đầy đủ Sổ từ vựng: Add to My Lists, Review/SRS, progress, streak, AI tools (giới hạn theo credit/quota chung).
    • Phần lớn list còn lại: chỉ user có premium (all-in-one/gói chương trình) mới kích hoạt được Sổ từ vựng (Add, Review, tracking, AI…). User free có thể xem nội dung list nhưng không dùng tính năng học.
    • Phù hợp khi muốn tập trung “taster experience” vào vài list được chọn (onboarding, campaign…).
  • Option B – Free view, gated practice
    • Tất cả list/public vocab đều xem free ở mức đọc (Index/Detail/Item); không giới hạn số list xem được.
    • Mọi tính năng Notebook/Practice (Add to My Lists, Review/SRS, tracking, AI tools) yêu cầu Pro (subscription/credit phù hợp), không phân biệt trial hay không.
    • Có thể bổ sung trial ở mức “số phiên miễn phí” hoặc “slot list miễn phí” cho user mới, nhưng default là mô hình free-view + gated-practice.
• Cả hai option dùng chung hạ tầng event/monetization; Product quyết định per-program và có thể A/B test.

Quy tắc (bổ sung cho Community)

• Chỉ xuất list đã duyệt; áp dụng filter timeframe (7/30/90 ngày) cho số liệu “được học/được xem/được thêm”.
• Dedupe với My Lists: nếu user đã có list → hiển thị trạng thái “Đã trong thư viện”, không cho Add lần nữa.
• Add to My Lists: tạo bản sao giữ nguyên subject; log community_list_added; hỗ trợ Quick Add (không rời trang, hiển thị chip “Added”).
• Persist filters: Subject/Sort/Timeframe được đưa vào URL để share/khôi phục state.
• Empty theo môn/timeframe: gợi ý đổi môn hoặc về All.

Behaviors bổ sung

• Ghi nhớ lựa chọn view (List/Group) và trạng thái collapse/expand nhóm theo user.
• Toggle ẩn/hiện mini chart trong Progress Overview; nhớ trạng thái theo user.
• Reorder mode trong Group view mặc định OFF; có tooltip hướng dẫn khi hover. Khi rời trang/reload tự reset về OFF.
• Trong Group view, khi bật Reorder mode: cung cấp Select all/Deselect all theo group; nút Delete hiển thị số lượng đã chọn và chỉ active khi ≥1; mặc định chỉ gỡ list khỏi group (không xoá khỏi thư viện); tùy chọn Archive hàng loạt với xác nhận 2 bước.
• Progress Hub: nhớ tab lần xem gần nhất; Summary hiển thị 3 thẻ (Biết đến/Ghi nhớ/Thành thạo) với Tổng, Δ7d, Freshness (median days). Drill‑down 1 nhấp tới My Lists với bộ lọc tương ứng.
• Progress Lite: Subject pills nhớ lựa chọn; có 1 liên kết “Xem chi tiết” dẫn tới My Lists với bộ lọc Subject hiện tại.

Permissions

• List cá nhân: chủ sở hữu được rename/sửa item; người xem với link share chỉ được review (nếu cho phép).
• Community: chỉ list đã duyệt mới được public; Add to My Lists tạo bản sao thuộc user.
• Archived: chỉ owner được Restore/Delete (nếu policy cho phép delete).

Templates

• Template logic tham chiếu: docs/Command/CMD_Templates_Logic.md

Luồng

• Tạo thủ công: New List → nhập tiêu đề/subject → thêm item thủ công → lưu.

• AI generate: prompt/upload → draft List → moderation → chỉnh sửa → lưu → (tuỳ chọn) chia sẻ.

• Bắt đầu học (auto session, SRS)

  • User chỉ thấy 1 nút chính “Bắt đầu học” trên Home; không phải chọn Học mới/Ôn cũ.
  • Khi bấm, hệ thống tạo một phiên auto trộn: item cần ôn lại (do lâu ngày/chưa vững) và item mới từ các List phù hợp.
  • Chế độ phiên:
    • Phiên có giới hạn thời gian: mặc định ~15 phút (configurable, ví dụ 10/15/20 phút) với thanh đếm ngược; hết thời gian auto kết thúc.
    • Phiên không giới hạn: học theo nhóm item nhỏ, user có thể dừng bất cứ lúc nào.
  • Trong phiên: mỗi thẻ cho phép Tôi nhớ / Tôi chưa nhớ / Bỏ qua; không có cấu hình phức tạp.
  • Đúng: F_now tăng (có thể lên mức cao hơn), D giảm và khoảng ôn dài hơn.
  • Sai: đánh dấu item “cần ôn”; lên lịch cho xuất hiện lại sau vài thẻ khác (không lặp ngay lập tức) để tránh nhàm chán.
  • Queue trong phiên được chia thành từng nhóm item nhỏ (ví dụ 5–10 item) chạy tuần tự; sau mỗi nhóm hiển thị mini-summary để user quyết định tiếp tục hay dừng.

• Vòng đời List: Delete → Archived → (tuỳ chọn) Restore.

• Nhóm List: tạo Group → thêm List (system/user) → reorder.

• Intake gợi ý sau test: Kết quả test → danh sách Suggestion → người dùng xem trước → Add vào sổ (tạo List sourceType=practice_suggested).

• Weekly Goal: set target → hiển thị tiến độ tuần trong Hero; hoàn thành khi completedThisWeek ≥ targetPerWeek.

• Progress Hub → Next Best Actions: khi người dùng bấm CTA sẽ mở phiên ôn tập tương ứng (batch mặc định 10, theo policy list được chọn) hoặc điều hướng tới My Lists phù hợp.

Spaced repetition (memory score – đề xuất)

• Mỗi item có một chỉ số nhớ đơn giản (0–100) giảm dần theo thời gian nếu không ôn.
• Đúng liên tiếp nhiều lần → chỉ số giảm chậm hơn (khoảng cách giữa các lần ôn dài hơn).
• Sai hoặc lâu ngày không ôn → chỉ số tụt nhanh, đưa item vào hàng đợi ôn khi user bấm “Bắt đầu học”.
• Một số item lâu ngày không gặp có thể coi là “từ nước” (quên gần như hoàn toàn); sau khi ôn đúng lại 1 lần có thể nhảy lên mức trung bình (không coi là hoàn toàn mới).

Quy tắc tính cho Progress Lite

• Loại trừ: Archived không được tính vào counters và thanh 3 bucket; practice_suggested tính như list thường sau khi Add.
• Learned (tuần này): đếm item lần đầu rời Hạt giống hoặc tăng mức trong tuần; mỗi item chỉ tính 1 lần/tuần.
• Items added (30 ngày): đếm KnowledgeItem mới được thêm vào bất kỳ User List nào trong 30 ngày; gồm Add từ Community, Import, tạo thủ công. Không đếm mục hệ thống chưa Add vào thư viện cá nhân.
• Active lists (14 ngày): list có ≥ 1 sự kiện học/ôn hoặc thêm/sửa mục trong 14 ngày.
• Thanh 3 bucket: Chưa học (Hạt giống) · Đang ôn (Nảy mầm → Cây non) · Thành thạo (Trưởng thành → Nở Hoa).
• Hoàn thành List (achievement): một List coi là “hoàn thành” khi ≥ 80% mục ở Trưởng thành hoặc Nở Hoa.

Streak từ vựng

• Mục tiêu: tạo thói quen học từ vựng mỗi ngày; người dùng có nơi riêng trong Sổ từ vựng để xem chi tiết streak.
• Kích hoạt ngày: khi user trả lời ≥ 1 item trong Review/Quiz của bất kỳ List đang active trong ngày; hành động skip không tính.
• Thời gian & freeze: dùng chung múi giờ và quy tắc freeze/reset với Core Streak (xem Learning Management/LM_Streak.md).
• Hiển thị
  • Card tổng quan ở Sổ từ vựng (current streak, best streak).
  • Trang chi tiết: heatmap theo ngày, lịch sử reset, best streak.
• Dữ liệu
  • Ghi nhận has_vocab_activity[date]=true khi có sự kiện hợp lệ.
  • Tính streak từ chuỗi ngày liên tiếp có cờ hợp lệ, áp dụng 1 ngày freeze.

Lỗi & Trường hợp biên

• Dedup trong phạm vi List; thêm sang List khác tạo entry riêng.

• Xoá Group không xoá List; đảm bảo List vẫn truy cập được.

• Restore từ Archived giữ nguyên trạng thái học.

• Sai môn khi thêm Item vào List khác môn: chặn và gợi ý tạo List mới/cùng môn.

• Không đủ quyền sửa nội dung Item trong List system|practice_suggested.

• DnD không khả dụng: fallback action buttons.

Analytics

• ai_generate_requested, ai_generate_completed, moderation_flagged/approved
• item_reviewed, item_skipped, review_result
• stage_changed_to_known, stage_changed_to_learned, stage_changed_to_mastered
• list_deleted_to_archived, list_restored
• group_created/deleted, group_list_added/removed
• list_progress_viewed, global_progress_viewed
• list_created_manual/ai/practice_suggested, moderation_status_viewed
• vocab_home_viewed (mở trang Home), vocab_home_quick_action_clicked (bấm hành động nhanh)
• community_list_clicked (xem/preview list cộng đồng), community_list_added (thêm list cộng đồng vào thư viện)
• vocab_streak_day_marked, vocab_streak_viewed, vocab_streak_best_updated, vocab_streak_reset
• weekly_goal_set, weekly_goal_progress_viewed, weekly_goal_completed
• progress_lite_viewed, progress_lite_view_details_clicked, progress_lite_subject_changed, progress_lite_achievement_viewed
• auto_session_started, auto_session_completed (user bấm “Bắt đầu học” và kết thúc một phiên auto; kèm số item mới/ôn)
• item_memory_score_updated (spaced repetition cập nhật chỉ số nhớ sau mỗi lần trả lời)
• vocab_trial_list_started, vocab_trial_list_completed (user bắt đầu/hoàn tất học trên list trial)
• vocab_feature_locked_viewed (user thấy trạng thái khoá notebook/practice trên list không có quyền)

Chính sách logging

• Không log hành vi chi tiết phía client; chỉ thống kê tổng hợp phục vụ hiển thị cho user.
• Log ở admin chỉ dùng khi cần xử lý khiếu nại và tuân thủ chính sách bảo mật.

Change log

• 2025-11-28: Cập nhật luồng “Bắt đầu học” dùng phiên auto (SRS), hỗ trợ cả phiên có/không giới hạn thời gian và học theo nhóm item nhỏ tuần tự.
• 2025-11-28: Bổ sung mô hình spaced repetition đơn giản (memory score 0–100) và analytics tương ứng (auto_session_started/completed, item_memory_score_updated).
• 2025-11-28: Ghi nhận hai option Pro access cho Sổ từ vựng (Option A - Trial lists full-feature, Option B - Free view + gated practice) để đồng bộ với logic Pro toàn DOL Academy; quyết định triển khai per-program.