sys-analysis-design/.claude/skills/ba-3-specification/templates/srs.md

SRS — <Tên User Story>

Version	1.0
Date	YYYY-MM-DD
Author	(skill ba-3-specification)
Status	🟡 Draft
Approved by	PO: — · Tech Lead: — · QA: —
Source	BACKLOG_… v1.0 · BR_… v1.0 · RBAC_… v1.0 · IMPACT_… v1.0
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. Wireframe quyết định nó nằm ở đâu, to bằng nào. Khi hai thứ mâu thuẫn: bảng thắng về sự tồn tại và hành vi, hình thắng về bố cục — và mâu thuẫn đó phải được báo cho BA.

---

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	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	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	Luồng dữ liệu, data contract, chất lượng, đối soát nguồn–đích
ml-model	srs-part2/ml-model.md	Bài toán, nhãn, metric + ngưỡng, fallback, drift
batch-job	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.

🔴 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

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

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