# Skill: Viết Đặc tả Use Case (Use Case Specification) - Phiên bản v1

## 1. Mục đích (Purpose)
Kỹ năng này giúp BA chuyển hóa toàn bộ các thông tin yêu cầu nghiệp vụ đã được thống nhất sau quá trình Q&A thành một tài liệu Đặc tả Use Case (Use Case Spec) hoàn chỉnh. Tài liệu này là "nguồn sự thật duy nhất" (Single Source of Truth) giúp đội ngũ Dev lập trình chính xác và đội ngũ Test thiết kế toàn bộ kịch bản kiểm thử (Test Cases/Scripts).

Ngôn ngữ output: auto-detect theo ngôn ngữ của ticket/task input — xem `custom/rules/output-language.md` (input tiếng Việt → output tiếng Việt; ngược lại mặc định tiếng Anh).

Chuẩn diễn đạt: xem `custom/rules/document-wording.md` — hành văn tự nhiên (không "cố/cố gắng/thử/tiến hành", câu chủ động, một câu một hành động) và mỗi mục/ô phải tự chứa đủ nội dung, không tham chiếu sang tài liệu khác (SRS/UC Spec/System Requirement/ticket), sang case khác, hay sang mục khác của cùng tài liệu. Mã nội bộ (`BR2.10`, `FR-01`) vẫn dùng để liên kết, nhưng phải kèm mô tả nội dung ngay tại chỗ, không để mã trần.

Thuật ngữ nghiệp vụ: bắt buộc theo `custom/rules/domain-terminology.md` và `AK-Docs/00.Project-Overview/Glossary.md` — dùng đúng từ QnA-Log / Analysis của cùng functionId đã dùng (không đổi sang từ đồng nghĩa), không tự dịch từ dự án (`buyer`, `group`, `product`...), không tự đặt tên tiếng Việt cho phân hệ / menu / màn hình; thuật ngữ tiếng Nhật viết tên gọi theo cột `Viết trong tài liệu` của Glossary kèm chữ gốc trong ngoặc ở lần đầu mỗi mục cấp 2. Chi tiết: mục "Dùng lại đúng từ của tài liệu trước" và "Tên phân hệ, menu, khu vực màn hình" của `domain-terminology.md`.
Động từ thao tác UI và thuật ngữ IT: bắt buộc theo `custom/rules/ui-action-wording.md` (kế thừa `qa-writing-standards.md` mục 6.11) — câu mô tả thao tác dùng động từ chuẩn (`Click button`, `Click menu item`, `Enter <value> into <field>`, `Select`, `Check`, `Open modal`, `Press Enter`…), câu mô tả kết quả dùng trạng thái chuẩn (`Displayed`, `Enabled` / `Disabled`, `Checked`…), thuật ngữ IT giữ tiếng Anh (field, button, toast, modal, server, cache, redirect, validate…); không viết "bấm", "nhấn", "tích chọn", "chọn tay", "máy chủ", "bộ nhớ đệm". Câu mô tả nghiệp vụ vẫn viết tiếng Việt.

## 2. Kiến thức cần có (Prerequisite Knowledge)
- **Cấu trúc Use Case chuẩn:** Hiểu rõ các thành phần của một Use Case Spec bao gồm: Thông tin chung, Mô tả màn hình, Mô tả thành phần UI, Luồng hoạt động (Activity Flow) và Quy tắc nghiệp vụ (Business Rules).
- **Cách mô tả Luồng xử lý (Flow):** 
  - Phân biệt hành động của Tác nhân (Actor Action) và phản hồi của Hệ thống (System Response).
  - Trình bày mạch lạc theo các bước đánh số thứ tự (1, 2, 3...).
- **Tính liên kết logic:** Đảm bảo mã lỗi, thông báo lỗi trong Business Rules phải khớp với các mô tả thành phần UI và vị trí hiển thị lỗi trên Prototype.

## 3. Quy trình thực hiện (Step-by-step Process)
- **Bước 1: Điền thông tin chung (General Information):**
  Xác định chính xác Function Name, Description, Actors, Trigger, Pre-Conditions, Main Flow tóm tắt, và Post-Conditions.
- **Bước 2: Tích hợp thiết kế màn hình:**
  Chèn ảnh chụp prototype (`ak proto shot`) và link Markdown click được tới file HTML gốc vào mục Screen Description. Không dán mã HTML/CSS. Chi tiết và cách xử lý khi máy chưa có Playwright: xem `create-spec-workflow.md`, Gate 4 Bước 3.
- **Bước 3: Mô tả các thành phần UI (UI Components):**
  Lập bảng chi tiết tất cả các control trên giao diện (các input fields, buttons, links, labels). Đối với mỗi thành phần, cần làm rõ:
    - Kiểu dữ liệu nhập vào (Text, Number, Date...).
    - Độ dài giới hạn (Min/Max length).
    - Tính bắt buộc (Mandatory: Yes/No).
    - Giá trị mặc định (Default Value).
    - Mô tả hành vi (Description).
- **Bước 4: Thiết kế sơ đồ Mermaid (Activity Flow):**
  Áp dụng kỹ năng `@skill-ba-mermaid-flowchart-v1.md` để vẽ và nhúng biểu đồ Mermaid.
- **Bước 5: Đặc tả Business Rules (Quy tắc nghiệp vụ):**
  Áp dụng kỹ năng `@skill-ba-build-business-rules-v1.md` để viết chi tiết các điều kiện kiểm tra, validation logic và câu thông báo lỗi đi kèm.

## 4. Checklist kiểm tra (Checklist for Verification)
- [ ] Luồng đi (Flow) có mô tả rõ ràng sự tương tác qua lại giữa Actor và System chưa?
- [ ] Bảng mô tả UI Components có bị bỏ sót bất kỳ thành phần nào trên prototype HTML không?
- [ ] Các Business Rules (BR) đã được đánh mã số rõ ràng (BR1, BR2, BR3...) để dễ tham chiếu chưa?
- [ ] Mọi trường hợp báo lỗi đều có câu thông báo lỗi (Error message) đi kèm chi tiết chưa?
- [ ] Hành văn tự nhiên, không dấu vết dịch máy? Chạy `grep -nE "Cố |Cố gắng|Thử (mở|nhập|bấm|click)|Tiến hành|thực hiện việc"` — phải 0 hit.
- [ ] Mỗi Flow step / Business Rule / mô tả UI Component đọc độc lập là hiểu, không có tham chiếu trần ("như mục trên", "theo BR2.10" không kèm mô tả nội dung, "xem SRS §x")?
- [ ] Thuật ngữ khớp QnA-Log / Analysis và Glossary? Không có từ tự dịch (`buyer` → "cửa hàng", "khách hàng"), không có tên phân hệ / menu tự đặt, không có chữ tiếng Nhật đứng một mình trong câu (`custom/rules/domain-terminology.md`).
- [ ] Câu mô tả thao tác / kết quả UI dùng động từ và trạng thái chuẩn của `custom/rules/ui-action-wording.md` (`Click button`, `Enter ... into field`, `Displayed`, `Disabled`…), thuật ngữ IT giữ tiếng Anh, cột "Loại Component" dùng tên Element của bảng? Chạy grep ở mục 5 của file đó — 0 hit ngoài chữ gốc trích nguyên văn.
- [ ] Tài liệu có sử dụng định dạng markdown chuẩn và cấu trúc thống nhất theo mẫu `@skill-ba-uc-template-v1.md` chưa?

## 5. Output mong đợi (Expected Output)
- Một tài liệu đặc tả Use Case hoàn chỉnh định dạng markdown, đặt tên theo chuẩn: `UC-Spec_v1.md` trong thư mục `AK-Docs/02.BA-Specs/04.UC-Specs/[functionId]/`.
