---
url: https://docs.nemo12.com/reference.md
description: >-
  Mục lục khu System Reference: mô tả hiện trạng đang chạy (code đúng, tài liệu
  sai thì sửa tài liệu), bổ sung cho SDD.
---

# System Reference

> **SDD trả lời "vì sao thiết kế thế". Khu này trả lời "cái gì đang chạy, chạy ra sao".**

Nếu một câu trong khu này không khớp với code thì **code đúng, tài liệu sai** — sửa tài liệu ngay. Khu Reference không mô tả dự định; nó mô tả hiện trạng, kể cả những chỗ còn thiếu.

## Viết tay

| Trang | Trả lời |
| --- | --- |
| [Models](models.md) | Có những model nào, chứa gì, ai sinh ra, versioning ra sao |
| [**1 · Goal Model**](goal-model.md) | Vì sao rỗng là hợp lệ, deadline gần thắng mục tiêu lớn, phát hiện xung đột mà không tự quyết |
| [**2 · Learner Context Model**](learner-context-model.md) | Lớp/school/quỹ thời gian, vì sao goal chỉ là tham chiếu |
| [**3 · Learner Model**](learner-model.md) | Bức ảnh tổng hợp vs sự thật sống, cập nhật theo từng câu trả lời |
| [**4 · Readiness Model**](readiness-model.md) | Luôn gắn một đề, xếp gap theo tác động, "cần đo" khác "cần học" |
| [**5 · Retention Model & Engine**](retention-model.md) | Trí nhớ: công thức decay, cập nhật thế nào, dùng thế nào, bất biến nào không được phá |
| [**6 · Constraint Model**](constraint-model.md) | Quỹ thời gian đến từ đâu, vì sao "chưa khai" khác "bằng 0" |
| [**7 · Learning Plan & Planning Engine**](learning-plan-model.md) | Chia một buổi học thế nào, và "đổi gì so với bản trước, vì sao" |
| [**Parent Model**](parent-model.md) *(khai báo)* | Niềm tin vs thực tế, observation, khuyến nghị chống can thiệp sai |
| [**Student Portrait**](student-portrait.md) *(khai báo)* | Ai được viết gì, hai cột bố mẹ/con, vì sao không override hệ thống |
| [Rà soát gắn node cho lab](../quality/reports/lab-node-review.md) | 70 lab chưa gắn Knowledge Node: 35 ghép được vào node có sẵn, 35 cần quyết có mở mảng mới không |
| [**Recommendation Engine**](recommendation-engine.md) | "Hôm nay học bài nào" — 5 bước chọn việc, và chỗ công thức code khác công thức SDD |
| [**Learning Engine**](learning-engine.md) | Dạy thế nào: chọn câu, 3 lớp đo, sai thì làm lại, và vì sao không dựng model sau mỗi câu |
| [**Assessment Engine**](assessment-engine.md) | Đo thế nào: 4 loại đo, ba tầng chống rác đầu vào, đường đi của một bằng chứng |
| [**Depth Engine**](depth-engine.md) | ⚠️ **Chưa xây** — thiết kế L0–L5, stopping criteria, và những mảnh đang tạm thay |
| [**Quality Engine**](quality-engine.md) | 4 lớp gác nội dung: sàng lọc máy, rubric 8 chiều ≥2 evaluator, cổng publish, vòng phản hồi |
| [**Context Builder**](context-builder.md) | Đường duy nhất learner data vào prompt: 4 purpose, bí danh, cổng chặn định danh |
| [**Global Orchestrator**](global-orchestrator.md) | Điều phối xuyên school — vì sao nó không phải một file, và còn thiếu mối nối nào |
| [Engines](engines.md) | Từng engine: **đầu vào → thuật toán (công thức thật) → đầu ra** |
| [Workflows](workflows.md) | Luồng đang chạy thật, từng step, cách xem lại một lần chạy |
| [Queues](queues.md) | `nemo12-events`: envelope, retry, DLQ, trạng thái consumer |
| [Schedules](schedules.md) | Cron đang chạy (api 4 nhịp + foundry 1), khoá và trần của từng nhịp, và những việc chưa có cron |
| [Webhooks](webhooks.md) | Hiện không có; luật bắt buộc khi thêm |
| [Email](emails/index.md) | Sáu loại thư gửi bố mẹ: lúc gửi, cách kích hoạt, ích lợi, trạng thái nối dây |
| [State Machines](state-machines.md) | Mọi enum trạng thái và đường chuyển tiếp |
| [Permissions](permissions.md) | Vai trò, `canAccessLearner()`, ai thấy được gì |
| [Errors](errors.md) | 7 mã lỗi, hợp đồng phản hồi, quy tắc suy giảm |
| [AI Registry](ai-registry.md) | Mọi chỗ gọi LLM — và vì sao Learner Model không dùng LLM |
| [Glossary](glossary.md) | Nemo, Marlin, mastery vs retention, mã sổ sách |
| [**Chuẩn curriculum Pearl**](curriculum-pearl-standard.md) | Tám luật S1-S8 cho curriculum năng lực trên Pearl, và vì sao 3-6 không mâu thuẫn với 6/6/6 |
| [**Chuẩn thiết kế Course**](course-design-standard/index.md) | CD-1..CD-5 cho tầng Course kiểu CEFR: level 1-5 thay lớp, unit = Big Idea + Essential Question, lesson = Guiding Question; soạn bằng skill `/course-design` |
| [**Sân luyện chép chính tả**](dictation-game.md) | learn.nemo12.com/dictation: learner chọn bậc và chủ đề, Workflow sinh bài, hạn mức ba bài, và năm bảng xếp hạng |
| [**Tiến độ bài tập IELTS**](ielts-exercise-progress.md) | Bốn trạng thái của một bài, hai cuốn sổ, `ref` đếm thứ tự TỪ 0, và vì sao một lỗi ở đường đọc trạng thái là một lỗi chặn đường học |
| [**Nghe & chép lại**](dictation.md) | Bài tập nghe của chặng Investigate: ba đoạn mỗi bài, chấm phần trăm bằng thuật toán, mốc từng câu chính xác vì máy đọc từng câu rồi mới nối |
| [**Thứ tự dựng một Course**](course-build-order.md) | Cái gì trước, cái gì sau: tầng 0 nguồn → course → unit → lesson → kho câu; ranh giới người/máy và chỗ xưởng nội dung cắm vào |
| [Luật 6/6/6](curriculum-666.md) | Ràng buộc tối thiểu 6 cho cây kiến thức trong D1, và còn thiếu bao nhiêu |

## Sinh tự động từ code

Ba trang dưới đây do `scripts/gen-reference.mjs` đọc thẳng source sinh ra. **Đừng sửa tay** — sửa code rồi chạy:

```bash
npm run gen:reference
```

| Trang | Nguồn |
| --- | --- |
| [Data Dictionary](data-dictionary.md) | `migrations/*.sql` — mọi bảng, cột, khóa ngoại, index |
| [API Catalog](api.md) | `workers/api/src/modules/*/routes.ts` — mọi endpoint kèm mức bảo vệ |
| [Event Catalog](events.md) | mọi lời gọi `publishEvent()` |

Cột **Auth** trong API Catalog được suy ra từ chính middleware và guard trong handler. Endpoint mới hiện `🌐 public` mà không cố ý là **bug bảo mật**, không phải lỗi tài liệu.

## Engine nào ở trang nào

Vài engine được mô tả **cùng trang với model nó sinh ra** — tách đôi sẽ khiến người đọc phải nhảy qua lại giữa công thức và chỗ nó ghi vào.

| Engine | Trang |
| --- | --- |
| Goal Engine | [1 · Goal Model](goal-model.md) |
| Context Engine | [2 · Learner Context Model](learner-context-model.md) |
| Learner Model Engine | [3 · Learner Model](learner-model.md) |
| Readiness Engine | [4 · Readiness Model](readiness-model.md) |
| **Retention Engine** | [5 · Retention Model & Engine](retention-model.md) |
| Constraint Engine | [6 · Constraint Model](constraint-model.md) |
| **Planning Engine** | [7 · Learning Plan & Planning Engine](learning-plan-model.md) |
| Mastery & Confidence Engine | [Engines §1](engines.md) |
| Recommendation · Learning · Assessment · Quality | trang riêng (bảng trên) |
| Context Builder | [trang riêng](context-builder.md) — cổng đã xây, chưa có lưu lượng |
| Global Orchestrator | [trang riêng](global-orchestrator.md) — là **tên gọi** cho 3 engine phối hợp, không phải file |
| Depth Engine | [chưa xây](depth-engine.md) |

## Ba luật của khu này

1. **Mô tả cái đang chạy, không mô tả cái sẽ làm.** Chưa có thì ghi thẳng là chưa có, kèm lý do — như [cron](schedules.md) và [webhook](webhooks.md).
2. **Khoảng trống phải hiện ra.** Consumer queue còn là stub, `refreshRetentionProjections()` chưa có trigger — những dòng đó nằm trong tài liệu là có chủ ý.
3. **Cơ khí thì sinh, phán đoán thì viết.** Bảng và endpoint đổi mỗi tuần nên phải sinh; còn "vì sao decay trước rồi mới cộng evidence" thì không script nào viết thay được.

## Trace

* REQ-DOC-01/02/04 · [conventions](../conventions.md) · [traceability](../traceability.md)
* Kiểm chứng: QG-001.