---
url: https://docs.nemo12.com/workflows/mentor-onboarding.md
description: >-
  WF-18 Onboarding Mentor (Dolphin): luồng vào rõ ràng cho Dolphin, ngang hàng
  với luồng Nemo (WF-01) và Marlin (WF-02).
---

# WF-18 — Mentor (Dolphin) Onboarding

Ba cộng đồng của Nemo12 đều phải có luồng vào rõ ràng: **Nemos** → [WF-01](learner-onboarding.md), **Marlins** → [WF-02](parent-onboarding.md), **Dolphins** → chính file này. Trước 2026-08-15 chỉ có hai luồng đầu được đặc tả; Dolphin vẫn vào được nhưng bằng các bước truyền miệng — đó là thứ file này thay thế.

**Điểm khác biệt với hai luồng kia:** Dolphin **không tự đăng ký được**. Quyền phải được cấp từ trong ra (admin console), và cổng dolphin còn một lớp chặn ở hạ tầng (Cloudflare Access) trước cả khi request chạm tới app. Đây là chủ ý: một Dolphin nhìn được dữ liệu của **mọi** trẻ trong hệ (SRC-037), nên đường vào phải hẹp và để lại dấu vết.

## Actor & tiền điều kiện

| | |
| --- | --- |
| Actor chính | Dolphin (mentor nội bộ — Q-009: 10 người, phase 1) |
| Actor phụ | Admin (chủ dự án) — người cấp quyền |
| Tiền điều kiện | Email của Dolphin nằm trong policy Cloudflare Access của `dolphin.nemo12.com`; người đó đã đăng nhập Nemo12 **ít nhất một lần** (để tồn tại bản ghi `users`) |
| Kết thúc khi | Dolphin mở được danh sách learner và ghi được ghi chú đầu tiên |

## Các bước

```mermaid
flowchart TD
  A[Admin mở admin.nemo12.com #/access] --> B[Nhập email + chọn role 'mentor']
  B --> C{Email đã từng đăng nhập?}
  C -- chưa --> C1[Báo lỗi: người này phải đăng nhập một lần trước<br/>Admin gửi link nemo12.com cho họ] --> B
  C -- rồi --> D[Cấp role · ghi audit_log RoleGranted]
  D --> E[Tùy chọn: gán learner theo dõi chính<br/>mentor_assignments · KHÔNG phải giới hạn quyền]
  E --> F[Dolphin mở dolphin.nemo12.com]
  F --> G{Cloudflare Access cho qua?}
  G -- không --> G1[Chặn ở hạ tầng — request không chạm app]
  G -- có --> H[Đăng nhập Google GSI → session cookie .nemo12.com]
  H --> I{/v1/me trả role mentor?}
  I -- không --> I1[Portal rỗng + thông báo 'chưa có quyền'<br/>KHÔNG lộ dữ liệu learner nào]
  I -- có --> J[Danh sách mọi learner, mọi family]
  J --> K[Mở hồ sơ một learner<br/>→ bắt buộc ghi audit log truy cập]
  K --> L[Ghi ghi chú đầu tiên · chọn visibility]
  L --> M[Chuyển sang nhịp thường ngày: WF-06m]
```

## Chi tiết

1. **Cấp quyền** (REQ-ACC-05) — admin console `#/access`, ô *Grant a role*: email + role `mentor`. Người chưa từng đăng nhập thì chưa có `users.id` để gắn role; màn hình nói thẳng điều đó thay vì tạo bản ghi ma. Mỗi lần cấp quyền ghi `audit_log`.
2. **Phân công theo dõi** (tùy chọn) — ô *Assign a learner to a mentor* tạo `mentor_assignments`. Từ SRC-037, assignment **không còn là giới hạn quyền**: nó chỉ là danh sách "những em tôi theo sát nhất" để dựng dashboard. Mọi Dolphin vẫn xem được mọi learner.
3. **Hai lớp bảo vệ** (REQ-SEC-05, REQ-SEC-02) — lớp hạ tầng: Cloudflare Access trên `dolphin.nemo12.com` (đã bật, xem [open-questions](../open-questions/index.md)); lớp ứng dụng: `/v1/mentor/*` yêu cầu session + role `mentor`/`admin`. Hai lớp độc lập — hỏng một lớp vẫn không lộ dữ liệu.
4. **Phiên đầu tiên** (REQ-MEN-01, REQ-MEN-06) — danh sách learner của mọi family; mở một em ra thấy cockpit + toàn cảnh + tiến độ. **Mỗi lần một Dolphin đọc dữ liệu của learner không thuộc quyền sở hữu của mình đều phải ghi audit log** — đây là điều kiện đánh đổi cho việc bỏ giới hạn assignment, không phải tính năng phụ.
5. **Ghi chú đầu tiên** (REQ-MEN-02) — mỗi ghi chú chọn mức hiển thị `internal_staff` / `mentor_team` / learner-visible. Mặc định là `internal_staff`: người mới dễ quên đổi, nên mặc định phải là mức kín nhất.
6. **Bàn giao sang nhịp thường ngày** — từ đây Dolphin đi theo [WF-06m](mentor-observation.md): xem learner, ghi quan sát, phản hồi.

## Trạng thái & cổng

| Cổng | Điều kiện qua | Nếu không qua |
| --- | --- | --- |
| Access gate | email ∈ policy Cloudflare Access | Cloudflare chặn, app không nhận request |
| Role gate | `/v1/me` có role `mentor` hoặc `admin` | Portal rỗng + thông báo "chưa có quyền" |
| Audit gate | mọi lần đọc learner data ghi được `audit_log` | Không đọc được (ghi log hỏng ⇒ từ chối truy cập, không âm thầm bỏ qua) |

## Sự kiện

`RoleGranted` · `MentorAssigned` · `LearnerDataAccessed` (audit) · `MentorNoteCreated` · `MentorInteractionRecorded` (→ Evidence Registry, REQ-MEN-03).

## Hỏng thì người dùng thấy gì

| Hỏng ở đâu | Dolphin thấy |
| --- | --- |
| Chưa được cấp role | "Tài khoản này chưa có quyền mentor" — không có danh sách, không có tên trẻ nào |
| Access chưa mở cho email | Trang đăng nhập của Cloudflare, không vào được app |
| API mentor lỗi | Danh sách rỗng kèm nút thử lại; không hiện dữ liệu cũ trong cache |

## Trace

REQ-ACC-05→§1 · REQ-MEN-01→§4 · REQ-MEN-02→§5 · REQ-MEN-06→§4 · REQ-SEC-02/05→§3.
Ma trận quyền chi tiết: [reference/permissions.md](../reference/permissions.md). Yêu cầu gốc: [PRD-001 §5 REQ-MEN](../product/prd-001/req/family.md).