# Template Yêu Cầu Hệ Thống (System Requirement) — Phiên bản v1

Đây là cấu trúc chuẩn cho tài liệu **System Requirement**.

Mỗi tài liệu System Requirement phải **trace 1-1 với một phiên bản UC Spec cụ thể**. Không tự bổ sung hoặc suy diễn nội dung nếu nội dung đó không có căn cứ từ UC Spec.

---

# Tài Liệu Yêu Cầu Hệ Thống: [functionId] — [Tên Chức Năng]

**Ngày tạo (Date):** [YYYY-MM-DD]

**Phiên bản System Requirement (System-Requirement-Version):** v{N}

**Phiên bản UC Spec tham chiếu (UC-Spec-Version):** [functionId] @ v{N}

<!-- BẮT BUỘC — mốc khớp 1-1 -->

**UC Spec nguồn (Source UC Spec):**
AK-Docs/02.BA-Specs/04.UC-Specs/[functionId]/UC-Spec_v{N}.md

---

## Ai cần đọc phần nào?

| Field                                         | Ai cần đọc                                                                                                          |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `Requirement`                                 | PM/BrSE/Comtor, Tester                                                                                              |
| `System Behavior`                             | Tester                                                                                                              |
| `Error Response`                              | Tester đọc đầy đủ, bao gồm cả HTTP code. PM/BrSE/Comtor chỉ cần đọc câu thông báo hiển thị, có thể bỏ qua HTTP code |
| `Traced UC Ref` (Mục 1, 2)                    | PM/BrSE/Comtor dùng để đối chiếu với UC Spec — trỏ tới bước Main/Alternative Flow hoặc Business Rule domain nguồn   |
| `Traced UC BR` (Mục 3)                        | PM/BrSE/Comtor dùng để đối chiếu với UC Spec — trỏ tới số Business Rule cụ thể mà Validation Rule dịch ra từ đó     |
| `Traced Exception Flow` (Mục 4)               | PM/BrSE/Comtor dùng để đối chiếu với UC Spec — trỏ tới Exception Flow cụ thể mà Error Handling xử lý                |
| `Classification`                              | PM/BrSE/Comtor dùng để nhận biết nội dung nào **cần quyết định** hoặc **đã được chốt**                              |
| `Implementation Reference` / `Tech Reference` | Dev                                                                                                                 |
| Mục 5 (Acceptance Test Scenarios)             | Tester                                                                                                              |

> **Dev và AI đọc toàn bộ tài liệu**, không phân biệt theo field.
>
> * Dev cần đầy đủ thông tin để triển khai.
> * AI sử dụng tài liệu ở nhiều gate khác nhau, ví dụ: coding Gate 3, sinh testcase và audit traceability.
>
> Bảng trên chủ yếu giúp PM/BrSE/Comtor và Tester biết phần nào cần tập trung đọc, và phần nào có thể bỏ qua nếu không liên quan trực tiếp đến công việc của mình.

---

## Tóm tắt điều hành (Executive Summary)

Phần này giúp người đọc nhanh chóng nắm được phạm vi tài liệu, mức độ hoàn thiện và những điểm cần quyết định trước khi chuyển sang triển khai.

* **Mục đích (Purpose):**
  [1 câu — tài liệu này bao gồm những gì và vì sao tài liệu này được tạo]

* **Tình trạng triển khai (Implementation status):**
  [ví dụ: Chưa bắt đầu / Đang triển khai / Khớp với UC Spec v{N}]

* **Độ khớp truy vết (Traceability coverage — từ audit Step 3.5):**
  [X]/[Y] mục UC Spec đã có System Requirement tương ứng · [Z] item bị gỡ vì không có căn cứ (unsupported)

* **Các sai khác chính so với UC Spec (Key deviations from UC Spec):**
  [danh sách các mục được gắn nhãn Deviation, hoặc "Không phát hiện sai khác"]

* **Hành động cần từ PM (Action needed from PM):**
  [danh sách các Gap/Assumption chưa được giải quyết cần PM xác nhận, hoặc "Không có — sẵn sàng chuyển giao cho Dev"]

---

## 0. Ma trận truy vết (Traceability Matrix)

Bảng này giúp đối chiếu trực tiếp giữa UC Spec và các mục tương ứng trong System Requirement.

| Tham chiếu UC (Flow / BR) | Mục System Requirement tương ứng |
| ------------------------- | -------------------------------- |
| Main Flow bước 3          | FR-01                            |
| Exception Flow B          | FR-05, ER-02                     |
| BR1.1                     | VR-01                            |

---

## 1. Yêu Cầu Chức Năng (Functional Requirements)

Mỗi Functional Requirement được mô tả theo 3 tầng, từ dễ hiểu đến chi tiết kỹ thuật:

1. **Requirement**: mô tả hệ thống cần đáp ứng điều gì bằng ngôn ngữ nghiệp vụ.
2. **System Behavior**: mô tả hệ thống xử lý như thế nào để đáp ứng Requirement.
3. **Implementation Reference**: thông tin kỹ thuật để Dev tham chiếu khi triển khai.

`Implementation Reference` chỉ chứa thông tin kỹ thuật và **không được đưa ngược lên Requirement hoặc System Behavior**.

### FR-01: [tên ngắn gọn mô tả hành vi nghiệp vụ]

* **Requirement:**
  [hành vi hệ thống bằng ngôn ngữ nghiệp vụ, không dùng tên framework/class/method]

* **System Behavior:**
  [hệ thống xử lý như thế nào — điều kiện, thứ tự kiểm tra]

* **Traced UC Ref:** Main Flow #3

* **Classification:**
  [Gap | Assumption | Decision | Deviation — bỏ dòng này nếu là một fact đơn thuần]

* **Implementation Reference:**
  [file:line / class / method — 1 câu, không diễn giải dài; Dev đọc code trực tiếp khi cần chi tiết hơn]

<!-- lặp lại FR-02, FR-03, ... theo cùng cấu trúc trên -->

---

## 2. Yêu Cầu Phi Chức Năng (Non-Functional Requirements)

Phần này mô tả các yêu cầu không trực tiếp thuộc nghiệp vụ chức năng, ví dụ như performance hoặc security.

### NFR-01: [tên ngắn]

* **Requirement:**
  [ngôn ngữ nghiệp vụ — ví dụ: yêu cầu về performance/security]

* **System Behavior:**
  [cách yêu cầu này được thực thi, bằng ngôn ngữ đơn giản]

* **Traced UC Ref:** BR3.1

* **Classification:**
  [Gap | Assumption | Decision | Deviation — bỏ nếu là fact đơn thuần]

* **Implementation Reference:**
  [file:line / class / method]

---

## 3. Quy Tắc Nghiệp Vụ → Quy Tắc Kiểm Tra Hợp Lệ (Business Rules → Validation Rules)

Phần này chuyển các Business Rules trong UC Spec thành Validation Rules mà hệ thống thực hiện.

### VR-01: [tên ngắn]

* **Requirement:**
  [ví dụ: "Tên Tag phải là duy nhất trong số các Tag đang active."]

* **System Behavior:**
  [ví dụ: "Hệ thống kiểm tra tên Tag với toàn bộ Tag đang active trước khi lưu."]

* **Error Response:**
  HTTP 422 (Validation Error) — "[thông báo hiển thị cho người dùng]"

* **Traced UC BR:** BR1.1

* **Classification:**
  [Gap | Assumption | Decision | Deviation — bỏ nếu là fact đơn thuần]

* **Implementation Reference:**
  [ví dụ: `Rule::unique(...)` trong `StoreTagRequest`]

---

## 4. Xử Lý Ngoại Lệ & Lỗi (Exception & Error Handling)

Phần này mô tả các trường hợp hệ thống không thể tiếp tục xử lý theo Main Flow, bao gồm điều kiện xảy ra, cách hệ thống phản hồi và thông báo trả về.

### ER-01: [điều kiện kích hoạt, bằng ngôn ngữ nghiệp vụ]

* **Requirement:**
  [ví dụ: "Chỉ người dùng có quyền CREATE mới được tạo Tag."]

* **System Behavior:**
  [ví dụ: "Request bị từ chối vì người gọi không có quyền cần thiết."]

* **Error Response:**
  HTTP 403 (Forbidden) — "[thông báo hiển thị cho người dùng]"

* **Traced Exception Flow:** Exception Flow B

* **Classification:**
  [Gap | Assumption | Decision | Deviation — bỏ nếu là fact đơn thuần]

* **Implementation Reference:**
  [error code/class/middleware hiện có]

---

## 5. Kịch Bản Kiểm Thử Chấp Nhận (Acceptance Test Scenarios)

Phần này mô tả các kịch bản mà Tester sử dụng để xác nhận hệ thống đáp ứng các yêu cầu đã được định nghĩa.

### AT-01: [Tên kịch bản] (Main Flow)

* **Given** ...
* **When** ...
* **Then** ...
* **Requirement Coverage:** FR-01, FR-03

### AT-02: [Tên kịch bản] (Exception Flow B)

* **Given** ...
* **When** ...
* **Then** ...
* **Requirement Coverage:** VR-01, ER-01

---

## 6. Bối Cảnh Hệ Thống Hiện Có (Existing System Context)

Phần này giúp người đọc hiểu nhanh các khu vực liên quan trong hệ thống hiện tại.

Không đưa chi tiết triển khai sâu vào đây. Các thông tin kỹ thuật chi tiết phải được đặt trong **Implementation Reference** của từng item tương ứng.

### 6.1 Tổng Quan Các Khu Vực Hệ Thống (System Areas Summary)

Chỉ tóm tắt các khu vực có liên quan.

| Khu vực (Area) | Tóm tắt (Summary) |
| -------------- | ----------------- |
| API            | ...               |
| Model          | ...               |
| Validation     | ...               |
| Migration      | ...               |
| Test           | ...               |

### 6.2 Bảng Thuật Ngữ / Ánh Xạ Thuật Ngữ (Glossary / Term Mapping)

Mỗi `Tech Reference:` được sử dụng trong Mục 1–4 phải có một dòng tương ứng tại đây.

Mục đích là tạo **một nơi duy nhất để tra cứu** mối liên hệ giữa thuật ngữ nghiệp vụ và Technical Reference trong code, thay vì phải tìm lại từng item.

Chỉ đưa vào bảng:

* Thuật ngữ đã được PM xác nhận ý nghĩa nghiệp vụ thông qua `Decision`.
* Giá trị thô chưa được PM xác nhận nhưng đã được gắn `Classification` tương ứng.

Không tự suy đoán ý nghĩa nghiệp vụ.

| Thuật Ngữ Nghiệp Vụ (Business Term)    | Tham Chiếu Kỹ Thuật (Technical Reference) | Classification                                                  |
| --------------------------------------- | ------------------------------------------ | ----------------------------------------------------------------- |
| [ví dụ: "trạng thái mặc định PENDING"] | `TagStatusEnum::PENDING`                  | Decision (PM xác nhận ngày [date]) / Assumption (chưa xác nhận) |

### 6.3 Giao Diện Với Hệ Thống Ngoài (External System Interfaces)

*(Tùy chọn — chỉ có khi UC này tích hợp với hệ thống bên ngoài UI/DB của app, ví dụ third-party API, webhook, message queue)*

UC Spec chủ yếu mô tả luồng UI và nghiệp vụ. Nếu chức năng có giao tiếp với hệ thống bên ngoài, thông tin tích hợp được ghi nhận tại đây.

Nếu UC không có giao diện bên ngoài thì bỏ hẳn mục này.

| Giao diện (Interface)        | Chiều (Direction) | Protocol/Format | Ghi chú (Note) |
| ----------------------------- | ------------------ | ---------------- | -------------- |
| [ví dụ: Payment Gateway API] | Outbound           | REST/JSON        | ...            |

---

## 7. Giả Định / Điểm Thiếu / Quyết Định / Sai Khác (Assumptions / Gaps / Decisions / Deviations)

Chỉ các item được gắn nhãn `Gap`, `Assumption`, `Decision` hoặc `Deviation` mới xuất hiện tại đây.

Các fact đơn thuần không cần đưa vào bảng này vì đó là trạng thái mặc định của các item trong Mục 1–4.

| Loại (Type) | Item | Cách xử lý (Resolution) |
| ----------- | ---- | ----------------------- |

---

## 8. Nhật Ký Quyết Định (Decision Log)

Đây là bảng tra cứu ngắn gọn, giúp tìm ngược từ ID quyết định đến người chốt, ngày chốt và nội dung chính.

Không cần diễn giải lại đầy đủ câu hỏi và câu trả lời vì chi tiết đã được ghi tại `Classification` của item tương ứng trong Mục 1–4.

| ID    | Người chốt | Ngày         | Tóm tắt                                                     |
| ----- | ---------- | ------------ | ----------------------------------------------------------- |
| OQ-xx | PM/BA      | [YYYY-MM-DD] | [1 dòng — chi tiết đầy đủ xem tại item tương ứng ở Mục 1–4] |

Quy tắc:

* `OQ-xx` / `D-xx` đã có câu trả lời thì ghi tại đây.
* Gap chưa được giải quyết vẫn phải ghi tại Mục 7.
* Không đưa Gap chưa có quyết định vào Decision Log.

---

## 9. Nhật Ký Thay Đổi (Change Log)

| Ngày (Date)  | Ticket | Thay đổi (Change)           | Ghi chú (Note) |
| ------------ | ------ | --------------------------- | -------------- |
| [YYYY-MM-DD] | —      | Tạo lần đầu từ UC Spec v{N} |                |