---
url: https://docs.nemo12.com/workflows/learner-onboarding.md
description: >-
  WF-01 Onboarding Learner: chọn school, khai hồ sơ, dựng Learner Model và
  Context Model rồi mới chẩn đoán.
---

# 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ường | Kiểu | Bắt buộc | Ghi chú |
| --- | --- | --- | --- |
| full_name / display_name | text | ✔ | ≥2 ký tự |
| date_of_birth | date | ✔ | suy ra birth_year, tuổi |
| grade | int 1–12 | ✔ | lớp hiện tại |
| current_school | text | ✔ | tên trường đang học (ngoài Nemo12) |
| province | text | ✔ | 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ường | Kiểu | Ghi chú |
| --- | --- | --- |
| target_school_name (+ id nếu chọn từ registry) | text | trường chuyên/chọn sẽ thi |
| province | text | |
| specialist_subject | text | môn chuyên |
| non_specialist_subjects | text\[] | các môn không chuyên |
| exam_date_approx | date | lịch thi ~ |
| priority | int | learner 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).