# SRS — <US-id> <Tên User Story>

| | |
|---|---|
| **Version** | 1.0 |
| **Date** | YYYY-MM-DD |
| **Author** | <BA> (skill ba-3-specification) |
| **Status** | 🟡 Draft |
| **Approved by** | PO: — · Tech Lead: — · QA: — · Designer: — *(chỉ khi PRODUCT = screen)* |
| **Source** | BACKLOG_… v1.0 · BR_… v1.0 · RBAC_… v1.0 · IMPACT_… v1.0 · UICONV_… v1.0 *(screen)* |
| **Scope** | US-0nn |
| **Profile** | `screen · brownfield · standard` *(PRODUCT · LIFECYCLE · RIGOR)* |
| **Biến thể PART 2** | `srs-part2/screen.md` |
| **Ngôn ngữ hiển thị** | VI / EN / KO *(N/A nếu PRODUCT không có giao diện)* |

## Change Log

| Version | Date | Người sửa | Thay đổi | CR |
|---|---|---|---|---|
| 1.0 | | | Bản đầu | — |

> **Quy ước đọc tài liệu này** *(quy tắc W11 — chỉ áp dụng khi `PRODUCT = screen`)*
> Bảng thành phần quyết định **một phần tử có tồn tại hay không** và **nó hành xử thế nào**.
> `WF_<US>.md` + `.html` (và prototype nó tham chiếu) quyết định **nó nằm ở đâu, to bằng nào,
> trông ra sao ở từng trạng thái**. `UICONV_<PROJECT>.md` quyết định **quy ước chung** (phân
> trang, toast, định dạng) — tài liệu này chỉ ghi phần khác. Khi mâu thuẫn: bảng thắng về sự
> tồn tại và hành vi, WF thắng về bố cục — và mâu thuẫn đó phải có dòng ở `WF` §5.

---

## PHẦN 1 — NGHIỆP VỤ

### 1.1 Tóm tắt cho người quyết định

*Ba câu, ngôn ngữ nghiệp vụ. Không tên bảng dữ liệu, không tên component.*

| | |
|---|---|
| **US này giải quyết** | RQ-0nn: … |
| **Người dùng được gì** | |
| **Khác hiện tại chỗ nào** | |

### 1.2 Vai trò và quyền

| Vai trò | Được làm gì trong US này | Không được làm gì | RBAC |
|---|---|---|---|

### 1.3 Business rule áp dụng

*Tham chiếu, không chép lại. Chép lại là tạo ra hai nguồn sự thật.*

| BR | Phát biểu ngắn | Áp dụng ở màn hình/field nào | Khi vi phạm |
|---|---|---|---|
| BR-021 | | | Chặn → `E-STL-0001` |

### 1.4 Vòng đời trạng thái *(nếu có)*

| Nguồn | Sự kiện | Điều kiện | Đích | Ai được làm | BR |
|---|---|---|---|---|---|

### 1.5 Ngoài phạm vi *(quy tắc W12)*

*Những gì người đọc có thể tưởng là có nhưng không có, và xử lý ở đâu.*

| # | Không làm gì | Vì sao | Xử lý ở đâu/khi nào |
|---|---|---|---|

---

## PHẦN 2 — ĐẶC TẢ SẢN PHẨM

> 🔴 **Phần này thay đổi theo `PRODUCT` trong profile.** Nạp đúng một (hoặc nhiều) biến thể
> dưới đây rồi chèn nội dung vào chỗ này — đừng viết PART 2 từ đầu.

| `PRODUCT` | Biến thể nạp | PART 2 mô tả gì |
|---|---|---|
| `screen` | [`srs-part2/screen.md`](srs-part2/screen.md) | Màn hình, bảng thành phần, bảng field, trạng thái rỗng |
| `api-service` | [`srs-part2/api-service.md`](srs-part2/api-service.md) | Người tiêu thụ, khả năng, hợp đồng dữ liệu, tương thích ngược |
| `data-pipeline` | [`srs-part2/data-pipeline.md`](srs-part2/data-pipeline.md) | Luồng dữ liệu, data contract, chất lượng, đối soát nguồn–đích |
| `ml-model` | [`srs-part2/ml-model.md`](srs-part2/ml-model.md) | Bài toán, nhãn, metric + ngưỡng, fallback, drift |
| `batch-job` | [`srs-part2/batch-job.md`](srs-part2/batch-job.md) | Job, lịch, idempotency, thất bại giữa chừng, cảnh báo |
| `process-only` | — | Không có PART 2 — nội dung nằm ở `PROCESS` của GĐ2 |

**Một US thường có nhiều loại** (màn hình + API, hoặc màn hình + job đêm). Khi đó nạp nhiều
biến thể, mỗi biến thể một mục con: `2.A Màn hình` · `2.B API` · `2.C Job`. Ghi rõ đã nạp
biến thể nào vào dòng **Biến thể PART 2** ở header.

Chọn `PRODUCT` thế nào: [domain-profiles.md §1](../../ba-lifecycle/references/domain-profiles.md).

🔴 Loại chưa có biến thể (nhúng / IoT / firmware) ⇒ **nói rõ với người dùng là phải tự viết
PART 2**, đừng nhét vào biến thể gần đúng nhất.

*(chèn nội dung biến thể vào đây)*

---

## PHẦN 3 — TIÊU CHÍ NGHIỆM THU

*Chi tiết ở `AC_<US>.md`, hoặc viết trực tiếp ở đây theo mẫu `templates/acceptance-criteria.md`.*

| AC | Nhóm | Tóm tắt | Field/Thành phần | BR | Test case (QA điền) |
|---|---|---|---|---|---|
| AC-01 | Thành công | | | | |
| AC-05 | Validation | | | | |
| AC-09 | Lỗi hệ thống | | | | |
| AC-12 | Phân quyền | | | | |

**Mỗi US phải có đủ bốn nhóm.** Chỉ có nhóm "Thành công" ⇒ spec chưa viết xong.

---

## PHẦN 4 — MÃ LỖI VÀ TEXT HIỂN THỊ

### 4.1 Mã lỗi

| Mã | Khi nào xảy ra | Thông điệp hiển thị (nguyên văn) | Hiển thị ở đâu | Người dùng làm gì tiếp | BR/AC |
|---|---|---|---|---|---|
| `E-STL-0001` | Mã cửa hàng đã tồn tại | "Mã cửa hàng này đã được sử dụng. Vui lòng nhập mã khác." | Dưới field F01 | Sửa mã | BR-021 |

Đặt mã theo `E-<DOMAIN>-<4 số>`. **Không tái sử dụng mã.** Dự án đã có dãy mã ⇒ dùng tiếp số.

### 4.2 Text màn hình *(chỉ khi có giao diện cho người)*

`PRODUCT` không có giao diện ⇒ ghi "N/A — không có text hiển thị", **đừng xoá mục**.
Với `api-service` và `batch-job`, phần tương đương là **thông điệp trả cho người gọi /
nội dung cảnh báo vận hành** — đặc tả ở PART 2 của biến thể tương ứng.

| Khoá | Ngữ cảnh | VI | EN | KO | Giới hạn ký tự |
|---|---|---|---|---|---|

### 4.3 Định dạng hiển thị *(chỉ khi có giao diện cho người)*

| Loại dữ liệu | Định dạng | Ví dụ | Ghi chú |
|---|---|---|---|
| Ngày | `dd/MM/yyyy` | 30/08/2026 | |
| Ngày giờ | `dd/MM/yyyy HH:mm` | 30/08/2026 14:05 | **Múi giờ hiển thị: …** |
| Số tiền | `#,##0` + " ₫" | 1.234.567 ₫ | Làm tròn: … |
| Số lượng | | | |
| Rỗng/null | `—` | | Thống nhất toàn hệ thống |

---

## PHẦN 5 — PHI CHỨC NĂNG

*Chi tiết ở `NFR_<US>.md`. Ở đây chỉ nêu cái áp dụng riêng cho US này.*

| ID | Nhóm | Yêu cầu (có số đo) | Điều kiện đo | Cách verify |
|---|---|---|---|---|

---

## PHẦN 6 — DỮ LIỆU VÀ TÍCH HỢP

### 6.1 API sử dụng

*Chi tiết ở `API_<US>.md`.*

| # | Mục đích | Method | Endpoint | Nguồn contract |
|---|---|---|---|---|
| 1 | Lấy danh sách | GET | `/api/v1/…` | ⚠️ BA đề xuất / ✅ BE cung cấp |

### 6.2 Tác động dữ liệu

*Tham chiếu `IMPACT_….md`. Nêu ngắn cái liên quan trực tiếp US này.*

---

## PHẦN 7 — BÀN GIAO CHO DEV

| | |
|---|---|
| **Trạng thái** | 🟡 Chưa sẵn sàng / ✅ Ready for Dev |
| **Tài liệu cần đọc kèm** | *(liệt kê theo thứ tự)* |
| **Quyết định đã chốt, không phải mặc định** | *(dev không được tự đổi)* |
| **Điểm còn mở** | *(OQ chưa trả lời, ảnh hưởng gì)* |
| **Không được sao chép từ đâu** | *(màn hình cũ có phần đã lỗi thời)* |

---

## PHẦN 8 — OPEN QUESTIONS

| ID | Câu hỏi | Hỏi ai | Từ ngày | Chặn gì | 🔴 chặn G3? | Phương án BA đề xuất |
|---|---|---|---|---|---|---|
| OQ-0nn | | | | AC-05, F03 | 🔴 | *(đề xuất, chưa phải quyết định)* |

---

## Tự chấm

**Gate G3**

| # | Tiêu chí | ☐/✅ | Ghi chú |
|---|---|---|---|
| 1 | Đủ mọi mục bắt buộc (mục N/A có ghi lý do) | | |
| 2 | **Tiêu chí riêng của biến thể PART 2 đã nạp** *(xem đầu file biến thể)* | | |
| 3 | Mỗi US có AC đủ 4 nhóm, có luồng lỗi *(`ml-model`: xem §2.4 metric + ngưỡng)* | | |
| 4 | Bảng mã lỗi đầy đủ, mỗi mã có thông điệp | | |
| 5 | NFR có số đo + cách verify | | |
| 6 | API contract có, ghi rõ nguồn | | |
| 7 | QA xác nhận mọi AC test được | | |
| 8 | Không còn OQ mở ảnh hưởng hành vi | | |
| 9 | Không còn `TBD` trong bảng đặc tả PART 2 và bảng mã lỗi | | |
| 10 | Đã áp đúng bảng "Bớt ở light" / "Thêm ở strict" theo `RIGOR` | | |
| 11 | *(screen)* `WF` có cho mọi `SCR`, tập `C-id` khớp hai chiều, §5 không còn lệch Tồn tại/Hành vi chưa quyết | | |
| 12 | *(screen)* Quy ước chung tham chiếu `UICONV`; chỗ khác có dòng ở `UICONV` §12 | | |

**Quét bắt buộc trước khi nộp:**

```bash
grep -niE "nhanh|mượt|thân thiện|v\.v|phù hợp|tương ứng|nên |có thể " SRS_….md   # W2 — phải rỗng
grep -n "TBD\|TODO\|???" SRS_….md                                                 # phải rỗng
```

**Quy tắc viết W1–W13**

| W1 | W2 | W3 | W4 | W5 | W6 | W7 | W8 | W9 | W10 | W11 | W12 | W13 |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| | | | | | | | | | | | | |