219 lines
9.0 KiB
Markdown
219 lines
9.0 KiB
Markdown
# 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 |
|
||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
||
| | | | | | | | | | | | | |
|