# Hướng Dẫn Đọc System Requirement (mọi role)

> **Dành cho:** bất kỳ ai cần đọc một `System-Requirement_v{N}.md` — PM, Comtor, BrSE, Tester, Dev, Tech Lead. Mục tiêu của tài liệu này: giúp bạn biết **mình cần đọc phần nào**, đọc xong hiểu đúng, không cần đọc code hay đọc hết mọi dòng.
> **Tài liệu được đọc:** `AK-Docs/02.BA-Specs/00.Requirements/[functionId]/System-Requirement_v{N}.md`, sinh ra bởi task type **"📐 Create System Requirement"** — cầu nối giữa UC Spec (BA) và code (Dev).
> **Nếu bạn là người duyệt (approve)** tài liệu này, xem thêm Mục 5 (Checklist) — phần còn lại của guide vẫn áp dụng, checklist chỉ là bước cuối.

---

## 1. Ai đọc phần nào

Mỗi `System-Requirement_v{N}.md` đã có sẵn bảng này ngay ở đầu file (nói 1 lần, không lặp lại theo từng dòng). Nhắc lại ở đây để bạn không cần mở file mới nhớ ra:

| Field trong tài liệu | Ai cần đọc |
|---|---|
| `Requirement` | PM/BrSE/Comtor, Tester |
| `System Behavior` | Tester |
| `Error Response` | Tester (đầy đủ, gồm HTTP code) — PM/BrSE/Comtor chỉ cần câu thông báo hiển thị |
| `Traced UC Ref` / `Traced UC BR` / `Traced Exception Flow` | PM/BrSE/Comtor (đối chiếu UC Spec) |
| `Classification` | PM/BrSE/Comtor — dấu hiệu "cần quyết định" hoặ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.** Nếu bạn là PM/Comtor/BrSE và thấy 1 dòng `Implementation Reference` mình không hiểu — đó là bình thường, **bỏ qua**, không phải bạn thiếu kiến thức.

---

## 2. Cách đọc 1 item (Requirement/System Behavior/Implementation Reference)

`System-Requirement_v{N}.md` được thiết kế theo 3 tầng, mỗi tầng cho 1 nhóm người đọc khác nhau trong **cùng một item**:

| Tầng | Viết bằng | Dành cho | Bạn cần đọc? |
|---|---|---|---|
| **Requirement** | Ngôn ngữ nghiệp vụ, không có tên class/method/framework | PM, Comtor, BrSE, **Tester** | ✅ Luôn đọc |
| **System Behavior** | Vẫn ngôn ngữ thường, mô tả điều kiện/thứ tự xử lý | BA, Tester | ✅ Luôn đọc |
| **Error Response** | HTTP code + message hiển thị cho end-user | Tester | ✅ Đọc nếu là Validation/Exception |
| **Implementation Reference / Tech Reference** | file:line, class, method, enum | Dev | ❌ **Bỏ qua được** — không phải Dev thì không cần đọc |

**Nguyên tắc:** nếu bạn phải đọc `Implementation Reference` để hiểu `Requirement` đang nói gì, đó là **lỗi của tài liệu** (leak kỹ thuật lên tầng nghiệp vụ) — báo lại cho Dev viết lại, không phải bạn thiếu kiến thức.

---

## 3. Giải thích về Classification

Mỗi item (FR/NFR/VR/ER) có thể mang 1 trong 4 nhãn `Classification`.

| Nhãn | Nghĩa | Ai tạo ra | Hành động bạn cần làm |
|---|---|---|---|
| **Gap** | UC Spec chưa có nội dung này | Dev, khi viết tài liệu | PM/BA phải trả lời. **Còn Gap chưa trả lời → tài liệu chưa được approve.** |
| **Assumption** | Dev suy đoán, chưa ai xác nhận | Dev | PM confirm → thành Decision. PM reject → quay lại Gap |
| **Decision** | Đã chốt, có ngày và người chốt | Sau khi PM trả lời | Chỉ đọc, không cần hành động |
| **Deviation** | Code hiện tại khác UC Spec | Dev, khi so sánh với code thật | BA/PM chọn: sửa code theo UC Spec, hoặc sửa UC Spec theo code |

### Khi 1 item có nhiều quyết định — cách đọc

Trường hợp 1 item có **2+ quyết định** liên quan (ví dụ BA chốt 1 phần, Dev chốt phần còn lại). Ví dụ:

```
Classification: Gap → Decision
  - OQ-35 (BA): sử dụng mã lượt đặt hàng để xác định yêu cầu đặt hàng trùng và tránh tạo đơn nhiều lần.
  - D-03 (Dev): nếu mã lượt đặt hàng đã được xử lý, không tạo đơn mới; trả về HTTP 400 kèm đơn đã tạo trước đó. Mã có hiệu lực trong 30 phút.
```

Cách đọc: mỗi dòng là **1 mã số + ai chốt + nội dung ngắn**.
- `OQ-xx` = quyết định gốc do BA chốt, kế thừa từ UC Spec (thường trong lúc Q&A trước khi UC Spec được ký duyệt).
- `D-xx` = quyết định phát sinh riêng khi Dev soạn tài liệu System Requirement này (ví dụ: UC Spec chốt "phải chống trùng đơn" nhưng chưa viết rõ máy chủ trả gì — Dev phải tự chốt thêm chi tiết kỹ thuật đó, ghi lại thành D-xx để không tự quyết ngầm).

Nếu bạn không nhớ hoặc không đồng ý với 1 trong các quyết định đó, nêu lại ngay — đừng chờ tới khi ra sản phẩm.

---

## 4. Workflow trạng thái Classification

```mermaid
%%{init: {'flowchart': {'curve': 'linear'}}}%%
flowchart TD
    Start([Dev viết draft]) --> Gap[Gap]
    Gap -->|"PM/BA trả lời chắc chắn"| Decision[Decision]
    Gap -->|"PM/BA trả lời<br/>nhưng chưa chắc 100%"| Assumption[Assumption]
    Assumption -->|"PM confirm đúng"| Decision
    Assumption -->|"PM reject / cần hỏi lại"| Gap
    Decision -->|"sau này Dev thấy<br/>code thực tế khác"| Deviation[Deviation]
    Deviation -->|"PM chọn sửa code<br/>theo UC Spec (đã fix xong)"| Decision
    Deviation -->|"PM chọn giữ code, sửa UC Spec<br/>(BA cập nhật UC Spec, tăng version mới)"| Decision
```

**Rule:** tài liệu **không được approve** khi còn item ở trạng thái `Gap` chưa trả lời. `Assumption` được phép tồn tại tạm nếu PM đã xác nhận "tạm chấp nhận, sẽ chốt sau" — nhưng phải ghi rõ trong Mục 8 (Decision Log), không được im lặng bỏ qua.

---

## 5. Checklist Review (dành cho người duyệt — không cần đọc code)

Làm theo đúng thứ tự — dừng và reject ngay khi 1 bước fail.

### Bước 1 — Đọc Executive Summary (30 giây)
- [ ] `Traceability coverage` = X/X? Thiếu → tài liệu chưa đầy đủ, trả lại Dev.
- [ ] `Action needed from PM` có danh sách → đây là Gap/Assumption bạn phải trả lời **trước**, ngay tại bước này.

### Bước 2 — Khớp 1-1 với UC Spec (Mục 0 — Traceability Matrix)
- [ ] Mở UC Spec `v{N}` ghi ở header song song.
- [ ] Mỗi Main/Alternative/Exception Flow, mỗi Business Rule trong UC Spec → tìm đúng 1 dòng tương ứng trong Traceability Matrix.
- [ ] Thiếu dòng nào → **reject**.

### Bước 3 — Đọc tầng Requirement (Mục 1–4)
- [ ] Chỉ đọc `Requirement` + `System Behavior` — bỏ qua `Implementation Reference`.
- [ ] Thấy tên class/method/framework lọt vào `Requirement`/`System Behavior` → **reject**, yêu cầu viết lại.
- [ ] Với Validation/Exception: `Error Response` phải giữ HTTP code + message hiển thị.

### Bước 4 — Xử lý từng nhãn Classification
- [ ] `Gap`/`Assumption` → trả lời theo workflow ở Mục 4.
- [ ] `Deviation` → chọn rõ: sửa code hay sửa UC Spec — không để lơ lửng.
- [ ] `Decision` → chỉ xác nhận đúng là điều đã chốt; không nhớ đã chốt → hỏi lại, đừng mặc định đúng.

### Bước 5 — Đối chiếu Mục 7 (Assumptions/Gaps/Decisions/Deviations)
- [ ] Mọi item có nhãn ở Mục 1–4 phải có dòng tương ứng ở Mục 7. Thiếu → reject.

### Bước 6 — Quyết định
- [ ] Còn `Gap` chưa trả lời → **không approve**.
- [ ] Pass hết Bước 1–5 → gõ `APPROVED`.

---

## 6. Câu hỏi thường gặp (FAQ)

### System Requirement để làm gì? Tôi có UC Spec rồi thì cần gì System Requirement nữa?

UC Spec và System Requirement trả lời 2 câu hỏi khác nhau:

- **UC Spec (BA viết)** trả lời: *"hệ thống PHẢI làm gì theo mong muốn của khách/nghiệp vụ?"* — viết **trước khi** biết chắc code hiện tại đang làm gì, không cần Dev tham gia để ký duyệt.
- **System Requirement (Dev viết, sau khi đọc UC Spec + mở code thật ra đối chiếu)** trả lời: *"code hiện tại đã làm đúng chưa? Còn thiếu gì? Có tình huống nào UC Spec không viết tới nhưng hệ thống vẫn phải xử lý?"*

Ví dụ thật trong tài liệu BUY074: UC Spec chỉ viết "chống bán vượt tồn kho", nhưng KHÔNG viết tới tình huống "2 khách đặt cùng 1 sản phẩm cùng lúc thì ai thắng, ai thua, giỏ của người thua xử lý sao, có bị deadlock không nếu đơn có nhiều sản phẩm giao nhau". Đây là những **Gap** mà chỉ khi Dev đọc code + tưởng tượng ra kịch bản thật mới phát hiện được — BA khi viết UC Spec không có đủ góc nhìn kỹ thuật để lường trước. System Requirement chính là nơi những Gap này được phát hiện, hỏi lại BA/PM, và ghi lại chốt là gì.

Nói ngắn: **UC Spec = ý định. System Requirement = ý định đó khi va vào code thật thì phải cụ thể hoá ra sao.**

### Vì sao không gộp UC Spec và System Requirement thành 1 tài liệu, review 1 lần cho gọn?

3 lý do:

1. **Thời điểm ký duyệt khác nhau.** UC Spec phải được BA/PM ký duyệt **trước**, không cần chờ Dev có thời gian đọc hết code. Nếu gộp 2 tài liệu, UC Spec sẽ bị kẹt chờ Dev investigate code xong mới ký được — làm chậm cả quy trình dù bản chất nghiệp vụ đã rõ và có thể duyệt độc lập với chi tiết kỹ thuật.
2. **Người review và tiêu chí review khác nhau.** Review UC Spec cần Dev đánh giá "khả thi kỹ thuật ở mức khái niệm" + Tester đánh giá "khả năng test được ở mức khái niệm". Review System Requirement cần Dev + Tester **đối chiếu từng dòng với UC Spec** (khác câu hỏi, khác độ chi tiết) — trộn 2 việc vào 1 lần review dễ khiến người review làm qua loa 1 trong 2, thay vì làm kỹ cả 2.
3. **Traceability rõ ràng hơn khi tách riêng.** Mỗi `System-Requirement_v{N}` phải matching đúng 1 phiên bản UC Spec (`UC-Spec-Version` header) — nếu 2 tài liệu là một, việc UC Spec đổi version (do yêu cầu nghiệp vụ đổi) và System Requirement đổi version (do Dev phát hiện thêm case khi code) sẽ lẫn vào nhau, khó biết cái gì đổi vì lý do gì.

**Nhưng:** Dự án có thể linh hoạt sắp xếp gộp 1 buổi review chung cho 2 tài liệu này, trong trường hợp có thể output 2 tài liệu cùng nhau thay vì phải chờ 1 khoảng thời gian dài để Dev điều tra.

### System Requirement có được phép thay đổi/thêm nội dung so với UC Spec không?

Không. System Requirement **không bao giờ bịa ra** nội dung mà UC Spec không có — mọi FR/VR/ER phải trace được về 1 dòng cụ thể trong UC Spec, hoặc được đánh dấu `Gap`/`Assumption`/`Deviation` và chờ PM/BA xác nhận. Nếu bạn thấy 1 `Requirement` mà không tìm được nguồn trong UC Spec, đó là lỗi — báo lại ngay (xem Bước 2/3 ở Mục 5).

### Khi nào cần viết lại/update System Requirement?

Hai trường hợp: (1) UC Spec lên version mới (BA sửa yêu cầu) → System Requirement phải `RESYNC` theo version mới; (2) trong lúc code 1 ticket, Dev phát hiện 1 case UC Spec có viết nhưng System Requirement bỏ sót → được đề xuất bổ sung, ghi thêm 1 dòng ở Change Log (Mục 9), không cần tăng version vì UC Spec chưa đổi.

### Mục 8 (Decision Log) chỉ có 1 dòng ngắn — thiếu thông tin à?

Không thiếu — chủ ý tránh viết trùng 2 nơi. Chi tiết đầy đủ đã nằm trong dòng `Classification` của item tương ứng ở Mục 1–4; Mục 8 chỉ là bảng tra cứu ngược (ID → ai chốt → ngày → 1 dòng tóm tắt).

### Tôi không hiểu `Implementation Reference` ghi gì, có sao không?

Tuỳ role. Nếu bạn là **PM/BrSE/Comtor/Tester** — không sao, tầng đó không dành cho bạn (xem Mục 1, 2); nếu bạn *cần* hiểu nó để đánh giá đúng/sai của `Requirement`, đó là lỗi tài liệu — báo lại, đừng tự trách mình thiếu kiến thức.

Nếu bạn là **Dev** — **bắt buộc phải hiểu**, vì đây chính là field ghi cho bạn (file:line/class/method để code) và AI cũng dựa vào nó ở Gate 3 coding. Không hiểu được thì không phải lỗi của bạn cần bỏ qua, mà là dấu hiệu tài liệu viết thiếu rõ (ví dụ thiếu context, path sai, hoặc tham chiếu tới code không còn tồn tại) — cần hỏi lại người viết (Dev khác/AI) hoặc tự mở code kiểm tra trước khi bắt đầu implement, không được đoán.

### `Tech Reference` trong Mục 6.2 (Glossary) khác gì `Implementation Reference`?

`Implementation Reference` nằm rải trong từng item, chỉ Dev cần. `Tech Reference` ở Mục 6.2 là **bảng tra cứu tập trung** — mỗi giá trị kỹ thuật (ví dụ enum `TagStatusEnum::PENDING`) map sang 1 ý nghĩa nghiệp vụ đã được PM xác nhận (`Decision`) hoặc chưa (`Assumption`). Dùng bảng này khi muốn biết "giá trị thô này nghĩa là gì với nghiệp vụ" mà không cần lục từng item.

### Tài liệu này có thay UC Spec không?

Không. UC Spec là nguồn nghiệp vụ gốc (BA sign-off). System Requirement là bản dịch sang góc nhìn Dev + trace lại UC Spec.

---

## 7. Liên quan

- Skill sinh ra tài liệu này: `.claude/skills/create-system-requirement/SKILL.md`
- Template: `.claude/skills/create-system-requirement/system-requirement-template-v1.md`
- Cấu trúc thư mục `02.BA-Specs/`: [BA-Specs-Structure.md](./BA-Specs-Structure.md)
- Quy trình SDLC end-to-end (Checkpoint #2/#3, gộp thread review): `docs/internal/SDLC-Unified-Workflow_v1.0.md`