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 | Có những model nào, chứa gì, ai sinh ra, versioning ra sao |
| 1 · Goal Model | 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 | Lớp/school/quỹ thời gian, vì sao goal chỉ là tham chiếu |
| 3 · Learner Model | 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 | 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 | 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 | Quỹ thời gian đến từ đâu, vì sao "chưa khai" khác "bằng 0" |
| 7 · Learning Plan & Planning Engine | Chia một buổi học thế nào, và "đổi gì so với bản trước, vì sao" |
| Parent Model (khai báo) | Niềm tin vs thực tế, observation, khuyến nghị chống can thiệp sai |
| Student Portrait (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 | 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 | "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 | 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 | Đ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 | ⚠️ Chưa xây — thiết kế L0–L5, stopping criteria, và những mảnh đang tạm thay |
| Quality Engine | 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 | Đường duy nhất learner data vào prompt: 4 purpose, bí danh, cổng chặn định danh |
| Global Orchestrator | Đ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 | Từng engine: đầu vào → thuật toán (công thức thật) → đầu ra |
| Workflows | Luồng đang chạy thật, từng step, cách xem lại một lần chạy |
| Queues | nemo12-events: envelope, retry, DLQ, trạng thái consumer |
| Schedules | 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 | Hiện không có; luật bắt buộc khi thêm |
| 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 | Mọi enum trạng thái và đường chuyển tiếp |
| Permissions | Vai trò, canAccessLearner(), ai thấy được gì |
| Errors | 7 mã lỗi, hợp đồng phản hồi, quy tắc suy giảm |
| AI Registry | Mọi chỗ gọi LLM — và vì sao Learner Model không dùng LLM |
| Glossary | Nemo, Marlin, mastery vs retention, mã sổ sách |
| Chuẩn curriculum Pearl | 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 | 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ả | 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 | 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 | 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 | 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 | 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 | migrations/*.sql — mọi bảng, cột, khóa ngoại, index |
| API Catalog | workers/api/src/modules/*/routes.ts — mọi endpoint kèm mức bảo vệ |
| Event Catalog | 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 |
| Context Engine | 2 · Learner Context Model |
| Learner Model Engine | 3 · Learner Model |
| Readiness Engine | 4 · Readiness Model |
| Retention Engine | 5 · Retention Model & Engine |
| Constraint Engine | 6 · Constraint Model |
| Planning Engine | 7 · Learning Plan & Planning Engine |
| Mastery & Confidence Engine | Engines §1 |
| Recommendation · Learning · Assessment · Quality | trang riêng (bảng trên) |
| Context Builder | trang riêng — cổng đã xây, chưa có lưu lượng |
| Global Orchestrator | trang riêng — là tên gọi cho 3 engine phối hợp, không phải file |
| Depth Engine | chưa xây |
Ba luật của khu này
- 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 và webhook.
- 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ủ ý. - 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 · traceability
- Kiểm chứng: QG-001.