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, Marlins → WF-02, 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

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); 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: 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. Yêu cầu gốc: PRD-001 §5 REQ-MEN.