PRD-001 — Nemo12 Platform

Core job: "Nemo12 liên tục hiểu learner đang ở đâu, tìm ra điều đang cản learner tiến lên, rồi giúp learner và gia đình biết chính xác nên làm gì tiếp theo."

1. Tầm nhìn & Brand Architecture

Nemo12 là một education world duy nhất cho K12 — không phải sáu website độc lập. Một learner giữ một identity, một learner model, một learning history xuyên suốt mọi school.

Nhánh	Tên	Vai trò	Domain/URL
Community	Nemos	Học sinh (learners)	learn.nemo12.com
Community	Marlins	Bố mẹ (parents)	marlins.nemo12.com
Community	Dolphins	Mentors	(mentor portal)
School	Turtle	Foundation — học chắc, đường dài	nemo12.com/turtle
School	Shark	Advanced / thi chuyên, high-performance	nemo12.com/shark
School	Octopus	AI & Future Skills	nemo12.com/octopus
School	Squid	English / IELTS	nemo12.com/squid
School	Ray	SAT / AP / College Prep	nemo12.com/ray
School	Whale	Study Abroad & Admissions — "Go far. Find the right ocean."	nemo12.com/whale

Nguồn legacy: Turtle + Shark kế thừa chuyenchon (SRC-013); Octopus kế thừa sutucon.com (SRC-014).

Thông số đã chốt (2026-08-13)

• Thứ tự build: web → learn → marlins → mentors → admin (Q-002).
• Quy mô năm đầu: ~10.000 learners, ~10.000 parents, ~10 mentors (Q-004).
• Mô hình: blended, 95% online (Q-005).
• Account: parent-first — account tự tạo khi parent login Google; parent invite learner (Q-006).
• Stack: Vite + VitePress là chính; tính trước cho mobile app (Q-029).

2. Personas & Pains (SRC-006)

Nemo (học sinh)

Pain chính: không biết mình hổng chính xác ở đâu; không biết bài nào nên làm trước; bài quá khó không rõ thiếu prerequisite nào; bài quá dễ vẫn phải học lại; không phân biệt tiến bộ thật với "quen dạng bài"; quá nhiều mục tiêu cạnh tranh; feedback chỉ là điểm số; sai không biết vì sao sai; đổi trung tâm là mất learning history; học sinh giỏi bị curriculum đại trà làm chậm.

Marlin (bố mẹ)

Pain chính: chỉ thấy điểm thấp rồi đoán nguyên nhân; không biết nên học thêm gì/bao nhiêu; quá nhiều lời khuyên trái ngược; không biết khi nào can thiệp; không phân biệt thiếu kiến thức / kỹ năng / động lực / thời gian / sai cách; không có nơi tổng hợp hành trình của con; nhiều dashboard ít insight hành động được; dễ thành người nhắc học – ép học; intervention error (điểm thấp → cho học thêm, trong khi nguyên nhân là prerequisite gap / giấc ngủ / exam technique...).

JTBD cấp ecosystem

JTBD	Learner	Parent
Understand me / my child	Tôi thực sự đang ở đâu?	Con tôi thực sự đang ở đâu?
Find the gap	Tôi đang mắc ở đâu?	Vì sao con gặp khó khăn?
Tell me what next	Tôi nên học gì tiếp?	Chúng tôi nên làm gì tiếp?
Help me improve	Giúp tôi vượt đúng trở ngại	Giúp tôi hỗ trợ đúng cách
Show progress	Tôi đang tiến bộ thế nào?	Con còn cách mục tiêu bao xa?
Keep one continuous journey	Đừng bắt đầu lại khi đổi school	Một hồ sơ xuyên suốt của con

3. Use-Case Model

graph LR
  subgraph Actors
    N[Nemo - Learner]
    M[Marlin - Parent]
    D[Dolphin - Mentor]
    S[Staff / Content Team]
  end
  subgraph learn.nemo12.com
    UC1(Xem next best action / cockpit)
    UC2(Làm learning experience đúng độ khó)
    UC3(Làm assessment / diagnostic)
    UC4(Xem overview đa chiều & goal readiness)
    UC5(Hỏi đáp / comment trên object học tập)
  end
  subgraph marlins.nemo12.com
    UC6(Login Google → account tự tạo)
    UC7(Invite con vào học)
    UC8(Hiểu trạng thái con + vì sao)
    UC9(Nhận actionable recommendation)
    UC10(Ghi observation / upload evidence)
  end
  subgraph mentors portal
    UC11(Xem learner được giao)
    UC12(Ghi note - internal / phản hồi)
    UC13(Review & feature bài làm)
  end
  subgraph admin / mori
    UC14(Quản lý content + quality loop)
    UC15(Duyệt moderation & audit)
  end
  N --> UC1 & UC2 & UC3 & UC4 & UC5
  M --> UC6 & UC7 & UC8 & UC9 & UC10 & UC5
  D --> UC11 & UC12 & UC13 & UC5
  S --> UC14 & UC15

4. User Stories

Format: As a…, I want…, so that… — mỗi story trace tới REQ. (AC = acceptance criteria chính.)

ID	Story	REQ
US-01	As a Marlin, I want đăng nhập bằng Google và có account ngay, so that tôi bắt đầu không cần form đăng ký. AC: login lần đầu tự tạo account + family; không nhập password.	REQ-ACC-01/02
US-02	As a Marlin, I want invite con bằng link/email, so that con vào học dưới sự đồng ý của tôi. AC: learner chỉ học được sau khi nhận invite; một family nhiều con; một con nhiều guardian.	REQ-ACC-03/04
US-03	As a Nemo, I want thấy "next best action" mỗi khi mở app, so that tôi không phải tự chọn trong 80 bài. AC: có lý do "vì sao là việc này"; trace ngược tới goal.	REQ-LRN-02, REQ-INT-05
US-04	As a Nemo, I want được học đúng độ khó, so that không chán vì dễ quá hoặc nản vì khó quá. AC: difficulty controller điều chỉnh theo success rate; scaffold khi 40–65%.	REQ-LRN-03, REQ-INT-06
US-05	As a Nemo, I want được "giải cứu" khi mắc kẹt, so that tôi biết mình thiếu prerequisite nào. AC: sau N lần fail → prerequisite check, không lặp thêm bài cùng dạng.	REQ-LRN-04, REQ-INT-06
US-06	As a Nemo, I want thấy readiness tới goal (vd "SAT Math 72%, còn 4 gap critical"), so that tôi biết còn cách mục tiêu bao xa.	REQ-LRN-05, REQ-VIS-03
US-07	As a Nemo, I want giữ nguyên hồ sơ khi học thêm school khác, so that không ai phải "hiểu tôi lại từ đầu". AC: một learner_id canonical; mastery không nhân bản theo school.	REQ-LRN-06, REQ-INT-09
US-08	As a Nemo, I want dừng một topic khi đã đạt đủ mục tiêu, so that không bị overlearning. AC: stopping criteria mastery+confidence+depth+diversity.	REQ-LRN-07, REQ-INT-11
US-09	As a Marlin, I want lời giải thích "con không yếu toàn bộ Đại số — gap ở fractions, đang chặn 6 skills", so that tôi hiểu đúng nguyên nhân.	REQ-PAR-01
US-10	As a Marlin, I want biết tuần này nên làm gì (và không nên làm gì), so that tôi tránh intervention error. AC: recommendation kèm trade-off; "chưa cần thêm lớp" là output hợp lệ.	REQ-PAR-02/04
US-11	As a Marlin, I want xem Goal → Current → Gap → Trajectory → Expected readiness, so that tôi biết con có đúng hướng không.	REQ-PAR-03, REQ-VIS-03/05
US-12	As a Marlin, I want ghi observation và upload evidence (ảnh bài làm...), so that hệ thống và mentor nhìn cùng một reality.	REQ-PAR-05, REQ-INT-01
US-13	As a Marlin, I want muốn "học kỹ hơn" thì thấy rõ trade-off (thêm 4–6h để lên L4, trong khi Skill B priority cao hơn), so that tôi quyết định có hiểu biết.	REQ-PAR-06, REQ-INT-11
US-14	As a Dolphin, I want xem đúng learner được giao với model + evidence, so that tôi mentor mà không phải hỏi lại từ đầu. AC: authorization theo assignment.	REQ-MEN-01, REQ-SEC-02
US-15	As a Dolphin, I want ghi note internal (learner không thấy), so that tôi trao đổi chuyên môn thẳng thắn. AC: visibility levels hoạt động đúng.	REQ-MEN-02, REQ-INX-03
US-16	As a Dolphin, I want comment/reply ngay trên Recommendation, Assessment, bài làm, so that trao đổi gắn đúng ngữ cảnh.	REQ-INX-01/02
US-17	As a Nemo, I want react/hỏi tiếp trong thread với mentor và bố mẹ, so that cả nhà cùng nhìn một evidence.	REQ-INX-01/02, REQ-PAR-07
US-18	As a Staff, I want content đi qua quality loop (rubric, multi-evaluator, candidate version), so that không publish nội dung kém.	REQ-KNW-07..10
US-19	As a Staff, I want dashboard chất lượng (school nào thấp nhất, node nào thiếu assessment), so that tập trung người vào đúng nơi.	REQ-KNW-11
US-20	As a Nemo/Marlin, I want hệ thống vẫn dùng được khi AI/recommendation lỗi, so that việc học không bị chặn. AC: graceful degradation theo bảng SDD-006.	REQ-NFR-02/03
US-21	As a chủ hệ thống, I want mọi recommendation lưu model version + algorithm version, so that giải thích được "vì sao hôm đó khuyên vậy".	REQ-INT-14, REQ-AI-04
US-22	As a Nemo dùng mobile app (tương lai), I want mọi tính năng qua API chuẩn, so that app mobile dùng chung backend.	REQ-PLT-10
US-23	As a Marlin, I want dữ liệu con tôi được bảo vệ đúng chuẩn dữ liệu trẻ em, so that tôi yên tâm.	REQ-SEC-04/05
US-24	As a Staff, I want ingest tài liệu yêu cầu mới vào intake và trace nó tới SDD/QG, so that không tài liệu nào lửng lơ.	REQ-DOC-01..03

5. Requirement Catalog

Priority: M = MUST, S = SHOULD, C = COULD. Status: ✔ = active, ⏳ = pending-confirm (chờ trả lời câu hỏi — chưa được implement). Mỗi REQ ✔ phải có SDD + QG; xem tổng hợp tại traceability.md.

REQ-ACC — Identity, Auth & Family

ID	Yêu cầu	Ưu tiên	Nguồn	SDD	QG	Status
REQ-ACC-01	Parent-first: login Google → account + family tự tạo, không có form đăng ký/password	M	Q-006	SDD-001 §6	QG-008	✔
REQ-ACC-02	SSO cookie xuyên subdomain .nemo12.com, session opaque + hash, có rotation	M	SRC-014 FEAT-049	SDD-001 §6	QG-008	✔
REQ-ACC-03	Parent invite learner; learner chỉ học sau invite; 1 family n learners, 1 learner n guardians	M	Q-006, FEAT-029/032	SDD-001 §6	QG-008	✔
REQ-ACC-04	Canonical learner_id (không dùng email làm khóa); mapping identity duy nhất toàn platform	M	RISK-001	SDD-001 §7	QG-004	✔
REQ-ACC-05	Roles: learner, parent/guardian, mentor, staff/admin — RBAC ở backend	M	SRC-008 §9	SDD-001 §6	QG-008	✔
REQ-ACC-06	Auth flow tương thích mobile app (token-based song song cookie)	S	Q-029	SDD-001 §6	QG-008	✔

REQ-BRD — Public Web (app: web)

ID	Yêu cầu	Ưu tiên	Nguồn	SDD	QG	Status
REQ-BRD-01	nemo12.com giới thiệu ecosystem + 6 trang school (/turtle … /whale)	M	SRC-001	SDD-001 §4	QG-007	✔
REQ-BRD-02	SEO + OG cards per-route	S	FEAT-052	SDD-001 §4	QG-001	✔
REQ-BRD-03	CMS cho marketing content	S	FEAT-053, Q-050	—	—	⏳
REQ-BRD-04	Pricing page, ebooks	C	FEAT-028, Q-050	—	—	⏳

REQ-LRN — Learner Experience (app: learn)

ID	Yêu cầu	Ưu tiên	Nguồn	SDD	QG	Status
REQ-LRN-01	Learner biết chính xác mình đang ở đâu (mastery + confidence, không nhầm "chưa học" với "chưa đủ evidence")	M	SRC-006 JTBD1	SDD-002 §2	QG-005	✔
REQ-LRN-02	Next best action hằng ngày (cockpit), kèm lý do	M	SRC-006 JTBD2, FEAT-007	SDD-002 §10	QG-005	✔
REQ-LRN-03	Học đúng độ khó (difficulty controller)	M	SRC-006 JTBD3	SDD-002 §11	QG-005	✔
REQ-LRN-04	Giải cứu khi mắc kẹt: tìm nguyên nhân, scaffold, quay lại prerequisite	M	SRC-006 JTBD4	SDD-002 §11	QG-005	✔
REQ-LRN-05	Thấy tiến độ tới goal (readiness %, critical gaps)	M	SRC-006 JTBD5	SDD-008 §5	QG-005	✔
REQ-LRN-06	Một hành trình liên tục xuyên school (không học lại từ đầu)	M	SRC-006 JTBD6	SDD-007 §5	QG-005	✔
REQ-LRN-07	Chứng minh năng lực bằng evidence; dừng đúng lúc (stopping criteria)	M	SRC-006 JTBD7, SRC-011	SDD-002 §12	QG-005	✔
REQ-LRN-08	Onboarding khảo sát mục tiêu — không ép mọi learner khai mục tiêu thi chuyên	M	FEAT-005, RISK-009	SDD-002 §4	QG-002	✔

REQ-VIS — Overview & Views (SRC-012)

ID	Yêu cầu	Ưu tiên	Nguồn	SDD	QG	Status
REQ-VIS-01	Multi-dimensional view: by school/subject/area/goal/skill/readiness/workload…	M	SRC-012 §2	SDD-008 §2	QG-005	✔
REQ-VIS-02	Drill-down Nemo12 → School → Subject → Area → Unit → Skill → Evidence, và zoom-out	M	SRC-012 §3	SDD-008 §3	QG-005	✔
REQ-VIS-03	Goal View: readiness ước tính + critical/important/nice-to-have gaps	M	SRC-012 §5	SDD-008 §5	QG-005	✔
REQ-VIS-04	Node states đầy đủ (Not Assessed / Unknown / Learning / Needs Review / Mastered / Advanced / Blocked / At Risk)	M	SRC-012 §4	SDD-008 §4	QG-005	✔
REQ-VIS-05	Trajectory view (Past → Current → Expected) + Workload view + cảnh báo overload	M	SRC-012 §6–7	SDD-008 §6	QG-005	✔
REQ-VIS-06	Trace ngược "vì sao hôm nay học cái này": Task → Gap → Area → Goal	M	SRC-012 §8	SDD-008 §7	QG-005	✔

REQ-PAR — Marlins (app: marlins)

ID	Yêu cầu	Ưu tiên	Nguồn	SDD	QG	Status
REQ-PAR-01	"Giúp tôi hiểu con": giải thích trạng thái + nguyên nhân bằng evidence	M	SRC-006 Job1	SDD-002 §13	QG-005	✔
REQ-PAR-02	Actionable recommendation cho parent (tối nay/tuần này/tháng này)	M	SRC-006 Job2	SDD-002 §13	QG-005	✔
REQ-PAR-03	On-track view: Goal → Current → Gap → Trajectory → Expected	M	SRC-006 Job3	SDD-008 §5	QG-005	✔
REQ-PAR-04	Chống intervention error: recommendation nêu rõ cả "không nên làm gì" + trade-off	M	SRC-006 Job4, SRC-011 §8	SDD-002 §13	QG-005	✔
REQ-PAR-05	Parent Model (evidence + inferred tendency, không label phán xét) + parent observation/upload	M	SRC-003 §4, FEAT-030/031	SDD-002 §4	QG-005	✔
REQ-PAR-06	Depth trade-off explanation (target depth, current, cost để nâng)	M	SRC-011 §8	SDD-002 §12	QG-005	✔
REQ-PAR-07	Shared understanding layer: parent–learner–mentor nhìn cùng evidence	M	SRC-006 Job5	SDD-005 §7	QG-005	✔
REQ-PAR-08	Member-intelligence-style: evidence gaps → adaptive questions cho parent	S	FEAT-033, Q-040	—	—	⏳

REQ-MEN — Dolphins (app: mentors)

ID	Yêu cầu	Ưu tiên	Nguồn	SDD	QG	Status
REQ-MEN-01	Mentor xem learner theo assignment (authorization bắt buộc)	M	SRC-002 §13	SDD-001 §6	QG-008	✔
REQ-MEN-02	Mentor notes với visibility (internal_staff / mentor_team / learner-visible)	M	SRC-007	SDD-005 §4	QG-008	✔
REQ-MEN-03	Mentor interaction ghi thành evidence (MentorInteractionRecorded)	M	SRC-002 §2.3	SDD-002 §5	QG-005	✔
REQ-MEN-04	Class operations: lớp, lịch, link buổi học, điểm danh	M?	FEAT-011..013, Q-045	—	—	⏳
REQ-MEN-05	Mentor review & feature bài làm xuất sắc	S	FEAT-020, Q-047	—	—	⏳

REQ-SCH — Schools as Domain Context

ID	Yêu cầu	Ưu tiên	Nguồn	SDD	QG	Status
REQ-SCH-01	School là domain context, không phải app/database riêng (learn.nemo12.com/turtle…)	M	SRC-002 §4.1	SDD-001 §4	QG-001	✔
REQ-SCH-02	Canonical skill — school chỉ thêm context (expected difficulty, exam application), không nhân bản skill	M	SRC-010 §5	SDD-007 §5	QG-004	✔
REQ-SCH-03	Depth target theo goal/school (Turtle L3 vs Shark L4-L5 trên cùng skill)	M	SRC-011 §3-4, FEAT-038	SDD-002 §12	QG-005	✔
REQ-SCH-04	Shark: exam & school intelligence (kho đề, registry trường, exam calendar, score simulator)	M?	FEAT-034..037, Q-041	—	—	⏳
REQ-SCH-05	Octopus: 4F Reflection + product submission (proof-of-work) + curriculum 5 Academies	M?	FEAT-045..048, Q-039	—	—	⏳

REQ-INT — Learner Intelligence (SRC-003, 009, 010, 011)

ID	Yêu cầu	Ưu tiên	Nguồn	SDD	QG	Status
REQ-INT-01	Evidence Registry chung: immutable, source reliability, idempotency key	M	SRC-003 §5	SDD-002 §5	QG-004/005	✔
REQ-INT-02	Learner Model = computed state (mastery/confidence/trajectory per skill), tách khỏi raw history	M	SRC-003 §2, SRC-010 §4	SDD-002 §2	QG-005	✔
REQ-INT-03	Mastery và confidence tách riêng; thuật toán cập nhật có evidence_strength + α	M	SRC-003 §7-8	SDD-002 §7-8	QG-005	✔
REQ-INT-04	Assessment Engine = information acquisition (chọn câu hỏi theo InformationGain, dừng khi đủ confidence)	M	SRC-003 §9	SDD-002 §9	QG-005	✔
REQ-INT-05	Recommendation Engine với priority score + explainability	M	SRC-003 §10	SDD-002 §10	QG-005	✔
REQ-INT-06	Learning Engine: chọn HOW (scaffold, worked example…), difficulty controller, prerequisite fallback	M	SRC-003 §11	SDD-002 §11	QG-005	✔
REQ-INT-07	Context Engine + TTL/decay; Context Projection per task (Context Contract, không dump toàn bộ history vào AI)	M	SRC-003 §12, SRC-010 §6-7	SDD-007 §6-7	QG-010	✔
REQ-INT-08	Global Workload Model (available time, cognitive load, deadlines, capacity)	M	SRC-009 §1, SRC-010 §8	SDD-007 §8	QG-005	✔
REQ-INT-09	Global Learner Orchestrator: school engines chỉ tạo candidate; arbitration toàn cục; conflict resolution	M	SRC-009 §2, SRC-010 §9-10	SDD-007 §9-10	QG-005	✔
REQ-INT-10	Model growth control: no raw events trong model, summaries có provenance, incremental recompute	M	SRC-010 §11-13	SDD-007 §11-13	QG-005	✔
REQ-INT-11	Depth levels L0–L5, target depth per objective, stopping criteria, diminishing returns, overlearning protection, depth budget	M	SRC-011	SDD-002 §12	QG-005	✔
REQ-INT-12	Recency & decay: effective_confidence giảm theo thời gian; evidence có validity window/superseded	M	SRC-010 §12	SDD-007 §12	QG-005	✔
REQ-INT-13	Main learning loop chạy async (Queues + Workflows), không trong 1 HTTP request	M	SRC-003 §15	SDD-002 §14	QG-009	✔
REQ-INT-14	Model versioning + recommendation explainability (input_model_version, algorithm_version)	M	SRC-003 §16	SDD-002 §15	QG-005	✔

REQ-KNW — Knowledge, Content & Quality (SRC-004, 005)

ID	Yêu cầu	Ưu tiên	Nguồn	SDD	QG	Status
REQ-KNW-01	Knowledge Registry: Domain→Area→Knowledge Node/Skill, đầy đủ metadata + lifecycle	M	SRC-004 §2	SDD-003 §2	QG-006	✔
REQ-KNW-02	Shared Knowledge/Skill Graph (prerequisite + 7 quan hệ), dùng chung mọi school	M	SRC-004 §3	SDD-003 §3	QG-006	✔
REQ-KNW-03	Learning Package đóng gói mục tiêu dạy được (nhiều package/skill theo age, level, exam)	M	SRC-004 §4	SDD-003 §4	QG-006	✔
REQ-KNW-04	Learning Experience Registry: abstract entity + experience_type (Micro/Practice/Assessment/Lab/Project/Simulation)	M	SRC-005 §5-8	SDD-004 §5-8	QG-006	✔
REQ-KNW-05	Item Bank riêng, không duplicate question giữa practice/assessment/micro	M	SRC-005 §9	SDD-004 §9	QG-006	✔
REQ-KNW-06	Storage 3 lớp: D1 metadata, R2 heavy content, KV/cache manifests; "load structure first, content on demand"	M	SRC-005 §4, §10	SDD-004 §4, §10	QG-004	✔
REQ-KNW-07	Quality Profile + rubric per entity; scores có reason/evidence/evaluator/rubric_version	M	SRC-004 §6	SDD-003 §6	QG-006	✔
REQ-KNW-08	Quality Engine 3 lớp: deterministic checks, graph/rule reasoning, LLM evaluation theo rubric	M	SRC-004 §7	SDD-003 §7	QG-006	✔
REQ-KNW-09	Multi-evaluator + variance flag + human review cho high-stakes	M	SRC-004 §8	SDD-003 §8	QG-006	✔
REQ-KNW-10	Improvement Engine + candidate version lifecycle (không sửa production trực tiếp); Priority Engine	M	SRC-004 §10-12	SDD-003 §10-12	QG-006	✔
REQ-KNW-11	Quality Registry + dashboard (coverage, node thiếu assessment, content quá hạn review)	M	SRC-004 §9	SDD-003 §9	QG-006	✔
REQ-KNW-12	Versioning immutable per asset; learner session ghi experience_version	M	SRC-005 §11	SDD-004 §11	QG-004	✔
REQ-KNW-13	Quality cuối cùng đối chiếu learner evidence thật (không chỉ LLM score)	M	SRC-004 §11	SDD-003 §11	QG-006	✔
REQ-KNW-14	Chiến lược 290 labs legacy (code-component + registry metadata)	S	FEAT-008, Q-044	—	—	⏳
REQ-KNW-15	AI illustrations + knowledge stories	C	FEAT-041/042, Q-051	—	—	⏳

REQ-INX — Interaction & Conversation (SRC-007)

ID	Yêu cầu	Ưu tiên	Nguồn	SDD	QG	Status
REQ-INX-01	Comment/Reply/Reaction/Mention/Annotation trên mọi object qua target_type+target_id	M	SRC-007	SDD-005 §2-3	QG-008	✔
REQ-INX-02	Threading (UI giới hạn 1–2 cấp)	M	SRC-007	SDD-005 §3	QG-007	✔
REQ-INX-03	Visibility levels: private / learner_parent / mentor_team / school / community / internal_staff — authorize ở backend	M	SRC-007	SDD-005 §4	QG-008	✔
REQ-INX-04	Mentions → events → Queue → Notification (in-app, email, push-ready)	M	SRC-007	SDD-005 §5	QG-009	✔
REQ-INX-05	Moderation K12: profanity/abuse/spam detection, report/hide/block, moderation queue, audit log, AI classify + human review	M	SRC-007	SDD-005 §6	QG-008	✔
REQ-INX-06	Activity Stream → Learner Activity Timeline (feed cho Learner/Parent Model)	M	SRC-007	SDD-005 §7	QG-005	✔
REQ-INX-07	Vote (up/down) + mentor featured trên submissions	S	FEAT-020, Q-047	—	—	⏳

REQ-MED — Media & Image Management (yêu cầu bổ sung 2026-08-13)

ID	Yêu cầu	Ưu tiên	Nguồn	SDD	QG	Status
REQ-MED-01	Media Registry dùng chung toàn platform: metadata D1, bytes R2, gắn mọi object qua target_type+target_id	M	User 2026-08-13, SRC-014	SDD-009 §2	QG-004	✔
REQ-MED-02	Upload flow direct-to-storage (presigned), validate type/size/quota; cấm base64 lưu vĩnh viễn trong D1	M	RISK-028	SDD-009 §3	QG-004	✔
REQ-MED-03	Delivery qua CDN + Cloudflare Images variants (thumb/card/full), signed URL theo visibility + authz backend	M	SRC-014	SDD-009 §4	QG-008	✔
REQ-MED-04	Moderation K12 bắt buộc: AI classify + moderation queue + audit; EXIF strip; chưa approve không serve public	M	SRC-007, SRC-014	SDD-009 §5	QG-008	✔
REQ-MED-05	Media versioning + retention + xóa theo child-privacy	M	REQ-SEC-04	SDD-009 §6	QG-008	✔
REQ-MED-06	AI illustration pipeline ghi cùng registry với provenance	C	FEAT-041, Q-051	SDD-009 §7	QG-010	⏳

REQ-LAB — Interactive Labs (bổ sung 2026-08-13, sau audit SRC-015)

ID	Yêu cầu	Ưu tiên	Nguồn	SDD	QG	Status
REQ-LAB-01	Lab Platform theo 6 archetypes: 4 engines data-driven (picker/parametric/stepper + inquiry) + sim components + scene3d cô lập	M	SRC-015	SDD-010 §2	QG-007	✔
REQ-LAB-02	Lab là LearningExperience: metadata D1 + content JSON R2 + version immutable; bỏ mô hình MPA 9-touchpoint	M	SRC-015	SDD-010 §3	QG-004	✔
REQ-LAB-03	Migrate content corpus 288 labs (620 prompts, 1.807 options, 288 inquiry triples) bằng reverse-parser; 186 picker labs = 100% tự động	M	SRC-015	SDD-010 §4	QG-006	✔
REQ-LAB-04	Evidence contract đầy đủ: lab_open/inquiry_open/inquiry_answer/lab_complete — bespoke labs phải có correctness signal	M	SRC-015	SDD-010 §5	QG-005	✔
REQ-LAB-05	Một LabShell trong Design System, sửa a11y một lần cho cả 288 (dialog, focus trap, aria-live, reduced-motion)	M	SRC-015	SDD-010 §6	QG-007	✔
REQ-LAB-06	Công nghệ dài hạn: React 19 + SVG procedural (zero-asset), config schema versioned (zod), engine/content version độc lập	M	User 2026-08-13	SDD-010 §7	QG-005	✔
REQ-LAB-07	Labs qua Quality Engine + coverage map theo taxonomy kế thừa; mode suy từ implementation (legacy sai nhãn 24%)	M	SRC-015	SDD-010 §8	QG-006	✔

REQ-PLT — Platform & Stack

ID	Yêu cầu	Ưu tiên	Nguồn	SDD	QG	Status
REQ-PLT-01	Cloudflare-first: Workers, D1, R2, KV, Queues, Workflows, AI Gateway, API Shield	M	SRC-002 §2.1	SDD-001 §2-3	QG-003/009	✔
REQ-PLT-02	Modular monolith (bounded modules), không microservice per school	M	SRC-002 §2.2	SDD-001 §2	QG-001	✔
REQ-PLT-03	Event-driven domain events chuẩn hóa (event_id, idempotency_key, occurred_at, producer, version)	M	SRC-002 §2.3, SRC-008 §4	SDD-001 §8	QG-009	✔
REQ-PLT-04	Backend Hono + TypeScript trên Workers; API api.nemo12.com/v1/*; OpenAPI contract sinh từ router (không hand-maintained)	M	SRC-002 §6, RISK-024	SDD-001 §5	QG-003	✔
REQ-PLT-05	Frontend Vite + React + TS; docs VitePress; apps: web, learn, marlins, mentors, admin, docs	M	SRC-002 §4, Q-002	SDD-001 §4	QG-001	✔
REQ-PLT-06	Một Design System duy nhất (Tailwind v4 + shadcn mới nhất), theme nhỏ per school, không fork	M	SRC-002 §5	DS-001	QG-007	✔
REQ-PLT-07	Monorepo: apps/ + workers/ + packages/ + migrations/ + docs/	M	SRC-002 §12	SDD-001 §9	QG-001	✔
REQ-PLT-08	Một canonical docs source, frontmatter machine-readable, VitePress render	M	SRC-002 §11	SDD-001 §10	QG-001	✔
REQ-PLT-09	AI chỉ qua AI Gateway (không gọi provider trực tiếp, không fallback bypass); prompt/model/policy registry + traceability per output	M	SRC-002 §10, RISK-022	SDD-001 §8, SDD-002 §15	QG-010	✔
REQ-PLT-10	API-first cho mobile app tương lai (auth token flow, push notification trong Notification module)	M	Q-029	SDD-001 §5-6	QG-003	✔
REQ-PLT-11	Migration đơn nguồn, idempotent, một sequence duy nhất cho mỗi database	M	RISK-004/016	SDD-001 §7	QG-004	✔

REQ-NFR — Reliability & Non-Functional (SRC-008)

ID	Yêu cầu	Ưu tiên	Nguồn	SDD	QG	Status
REQ-NFR-01	Failure isolation giữa các module; critical path = commit → emit event → async	M	SRC-008 §1-2	SDD-006 §1-2	QG-009	✔
REQ-NFR-02	Graceful degradation có bảng fallback cho từng capability	M	SRC-008 §3	SDD-006 §3	QG-009	✔
REQ-NFR-03	Data durability + idempotent operations cho critical data	M	SRC-008 §4	SDD-006 §4	QG-004	✔
REQ-NFR-04	Async reliability: retry, backoff, DLQ, timeout, manual replay	M	SRC-008 §5	SDD-006 §5	QG-009	✔
REQ-NFR-05	Availability tiers: T1 ≥99.9%, T2 ≥99.5%, T3 best-effort	M	SRC-008 §6	SDD-006 §6	QG-009	✔
REQ-NFR-06	Performance: API p95 <500ms, simple reads p95 <300ms, interaction <200ms; "show useful state first, enrich later"	M	SRC-008 §7	SDD-006 §7	QG-009	✔
REQ-NFR-07	Scale cho 10k learners + 10k parents, learner đa school đồng thời	M	SRC-008 §8, Q-004	SDD-006 §8	QG-009	✔
REQ-NFR-08	Observability: structured telemetry, trace_id correlation, dashboards	M	SRC-008 §10	SDD-006 §10	QG-009	✔
REQ-NFR-09	Error taxonomy chuẩn, không leak raw exception	M	SRC-008 §11	SDD-006 §11	QG-009	✔
REQ-NFR-10	Deployment safety: backward-compatible API/events, safe migration, rollback, feature flags	M	SRC-008 §12-13	SDD-006 §12-13	QG-009	✔
REQ-NFR-11	Disaster recovery: backup, PITR, immutable versions, rollback content/algorithm	M	SRC-008 §14	SDD-006 §14	QG-009	✔
REQ-NFR-12	Production-ready checklist 5 câu hỏi cho mọi subsystem mới	M	SRC-008 §16	SDD-006 §16	QG-009	✔

REQ-SEC — Security & Privacy

ID	Yêu cầu	Ưu tiên	Nguồn	SDD	QG	Status
REQ-SEC-01	Least privilege; backend authorization mọi truy cập learner data	M	SRC-008 §9	SDD-006 §9	QG-008	✔
REQ-SEC-02	Parent chỉ xem learner trong family; mentor theo assignment	M	SRC-002 §13	SDD-006 §9	QG-008	✔
REQ-SEC-03	Audit log cho thay đổi quan trọng; secrets ngoài code; encryption in transit; rate limiting; input validation	M	SRC-008 §9	SDD-006 §9	QG-008	✔
REQ-SEC-04	Child-data privacy là architectural concern (consent, minimization, retention)	M	SRC-008 §9, Q-030	SDD-006 §9	QG-008	✔
REQ-SEC-05	Cloudflare Access bảo vệ admin/mori/internal surfaces	M	SRC-013 pattern	SDD-001 §6	QG-008	✔
REQ-SEC-06	Không hardcode owner email / audience / school_id / domain trong source	M	RISK-013/023	SDD-001 §11	QG-008	✔

REQ-GAM / REQ-COM / REQ-GRW — pending clusters (từ legacy, chờ xác nhận)

ID	Yêu cầu	Nguồn	Status
REQ-GAM-01	Badges, streaks, XP, stickers, rewards	FEAT-015..019, 027, Q-046	⏳
REQ-COM-01	Public portfolio + social profiles + contributions	FEAT-021/022, Q-047	⏳
REQ-COM-02	Events/Cafe offline + Zalo community	FEAT-023/024, Q-048	⏳
REQ-GRW-01	Membership entitlements + payments	FEAT-025, Q-014/015	⏳
REQ-GRW-02	Affiliate / referral	FEAT-026, Q-049	⏳
REQ-TRU-01	Integrity system (khai báo, thay đổi, notices)	FEAT-051, Q-053	⏳

REQ-DOC — Documentation System

ID	Yêu cầu	Ưu tiên	Nguồn	SDD	QG	Status
REQ-DOC-01	Một canonical docs source cho cả người và AI (frontmatter, intake ledger)	M	User + SRC-002 §11	conventions.md	QG-001	✔
REQ-DOC-02	Traceability 2 chiều: mọi REQ active có SDD + QG; mọi ý SDD trace về REQ/US	M	User 2026-08-13	traceability.md	QG-001	✔
REQ-DOC-03	Quality framework cho chính tài liệu (kế thừa requirements-assessment của chuyenchon)	S	FEAT-044, Q-057	quality-gates.md	QG-002	✔