Nemo12 Docs

WF-01 — Learner (Nemo) Onboarding ​

Nguyên tắc: chọn school → khai báo hồ sơ (nếu thiếu) → dựng Learner Model + Context Model → mới chẩn đoán. Tham khảo cách thu thập của app.chuyenchon.com/app/onboarding/OnboardingWizard.tsx + bảng onboarding_learner_profiles.

Tiền điều kiện ​

Nemo đã nhận lời mời của Marlin và đăng nhập Google (WF-02, REQ-ACC-03) → có learners row status='active', user_id gắn.

Các bước & cổng (gate) ​

mermaid
flowchart TD
  A[Nemo đăng nhập / vào learn.nemo12.com] --> B{Đã chọn school?}
  B -- chưa --> S[Chọn School<br/>Turtle / Shark / Octopus / Squid / Ray / Whale]
  S --> C{Hồ sơ cơ bản đủ?}
  B -- rồi --> C
  C -- thiếu --> P[Khai báo hồ sơ<br/>Họ tên · Ngày sinh · Lớp · Trường hiện tại · Tỉnh/Thành]
  P --> P2[Tùy chọn: mục tiêu<br/>trường mục tiêu · môn · giờ học/tuần]
  P2 --> M
  C -- đủ --> M[Khởi tạo Learner Model + Learner Context Model]
  M --> R{Đã có chẩn đoán ban đầu?}
  R -- chưa --> D[WF-03 Diagnosis<br/>dựa trên Context: lớp, school, mục tiêu]
  R -- rồi --> K[Cockpit: readiness + next best action]
  D --> K

Chi tiết từng bước ​

1. Chọn School (REQ-ONB-01) ​

Learner chọn một trong 6 school. Ghi vào school_enrollments (learner_id, school_code, status='active'). School quyết định context (subject phù hợp, blueprint mặc định), không phải database riêng (REQ-SCH-01). Một learner có thể enroll nhiều school; onboarding chạy cho school đang vào.

2. Hồ sơ cơ bản (REQ-ONB-02) — bắt buộc nếu thiếu ​

Trường thu thập (theo chuyenchon onboarding_learner_profiles):

TrườngKiểuBắt buộcGhi chú
full_name / display_nametext✔≥2 ký tự
date_of_birthdate✔suy ra birth_year, tuổi
gradeint 1–12✔lớp hiện tại
current_schooltext✔tên trường đang học (ngoài Nemo12)
provincetext✔tỉnh/thành

Lưu vào learners (display_name, birth_date, grade) + learner_profiles (current_school, province, completed_at). Gate: không cho vào chẩn đoán/học nếu hồ sơ chưa đủ.

2b. Shark — Exam Targets (REQ-ONB-07) — bắt buộc khi vào Shark ​

Nếu school đang vào là Shark, sau hồ sơ cơ bản phải khai exam targets (hỗ trợ nhiều trường):

TrườngKiểuGhi chú
target_school_name (+ id nếu chọn từ registry)texttrường chuyên/chọn sẽ thi
provincetext
specialist_subjecttextmôn chuyên
non_specialist_subjectstext[]các môn không chuyên
exam_date_approxdatelịch thi ~
priorityintlearner tự xếp ưu tiên

Cho phép thêm/sửa/xóa nhiều target (nhiều lịch thi). Mỗi target → một goal (specialized-chuyen + môn chuyên) với deadline riêng; nhiều target → Global Orchestrator cân đối (SDD-011 §2b, SDD-007 §9). Turtle bỏ qua bước này.

3. Aspirations — tùy chọn (REQ-ONB-05) ​

Với các school không phải Shark: mục tiêu (giờ học/tuần, mức rõ ràng mục tiêu) là tùy chọn. Không ép khai mục tiêu thi chuyên (fix RISK-009 — learner Turtle không cần). Nếu có → nạp vào Context Model + tạo learner_goals.

4. Khởi tạo Model (REQ-ONB-03) — trước chẩn đoán ​

Sau khi có hồ sơ, hệ thống tạo (idempotent):

  • Learner Model learner_models (learner_id, version=1, algorithm_version, generated_at, evidence_cutoff, summary_json) — khung rỗng theo SDD-002 §2 (skill states khởi tạo prior, chưa có evidence).
  • Learner Context Model learner_context_models (learner_id, active_school_code, current_grade, current_school, goal_blueprint_id?, deadline?, available_minutes_per_week, updated_at) — SDD-002 §3, SDD-007 §6. Khởi từ hồ sơ + aspirations.

Phát sự kiện LearnerModelInitialized, LearnerContextUpdated.

5. Chẩn đoán (REQ-ONB-04) → WF-03 ​

Chỉ chạy khi Learner Model đã khởi tạo. Diagnosis đọc Context Model để chọn phạm vi (lớp hiện tại làm anchor grade, school → subject/blueprint), thay vì hỏi lại từ đầu.

Trạng thái onboarding ​

onboarding_state ∈ { school_pending, profile_pending, model_pending, diagnosis_pending, ready } — /v1/me trả trạng thái này để app điều hướng đúng bước (giống onboarding_accounts.current_step của chuyenchon).

Sự kiện phát ra ​

SchoolEnrolled · LearnerProfileCompleted · LearnerModelInitialized · LearnerContextUpdated · GoalSet.

Lỗi & degrade ​

  • Model init lỗi → learner vẫn xem được school/hồ sơ; chẩn đoán trì hoãn (SDD-006 §3).
  • Thiếu trường hồ sơ → chặn mềm với thông báo rõ, không mất dữ liệu đã nhập.

Trace ​

REQ-ONB-01→§1 · 02→§2 · 03→§4 · 04→§5 · 05→§3 · REQ-LRN-08→§3 (không ép goal thi chuyên).

Nemo12