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 | Nemo | User journey + orchestration | ✅ chi tiết | 🔵 đang code · có run history |
| WF-02 | Parent Onboarding | Marlin | User journey | ✅ chi tiết | ✅ đã có (auth + invite) |
| WF-03 | Diagnosis | Nemo (+ system) | Orchestration | ✅ chi tiết | 🔵 đang nâng cấp (gate theo model) · có run history |
| WF-04 | Evidence → Model Update | System | Cloudflare Workflow (async) | ✅ chi tiết | 🟡 baseline (đồng bộ), sẽ chuyển async · có run history |
| WF-05 | Recommendation & Cockpit | System → Nemo/Marlin | Orchestration | ✅ chi tiết | ✅ baseline (cockpit) |
| WF-06m | Mentor Observation | 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 | 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 | 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, types: SDD-004 §5-8.
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.
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.
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, SDD-006 §5.
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, SDD-009 §5.
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.
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; UI: Coral (SDD-013 §5).
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.
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.
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.
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.
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.
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.
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.
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.