---
url: https://docs.nemo12.com/architecture/sdd-006-reliability.md
description: >-
  Kiến trúc độ tin cậy (SDD-006): cô lập lỗi, suy giảm êm, bền dữ liệu và
  idempotency để nền tảng vẫn phục vụ learner khi có thành phần hỏng.
---

# SDD-006 — Reliability & NFR

**Nguyên tắc:** *Failure phải được cô lập. Thiết kế với giả định bất kỳ component nào cũng có thể lỗi — hệ thống vẫn phục vụ learner an toàn.*

## 1–2. Failure Isolation (REQ-NFR-01)

Boundaries rõ giữa Identity/Learning/Assessment/Evidence/Recommendation/Interaction/Notification/AI/Content/Quality/Admissions. Cấm request chain dài `Learning→Recommendation→AI→Notification→Analytics→response`. Chuẩn: `Critical operation → Commit → Emit Event → Queue → downstream async`. Submit assessment: lưu submission + tạo evidence + trả success; AI analysis/notification/analytics chạy sau.

## 3. Graceful Degradation (REQ-NFR-02)

| Failure | Hành vi |
| --- | --- |
| AI Gateway down | deterministic recommendation hoặc báo "AI analysis tạm unavailable" |
| Recommendation down | learner vẫn xem curriculum, tiếp tục activity |
| Notification down | ghi Queue retry |
| Interaction down | learning + assessment vẫn chạy |
| Analytics down | không block transaction |
| Quality Engine down | published content vẫn phục vụ |
| R2 asset lỗi | fallback + log |
| External provider lỗi | circuit breaker, retry, fallback |
| Squid lỗi | Turtle vẫn chạy (module isolation) |
| Global Orchestrator lỗi | learner tiếp tục activity hiện tại, recommendation mới trì hoãn (SDD-007 §17) |

Optional feature không được thành single point of failure.

## 4. Data Durability & Idempotency (REQ-NFR-03)

Critical: identity, submissions, evidence, model versions, enrollment, quan hệ parent/learner, progress, recommendation history, audit. Event chuẩn `{event_id, idempotency_key, occurred_at, producer, version}`; consumer idempotent — 2 lần `AssessmentCompleted` không tạo 2 evidence.

## 5. Async Reliability (REQ-NFR-04)

Bắt buộc: retry + exponential backoff, DLQ (`nemo12-events-dlq`), timeout, failed-job inspection, manual replay. Không retry vô hạn — quá threshold → khu điều tra.

## 6. Availability Tiers (REQ-NFR-05)

* **T1 ≥99.9%**: auth, learner portal, assessment submission, progress, core APIs.
* **T2 ≥99.5%**: recommendation, parent dashboard, mentor portal, content management.
* **T3**: analytics, quality audit, background improvement, reporting.

## 7. Performance (REQ-NFR-06)

API p95 <500ms · simple reads p95 <300ms · interaction <200ms. AI/long tasks không giữ UI: *show useful state first, enrich later* (recommendation hiện trước, AI explanation cập nhật sau).

## 8. Scalability (REQ-NFR-07)

Scale theo learners (10k), concurrent sessions, schools, assets, events, AI requests. Một learner nhiều enrollment đồng thời (Turtle+Shark+Octopus+Squid+Ray) — cross-school workload trên shared infra; workload nặng đi batch/Queue.

## 9. Security & Privacy (REQ-SEC-01..04)

Least privilege; Parent A chỉ thấy learners Family A; mentor theo assignment/scope. Bắt buộc: backend authz, audit log, secrets ngoài frontend/code, TLS, secure session, rate limiting, abuse prevention, input validation (zod tại route). **Child-data privacy là architectural concern**: data minimization, consent qua parent-first flow, retention policy, quyền xóa (Nghị định 13/2023 — tự quyết Q-030).

## 10. Observability (REQ-NFR-08)

Structured telemetry `{request_id, user_id/learner_id, service, operation, latency, status, error_type, timestamp}` + `trace_id` xuyên service. Dashboards: error rate, p95/p99, queue backlog, workflow failure, D1 errors, AI failure/cost, asset errors. Workers observability bật cho mọi worker (legacy sutucon quên bật cho api — RISK-025).

## 11. Error Handling (REQ-NFR-09)

Taxonomy: `VALIDATION_ERROR, AUTHORIZATION_ERROR, LESSON_LOCKED, NOT_FOUND, CONFLICT, RATE_LIMITED, TEMPORARY_FAILURE, DEPENDENCY_FAILURE, INTERNAL_ERROR`. User message dễ hiểu; technical detail vào logs; không leak raw exception.

## 12–13. Deployment Safety & Version Compatibility (REQ-NFR-10)

Backward-compatible API/event schema; safe migration (migration tương thích deploy TRƯỚC code cần schema mới); staging checks; rollback tự động; feature flags cho thay đổi rủi ro. Version độc lập: API, Events, Learner Model, Algorithms, Rubrics, Experiences, Items, Prompts — old data đọc được sau nâng cấp; không đổi semantics field cũ mà không version.

## 14. Disaster Recovery (REQ-NFR-11)

Backup + D1 Time Travel (PITR); immutable versions; audit trail; rollback content/algorithm/config khi: deploy lỗi, data sửa sai, algorithm sai hàng loạt, publish lỗi, provider outage.

## 15–16. Quality Gate & Production-Ready Rule (REQ-NFR-12)

Mọi production change (code, migration, content, rubric, prompt, algorithm, recommendation rule) có validation trước publish ([quality-gates.md](../quality/quality-gates.md)). Subsystem mới phải trả lời 5 câu: *Nếu nó chết cái gì còn chạy? Mất data không? Retry được không? Quan sát được lỗi không? Rollback được không?*

## Trace

REQ-NFR-01..12 → §1–§16 · REQ-SEC-01..04 → §9.