---
url: https://docs.nemo12.com/product/prd-001/req/platform.md
description: >-
  Bảng REQ của PRD-001 cho nhóm PLT, NFR, SEC, DOC: mỗi REQ một dòng với ưu
  tiên, nguồn, SDD, QG và trạng thái.
---

# PRD-001 · REQ: Nền tảng, độ tin cậy, bảo mật, tài liệu

Một mảnh của [danh mục REQ PRD-001](../../prd-001-nemo12-platform.md), gồm REQ-PLT, REQ-NFR, REQ-SEC, REQ-DOC. Sổ chung chỉ
CHÈN: thêm REQ bằng Edit vào đúng bảng của nhóm, không ghi cả file. Luật viết REQ, nghĩa của cột
Priority và Status nằm ở trang mục lục; §6, §7 ở [độ phủ](../req-coverage.md).

### 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-PLT-12 | **AI First / AI Native**: vận hành + tạo content hầu như không cần con người — mọi pipeline content chạy end-to-end bằng AI (multi-evaluator thay human review mặc định; owner chỉ spot-check theo ngưỡng rủi ro); ngoại lệ duy nhất: an toàn trẻ em/moderation public (QG-008) giữ human trong loop | M | SRC-035 | SDD-013 §6, SDD-014 §5 | QG-010 | ✔ |
| REQ-PLT-13 | **Bằng chứng thi hành**: mỗi workflow run (WF-xx) và mỗi lần engine chạy được ghi lại — trigger, trạng thái, thời lượng, step, input/output, model version sinh ra; engine chạy mà output không đổi vẫn có dòng lịch sử | M | SRC-098 | SDD-002 §19 | QG-009 | ✔ |
| REQ-PLT-14 | **Admin console tiếng Anh toàn bộ** (UI + thông điệp API của module admin); có trang tra cứu model theo learner và trang lịch sử run | M | SRC-098 | SDD-001 §4, SDD-002 §19 | QG-001 | ✔ |
| REQ-PLT-15 | **Bảng learner của admin hiện phụ huynh**: tên + email, gộp từ `family_members` (owner|guardian) và `guardians` của riêng learner. `supporter` KHÔNG tính là phụ huynh (người hỗ trợ xem được dữ liệu, không phải người chịu trách nhiệm); learner tự đứng tên tài khoản thì không tự liệt kê mình | S | SRC-404 | SDD-001 §4 | QG-001 | ✔ |
| REQ-PLT-16 | **Màn hình admin phân biệt ba trạng thái**: đang tải · rỗng thật · hỏng. Lỗi hạ tầng không được hiện ra như "không có dữ liệu", và danh sách bị cắt phải nói ra là đã cắt kèm đường xem thêm | M | SRC-416 | SDD-001 §4 | QG-009 | ✔ |
| REQ-PLT-17 | **Hành động không hoàn tác được trong admin phải xác nhận**: cấp quyền `admin`, chạy tác vụ toàn hệ, replay message, ghi đè chính sách retention. Thao tác rủi ro thấp làm hàng loạt (cấp mentor/staff) thì không hỏi | M | SRC-416 | SDD-001 §6 | QG-008 | ✔ |
| REQ-PLT-18 | **Mọi endpoint vận hành có đường vào từ giao diện**: admin đưa được người vận hành tới nhật ký audit, dead letter (kèm replay), chính sách retention (kèm sync) và chỉ số run, không phải dựng lời gọi HTTP bằng tay | M | SRC-416 | SDD-006 §16 | QG-009 | ✔ |
| REQ-PLT-19 | **Migration trùng số phải đổi tên KÈM cập nhật `d1_migrations`**, vì wrangler theo dõi bằng TÊN FILE: đổi tên trên đĩa mà không sửa bảng thì production coi đó là migration mới và chạy lại. Hai phiên chạy song song cùng chọn một số là chuyện đã xảy ra hai lần | M | SRC-343, SRC-426 | SDD-001 §5 | QG-004 | ✔ |
| REQ-PLT-20 | **Một sự việc chỉ có MỘT bảng là nguồn sự thật.** Màn Lịch thi từng ghi vào `learner_goal_dates` trong khi mọi engine đọc `semester_exam_schedule`, nên đổi ngày thi xong mà model không nhúc nhích | M | SRC-335 | SDD-002 | QG-004 | ✔ |
| REQ-PLT-21 | **Định danh trong code đặt tên tiếng Anh** — hằng số, biến, hàm, type, key nội bộ, slug URL, class CSS, tên file. Nội dung hiển thị vẫn tiếng Việt. Ngoại lệ đóng: danh từ riêng, ID nội dung chương trình học, mã môn học | M | SRC-600 | [Coding Conventions](../../../engineering/coding-conventions.md) | QG-004 | ✔ |
| REQ-PLT-22 | **Nemo12 Tool Plane** — AI Agent chạm vào hệ Nemo12 chỉ qua một tầng năng lực domain (`learner.*` · `assessment.*` · `learning.*` · `coral.*` · `application.*` · `nemo12.*`) trên MCP tại `mcp.nemo12.com`, **không bao giờ cầm credential** (D1, Cloudflare token, secret dịch vụ). Mỗi lượt gọi đi qua xác thực agent, ủy quyền bốn cấp (agent · user · resource · environment), policy engine có mức rủi ro LOW/MEDIUM/HIGH/CRITICAL, và ghi audit không chứa dữ liệu learner; `tools/list` chỉ hiện tool được cấp; tool đọc/ghi phân biệt được từ registry; tool ghi bị từ chối mặc định. Tool là ranh giới trừu tượng có version, API bên trong đổi thì Agent không gãy | M | SRC-667 | [SDD-030](../../../architecture/sdd-030-tool-plane.md) §2-11 | QG-004/008/010 | ✔ |

### 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-NFR-13 | **Một lượt chấm không đi nhiều chuyến khứ hồi D1 nối đuôi nhau**: truy vấn độc lập phải chạy song song, phát sự kiện không chặn phản hồi. Đo được trước khi sửa: sáu chuyến nối đuôi cho một lượt chấm | M | SRC-364 | SDD-006 | QG-009 | ✔ |
| REQ-NFR-14 | **Thêm cột trạng thái mới phải nới ràng buộc `CHECK` trong cùng migration.** Ghi `status='started'` vào một bảng mà `CHECK` chưa biết giá trị đó làm learner gặp "Có lỗi xảy ra" ngay khi mở bài — đã live 4 tiếng một lần | M | SRC-405 | SDD-001 §5 | QG-004 | ✔ |
| REQ-NFR-15 | **Bài học đã hiện ra thì không được biến mất giữa chừng.** Phản hồi "cứ sau một lúc thì một lesson lại bị biến mất" là lỗi đồng bộ giữa dữ liệu và giao diện, không phải chuyện thẩm mỹ: learner mất chỗ đang đứng và không biết mình đã làm tới đâu | M | SRC-374 | SDD-021 | 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 của mình (kiểm ở backend, có test chứng minh); **mentor xem được mọi learner nhưng mỗi lần truy cập bắt buộc ghi audit log** — giới hạn theo assignment đã bỏ từ SRC-037, `mentor_assignments` chỉ còn là phân công theo dõi | M | SRC-002 §13, SRC-037 | 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-SEC-07 | **Phủ xác thực chứng minh được**: mọi route `/v1` hoặc nằm dưới `requireSession`, hoặc có tên trong danh sách public khai tường minh kèm lý do. Đo bằng bảng route LÚC CHẠY chứ không bằng grep mã nguồn, và cổng chạy trong `npm test` nên chặn cả CI lẫn deploy | M | SRC-412 | SDD-001 §6 | QG-008 | ✔ |

### 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](../../../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](../../../traceability.md) | QG-001 | ✔ |
| REQ-DOC-04 | **Khu System Reference**: mô tả kỹ từng Model (nội dung, versioning), từng Engine (logic/thuật toán, đầu vào, đầu ra), từng Workflow (chi tiết step), Queue/Cron/Webhook, cùng data dictionary, API catalog, event catalog, state machines, permissions, error catalog, AI registry, glossary. Phần cơ khí **sinh tự động từ source** (`scripts/gen-reference.mjs`) để không lệch với hệ thống thật | M | SRC-067, SRC-198 | [reference/](../../../reference/index.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](../../../quality/quality-gates.md) | QG-002 | ✔ |
| REQ-DOC-05 | **Tiêu chuẩn audit toàn hệ**: 10 bộ × 5 tiêu chí × 5 chỉ báo nhị phân (pass / không pass), phủ docs · yêu cầu · kiến trúc · dữ liệu · thuật toán · nội dung · bảo mật · vận hành · trải nghiệm · AI; cấm N/A, không bằng chứng = không pass, chỉ báo 🔴 chặn release | M | SRC-108 | [audit-standard/index.md](../../../quality/audit-standard/index.md) | QG-001/002 | ✔ |
| REQ-DOC-06 | **Đóng chỉ báo audit trước khi mở cho người dùng thật**: mỗi lần audit sinh một đợt hành động, **mỗi chỉ báo KHÔNG PASS có đúng một hành động đóng được** (ghi trong báo cáo audit hoặc `open-questions/index.md` kèm ✍️ nếu là nợ chấp nhận được). Ngưỡng mở thử với người dùng thật: **≥90% (225/250) chỉ báo PASS và không chỉ báo 🔴 nào hỏng**. Cấm hạ chuẩn bằng cách sửa tiêu chuẩn thay vì sửa hệ | M | SRC-111 | [audit-standard/index.md](../../../quality/audit-standard/index.md) §13, [audit #001](../../../quality/audits/2026-08-15.md) §4 | QG-001/002 | 🔵 |
| REQ-DOC-07 | **Tài liệu không được trôi khỏi mã đang chạy**: đường dẫn mã nguồn và bảng D1 nhắc trong docs phải tồn tại thật (trừ khi câu văn nói rõ là chưa dựng hoặc đã ngừng), không doc mồ côi, và `last_reviewed` không cũ hơn lần sửa file thật. Cổng đo theo `git ls-files` và lịch sử git để cư xử giống nhau ở máy lẫn CI | M | SRC-416 | [conventions.md §4](../../../conventions.md) | QG-001 | ✔ |
| REQ-DOC-08 | **Luật cấm em dash áp cho cả chữ nằm trong DỮ LIỆU**, không riêng chữ trong mã nguồn: nội dung câu hỏi, lab và popover đều là chữ learner đọc, nên cổng phải với tới được cả kho dữ liệu | S | SRC-379, SRC-382 | [conventions.md §5](../../../conventions.md) | QG-001 | ✔ |
| REQ-DOC-09 | **Hệ tiêu chuẩn chất lượng 3 lớp trong docs.nemo12.com** là chuẩn cuối cùng của toàn hệ: lớp gate (12 QG), lớp Content Standards (CS-01..CS-09 — sổ đăng ký mọi loại content: subject/package/module/unit/LX/AX/item/figure/exam, mỗi loại chỉ tiêu số lượng + chất lượng bằng con số, mỗi số một nguồn canonical), lớp Audit (255 chỉ báo). **Definition of Done: audit đạt 100% (255/255), 0 chỉ báo 🔴 hỏng** — dưới đó sản phẩm chưa được coi là xong | M | SRC-495 | [quality/index.md](../../../quality/index.md), [content-standards.md](../../../quality/content-standards.md) | QG-012 | ✔ |
| REQ-DOC-10 | **docs.nemo12.com giống hệt pearl.nemo12.com về kỹ thuật**: cùng stack VitePress + `@nemo12/design-system` (bridge token dùng chung, không fork), cùng cấu hình (cleanUrls, appearance off, search local tiếng Việt), cùng đường deploy Cloudflare worker qua GitHub Actions | S | SRC-495 | [SDD-001 §6](../../../architecture/sdd-001-platform.md) | QG-007 | ✔ |