---
url: https://docs.nemo12.com/workflows.md
description: >-
  Catalog các workflow Nemo12 (user journey và điều phối Cloudflare
  Workflows/Queues): actor, tiền điều kiện, bước, cổng, sự kiện.
---

# Workflows Catalog

Tài liệu mô tả **các workflow (quy trình)** của Nemo12 — cả *user journey* (trình tự người dùng đi qua) lẫn *system orchestration* (điều phối bằng Cloudflare Workflows/Queues). Mỗi workflow có: actor, tiền điều kiện, các bước, trạng thái/cổng (gate), sự kiện phát ra, và lỗi/degrade.

## Nguyên tắc trình tự lõi (rất quan trọng)

> **Chọn school → Khai báo hồ sơ cơ bản (nếu thiếu) → Hệ thống dựng Learner Model + Learner Context Model → RỒI mới Chẩn đoán.**
> Chẩn đoán phải **dựa trên Learner Model** (đọc context: lớp, school, mục tiêu) chứ không chạy khi chưa có model.

## Danh mục

| ID | Workflow | Actor | Loại | Tài liệu | Trạng thái |
| --- | --- | --- | --- | --- | --- |
| WF-01 | [Learner Onboarding](learner-onboarding.md) | Nemo | User journey + orchestration | ✅ chi tiết | 🔵 đang code · có run history |
| WF-02 | [Parent Onboarding](parent-onboarding.md) | Marlin | User journey | ✅ chi tiết | ✅ đã có (auth + invite) |
| WF-03 | [Diagnosis](diagnosis.md) | Nemo (+ system) | Orchestration | ✅ chi tiết | 🔵 đang nâng cấp (gate theo model) · có run history |
| WF-04 | [Evidence → Model Update](evidence-model-update.md) | System | Cloudflare Workflow (async) | ✅ chi tiết | 🟡 baseline (đồng bộ), sẽ chuyển async · có run history |
| WF-05 | [Recommendation & Cockpit](recommendation-cockpit.md) | System → Nemo/Marlin | Orchestration | ✅ chi tiết | ✅ baseline (cockpit) |
| WF-06m | [Mentor Observation](mentor-observation.md) | Dolphin | User journey | ✅ chi tiết | ✅ live (dolphin.nemo12.com) |
| WF-06 | Learning Experience delivery | Nemo | Orchestration | catalog dưới | ⏳ chưa code |
| WF-07 | Content Quality & Improvement loop | Staff + System | Cloudflare Workflow | catalog dưới | ⏳ thiết kế (SDD-003) |
| WF-08 | Global Learner Orchestration (đa school) | System | Cloudflare Workflow | catalog dưới | ⏳ thiết kế (SDD-007) |
| WF-09 | Notification fan-out | System | Queue | catalog dưới | ⏳ thiết kế (SDD-005) |
| WF-10 | Moderation (K12) | System + Staff | Queue + human review | catalog dưới | ⏳ thiết kế (SDD-005) |
| WF-11 | Admissions / Study-abroad (Whale) | Marlin/Nemo + Staff | Cloudflare Workflow | catalog dưới | ⏳ chưa scope |
| WF-12 | [Parent recommendation](parent-recommendation.md) | System → Marlin | Orchestration | ✅ chi tiết | ✅ live (marlins) |
| WF-13 | Real exam ingestion (đề thi thật) | System (+ owner spot-check) | Content pipeline AI-first | catalog dưới | ⏳ thiết kế (SDD-012) |
| WF-14 | Blueprint generation run | Staff + System | Cloudflare Workflow + Queue | catalog dưới | ⏳ thiết kế (SDD-013) |
| WF-15 | Declarations intake (Nemo/Marlin khai tự nhiên) | Nemo/Marlin + System | AI interpret + confirm | catalog dưới | 🟡 baseline (form → Goal Engine, chưa có AI interpret) |
| WF-16 | Exam crawl & acquisition | System | Cloudflare Workflow + Queue | catalog dưới | ⏳ thiết kế (SDD-014) |
| WF-17 | Nightly Model Refresh (retention + dựng bù model lõi) | System | Cron Trigger hằng ngày | catalog dưới | ✅ live (21:00 UTC) |
| WF-18 | [Mentor Onboarding](mentor-onboarding.md) | Dolphin | User journey | ✅ chi tiết | ✅ live (dolphin.nemo12.com) |
| WF-19 | Lesson content forge (Content Foundry) | Admin + System | **Cloudflare Workflow thật** (`nemo12-foundry`) | catalog dưới | ✅ live (SDD-027, SRC-632) |
| WF-20 | Item forge (sinh kho câu hỏi mỗi bài) | Admin + System | **Cloudflare Workflow thật** (`nemo12-foundry`) | catalog dưới | 🔵 đang dựng (SDD-027 §17, SRC-638) |

## Catalog — các workflow chưa có tài liệu riêng

### WF-06 — Learning Experience delivery

`Recommendation chọn WHAT → Learning Engine chọn HOW → render experience (micro/practice/lab) → thu evidence → WF-04`. Chi tiết engine: [SDD-002 §11](../architecture/sdd-002-learner-intelligence/models-and-engines.md), types: [SDD-004 §5-8](../architecture/sdd-004-curriculum-storage.md).

### WF-07 — Content Quality & Improvement loop

`Content → Quality Engine (rules+graph+LLM+learner evidence) → findings → Priority Engine → Improvement Engine → candidate version → re-evaluate → publish`. Chạy nền qua Cloudflare Workflow + Queue. Chi tiết: [SDD-003 §7-11](../architecture/sdd-003-knowledge-quality.md).

### WF-08 — Global Learner Orchestration (learner học nhiều school)

`School engines sinh CandidateRecommendation[] → Workload Model → Global Orchestrator (constrained optimization: TotalTime ≤ Capacity) → GlobalLearningPlan`. Chi tiết: [SDD-007 §9-10](../architecture/sdd-007-learner-orchestration.md).

### WF-09 — Notification fan-out

`Domain event (Comment/Mention/RecommendationGenerated…) → Queue nemo12-events → Notification consumer → in-app/email/push`. Idempotent, DLQ. Chi tiết: [SDD-005 §5](../architecture/sdd-005-interaction.md), [SDD-006 §5](../architecture/sdd-006-reliability.md).

### WF-10 — Moderation (K12)

`Media/Comment created → Queue → AI classify (qua AI Gateway) → auto-approve | moderation queue → human review → approve/hide/block + audit`. Chi tiết: [SDD-005 §6](../architecture/sdd-005-interaction.md), [SDD-009 §5](../architecture/sdd-009-media.md).

### WF-11 — Admissions / Study-abroad (Whale)

Cloudflare Workflow nhiều bước có human approval: chọn quốc gia/trường/ngành → scholarship → application strategy → hồ sơ → nộp. Chưa scope (Q-041 nhóm Shark/Whale).

### WF-12 — Parent recommendation

`Learner evidence + Parent Model → Parent Engine → actionable recommendation cho Marlin (kể cả "chưa cần thêm lớp") + trade-off`. Chi tiết: [SDD-002 §13](../architecture/sdd-002-learner-intelligence/models-and-engines.md).

### WF-13 — Real exam ingestion (đề thi thật)

`Sưu tầm (PDF/ảnh + nguồn) → OCR/nhập → tách bài → biên tập statement → metadata + dạng bài + node links → lời giải gợi ý (AI draft → AI multi-evaluator, owner spot-check — SRC-035) → deterministic checks (QG-011) → publish`. Chi tiết: [SDD-012 §7](../architecture/sdd-012-real-exam-bank.md); UI: Coral ([SDD-013 §5](../architecture/sdd-013-coral-content-plane.md)).

### WF-15 — Declarations intake

`Nemo/Marlin khai tự nhiên ("con sắp thi học kỳ") → AI interpret qua gateway (QG-010) → confirm với người khai → Context Event Registry / Goal Model → Model Update Policy chạy downstream`. Tùy chọn, cấm form 20 fields; degradation → form tối giản. Chi tiết: [SDD-002 §5b, §16](../architecture/sdd-002-learner-intelligence/models-and-engines.md).

### WF-16 — Exam crawl & acquisition

`acquisition_target → Workflow exam-crawl (robots-aware) → asset gốc R2 → AI extract/tách bài/metadata/lời giải → AI multi-evaluator → publish exam bank | review queue`. Chi tiết: [SDD-014 §4](../architecture/sdd-014-exam-acquisition.md).

### WF-17 — Retention refresh (định kỳ)

`Cron 21:00 UTC (04:00 VN) → chọn learner có retention state, ưu tiên snapshot cũ nhất → Retention Engine mỗi learner → tính lại urgency / review window / confidence + snapshot Retention Model`. Cap 200 learner/lần chạy, phần bị hoãn ghi rõ `deferred` trong output run (không cắt im lặng). Trí nhớ phai theo THỜI GIAN nên workflow này phải chạy kể cả khi learner không làm gì. Đồng thời **dựng bù model lõi còn thiếu** (Goal · Context · Learner · Readiness) cho learner đã có evidence: engine là event-driven nên learner học từ trước khi engine được nối dây sẽ không bao giờ tự có model — cron là nơi duy nhất sửa được. Backfill chạy một lần cho mỗi learner, có rồi thì thôi. Chi tiết: [SDD-017 §15](../architecture/sdd-017-retention.md).

### WF-19 — Lesson content forge (Content Foundry)

`Admin bấm (requireAdmin + audit log) → nemo12-foundry POST /runs (trần chi phí ngày) → Cloudflare Workflow LessonForge: các model SONG SONG, mỗi model sinh → chấm rubric L1-L16 → còn chỗ hỏng thì sửa 1 vòng → chấm lại → R2 + content_run_trials (stamp prompt/rubric version) → người duyệt đưa vào curriculum_* bằng tay`. Workflow Cloudflare THẬT đầu tiên của hệ — không dùng run log ba bảng, tra qua `GET /v1/admin/foundry/runs`. Chi tiết: [SDD-027](../architecture/sdd-027-content-foundry/index.md).

### WF-20 — Item forge (kho câu hỏi mỗi bài)

`Kế hoạch 16 khe (vai + hiểu lầm + độ khó) → mỗi khe MỘT lượt gọi model → 11 ràng buộc kiểm bằng mã → trượt thì vá đúng chỗ (tối đa 1 lượt) → code xoay vị trí đáp án và gán độ khó → content_item_drafts chờ người duyệt`. Sinh từng khe thay vì cả chùm là cách hạ số ràng buộc model phải giữ từ ~11 xuống ~4; `constraint_pressure` ghi lại ràng buộc nào đang chặn. Chi tiết: [SDD-027 §17](../architecture/sdd-027-content-foundry/itemforge-and-costs.md).

### WF-14 — Blueprint generation run

`Blueprint (LX/Assessment) + target set → Cloudflare Workflow content-generation → fan-out generate qua Queue nemo12-content → collect → Quality Engine evaluate → review queue → publish`. Chi tiết: [SDD-013 §3, §8](../architecture/sdd-013-coral-content-plane.md).

## Bằng chứng thi hành

Mỗi lần một workflow chạy đều ghi `workflow_runs` + `workflow_run_steps`, mỗi lần một engine chạy ghi `engine_runs` — xem lại trong Admin › Runs. Chi tiết: [SDD-002 §19](../architecture/sdd-002-learner-intelligence/run-history-and-scheduling.md).

## Trace

Các workflow trace về REQ nhóm `REQ-ONB` (onboarding), `REQ-LRN`/`REQ-INT` (learner intelligence), `REQ-ACC` (auth/family), `REQ-PAR` (parent), `REQ-KNW` (content). Xem [traceability.md](../traceability.md).