#08 – Thiết kế API

Giai đoạn: Thiết kế hệ thống · Phiên bản 0.1 – 29/10/2026

Mức tổng quan để chốt hợp đồng giữa frontend và backend. Đặc tả chi tiết sẽ được sinh tự động dạng OpenAPI 3.1 từ mã nguồn (NFR-MAINT-01).

#1. Quy ước chung

#Mã lỗi nghiệp vụ chính

#2. API cho học sinh

#2.1 Tài khoản & kích hoạt

POST /api/v1/activations
Idempotency-Key: 7c1f...
{ "code": "k7xq-m4pa-r9" }

201 Created
{
  "book": { "id": "b-toan-27", "title": "Ôn thi TNTHPT Toán", "edition": "2027", "subject": "MATH" },
  "entitlement": { "validTo": "2027-09-30T23:59:59+07:00" }
}

#2.2 Phân giải ID

GET /api/v1/codes/tv012

200 OK
{ "code": "TV012", "kind": "EXAMPLE", "resourceId": "r-123", "bookId": "b-toan-27",
  "path": "/vi-du/r-123", "printedPage": 87 }

403 Forbidden
{ "error": { "code": "NOT_ENTITLED", "details": { "bookId": "b-toan-27", "bookTitle": "Ôn thi TNTHPT Toán 2027" } } }

404 Not Found
{ "error": { "code": "CODE_NOT_FOUND", "details": { "normalized": "TV999", "suggestions": ["TV099"] } } }

#2.3 Học liệu

#2.4 Làm bài & kết quả

PATCH /api/v1/attempts/a-789/answers
{
  "answers": [
    { "questionId": "q-1", "response": "B", "timeSpentMs": 41200, "clientUpdatedAt": "2026-11-28T20:15:03.120+07:00" },
    { "questionId": "q-14", "response": { "a": true, "b": false, "c": true, "d": true } },
    { "questionId": "q-19", "response": "-1,5", "flagged": true }
  ]
}

200 OK
{ "savedAt": "2026-11-28T20:15:03.410+07:00", "deadlineAt": "2026-11-28T21:30:00+07:00" }

POST /api/v1/attempts/a-789/submit

200 OK
{
  "score": 7.25, "maxScore": 10, "submitType": "MANUAL", "durationSec": 4680,
  "sections": [
    { "title": "Phần I", "score": 2.5, "max": 3 },
    { "title": "Phần II", "score": 2.75, "max": 4 },
    { "title": "Phần III", "score": 2.0, "max": 3 }
  ],
  "summary": { "correct": 14, "wrong": 6, "blank": 2 },
  "recommendations": [
    { "tag": { "id": "t-nh", "name": "Nguyên hàm – Tích phân" }, "errorRate": 0.67,
      "resources": [ { "kind": "THEORY", "code": "TL021", "resourceId": "r-21" },
                     { "kind": "EXERCISE_SET", "code": "TB021", "resourceId": "r-77" } ] }
  ]
}

#2.5 Lịch sử & tiến bộ

#2.6 Thương mại (P3)

#2.7 Sự kiện

#3. API cho giáo viên

#4. API cho CMS & quản trị (/admin)

#5. Tích hợp ngoài (cần xác nhận với đối tác)