US-[ID]: [Tên User Story]

Thuộc FS: 00-overview.md — [TÊN FEATURE] Phần chung (tổng quan, roles, flow tổng, related features, NFR, Open Questions, References) xem ở Overview. File này chỉ chứa nội dung riêng của US.

Field	Value
US ID	US-[ID]
Role thực hiện	[R1 - End user]
Phase	MVP / Phase 2
Priority	P0 / P1 / P2
Status	Draft / Ready / Approved
NFR liên quan	[NFR-01, NFR-03 — xem Overview §5]
OQ liên quan	[OQ-001 — xem Overview §6, hoặc "Không có"]

1. US Statement

As a [role]
I want [hành động]
So that [lợi ích]

2. Dependencies & Definition Of Ready

US này chỉ sẵn sàng để build khi các dependency dưới đây đã rõ.

#	Cần sẵn sàng	Ai cung cấp	Trạng thái
D1	Figma frame M1, M2 final	@Designer	☐
D2	API /xxx ready hoặc đã có contract	@Backend	☐
D3	US-XX merged hoặc behavior đã được confirm	@Frontend	☐

3. Business Rules

Đặt business rules trước phần design để field/action/validation có rule tham chiếu rõ ràng.

Mỗi BR phải có ít nhất 1 AC (hoặc field/action/NFR cụ thể) cover — điền cột "Đã cover bởi". BR chưa có AC cover → bổ sung AC hoặc tạo Open Question ở Overview §6, không để trống.

ID	Rule	Áp dụng ở	Đã cover bởi (AC)	Nguồn code (Mode B/C)
BR-01	[Rule nghiệp vụ]	M1 - action [Tên action]	AC-M1.x	[file.ts:dòng — Mode A: N/A]
BR-02	[Rule nghiệp vụ]	M2 - field [Tên field]	AC-M2.x
BR-03	[Rule nghiệp vụ]	[Màn/action/field liên quan]	AC-Mx.x / EC-Mx.x

Mode B/C: rule mô tả hành vi quan sát được trong code, viết bằng ngôn ngữ nghiệp vụ (không tên class/biến trong cột Rule). Hành vi nghi là bug → không viết thành rule: ghi ⚠️ Observed + tạo OQ ở Overview §6. Mode C: thêm tiền tố [NEW] / [CHANGED] / [UNCHANGED] cho mỗi BR.

4. Design

a. Mối liên hệ giữa các màn & User Flow

[Entry]
  ↓ user click X
[M1: Search]
  ↓ chọn item
[M2: Confirm]
  ├─ submit OK ──→ [M3: Success]
  ├─ lỗi A ──────→ ở lại M2, hiện inline error
  └─ lỗi B ──────→ [M4: Modal error]

Link flow chi tiết nếu có:

• Mermaid / Excalidraw / Figma flow: [Link]

b. Chi tiết từng màn

Quy ước:

• Mỗi màn dùng mã M1, M2, ... (trong phạm vi US này).
• Mỗi màn tương ứng một Figma frame riêng nếu có UI.
• Nếu thiếu frame/state, ghi rõ TODO: Designer bổ sung.

Màn M1 - [Tên màn]

Field	Value
Figma frame	[Link frame cụ thể]
Trigger vào màn	[User làm gì để vào màn này]
Mô tả ngắn	[1-2 câu mô tả mục đích màn]

UI States

State	Khi nào	Hiển thị	Figma frame
Default	Vừa vào màn	[Mô tả UI]	[Link]
Loading	Đang load data	Skeleton/spinner	[Link]
Has data	Có data	[Mô tả UI]	[Link]
Empty	Không có data	Empty state + CTA nếu có	[Link]
Error	API lỗi	Toast/inline error + retry nếu có	[Link]
Disabled	Điều kiện chưa đủ	[Mô tả UI disabled]	[Link]

Frame thiếu: ghi TODO: Designer bổ sung [tên state].

Fields

Field list + thuộc tính + rule lấy từ bước Field Intake. Marker: [đề xuất] = AI tự điền chờ BA review; ❓BA = cần BA cung cấp (chưa suy được). Ô ❓BA chưa quyết → Open Question ở Overview, không bịa.

Field	Required	Type	Default	Format	Validation	Error Message	Visibility	Depends On
[Tên field]	Yes/No	Text/Number/Date/Dropdown/...	[Default]	[dd/MM/yyyy, regex, max length]	[Rule + ref BR-XX]	[Text khi sai]	Always/Hidden/Readonly	[Field X = Y thì field này...]

Filter / Search / Sort (chỉ màn List/Report — xóa nếu không phải)

Loại	Theo field	Kiểu	Default	Notes
Filter	[field]	dropdown / range / date range / multi-select	[Tất cả]
Search	[field]	free-text	—
Sort	[field]		[field + chiều mặc định]
Pagination	—		[page size]

Actions

A1 - [Tên action]

Item	Description
Trigger	[User làm gì]
Behavior	[Hệ thống xử lý gì, ref BR-XX nếu có]
Success Result	[Kết quả mong đợi]

Error cases:

Case	Expected Handling
[Lỗi 1]	[Hiển thị gì / xử lý gì]
[Lỗi 2]	[Hiển thị gì / xử lý gì]

Acceptance Criteria của màn M1

Format chuẩn: Given - When - Then.

AC-M1.1 - [Tên ngắn]

Given [điều kiện]
When [hành động]
Then [kết quả]

Maps to:

• Business Rule: [BR-XX]
• Field/Action: [Tên field/action nếu có]

AC-M1.2 - [Tên ngắn]

Given [điều kiện]
When [hành động]
Then [kết quả]

Maps to:

• Business Rule: [BR-XX]

Negative AC / Edge Cases của màn M1

ID	Tình huống	Hành vi mong đợi
EC-M1.1	Mất mạng giữa flow	[Expected behavior]
EC-M1.2	Mở 2 tab cùng thao tác	[Expected behavior]
EC-M1.3	Input có ký tự đặc biệt/emoji	[Expected behavior]
EC-M1.4	Refresh trang giữa modal	[Expected behavior]

Màn M2 - [Tên màn]

[Lặp toàn bộ cấu trúc màn M1: Figma frame, trigger, UI States, Fields, Actions, Acceptance Criteria, Negative AC / Edge Cases.]

5. Cross-feature AC

AC riêng cho các trường hợp US này ảnh hưởng đến hoặc bị ảnh hưởng bởi tính năng khác ngoài tính năng hiện tại.

Nếu không có cross-feature AC, ghi: Không có.

Trường Maps to phải dùng mã REL-XX đã khai báo ở mục 3. Các tính năng liên quan của Overview.

AC-X.1 - [Tên cross-feature AC]

Given [điều kiện]
When [hành động]
Then [kết quả]

Maps to:

• REL-XX ([Affects / Be Affected] - [Tên feature/module liên quan])