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, NOT_FOUND, CONFLICT, 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). 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.