# Skill: Template Đặc tả Use Case (Use Case Spec) - Phiên bản v1

Cấu trúc chuẩn của một tài liệu đặc tả Use Case hoàn chỉnh dùng để chuyển giao cho Dev/Test.

> ⚠️ **Chuẩn diễn đạt bắt buộc:** `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 tự chứa đủ nội dung; mã `BR-NNN`/`[PENDING - QA-ID]` dùng để liên kết vẫn phải kèm mô tả nội dung ngay tại chỗ, không để mã trần.
>
> ⚠️ **Thuật ngữ bắt buộc:** `custom/rules/domain-terminology.md` + `AK-Docs/00.Project-Overview/Glossary.md` — dùng đúng từ QnA-Log / Analysis đã dùng; không tự dịch từ dự án, không tự đặt tên phân hệ / menu / màn hình; tiếng Nhật viết tên gọi (chữ gốc) khi mô tả, chữ gốc (tên gọi) khi người đọc phải khớp chữ trên màn hình.
>
> ⚠️ **Động từ thao tác UI & thuật ngữ IT:** `custom/rules/ui-action-wording.md` — `Click button`, `Click menu item`, `Enter <value> into <field>`, `Select`, `Check`, trạng thái `Displayed` / `Enabled` / `Disabled`; thuật ngữ IT giữ tiếng Anh (field, toast, modal, server, cache, redirect…); không viết "bấm", "nhấn", "tích chọn", "chọn tay".

---

<!-- Frontmatter (KIT-25) — bắt buộc khi UC Spec do Light-out Agents (akg) quản lý, tuỳ chọn ở flow manual:
---
functionId: F-xxx
title: [Tên chức năng]
type: new            # new | change
status: draft        # draft → signed khi Human/PM ký; bản đã ký không sửa, muốn sửa thì tạo _v(N+1)
version: N
signedBy:            # điền khi ký
signedAt:            # YYYY-MM-DD
sources:             # ticket / Backlog Document / comment kèm `updated` (yêu cầu thô nằm trên Backlog)
  - { ticket: PROJ-123, updated: 2026-10-20T09:00:00Z }
analysis: ../../01.Analysis/[functionId]/Analysis_vK.md
qna: ../../02.QnA/[functionId]/QnA-Log_vN.md
changeOf: v(N-1)     # chỉ khi type: change
changeRequest: PROJ-456
---
Bản đã ký cũ chuyển vào `_archive/` cùng thư mục khi bản mới được ký.
-->

# Tài liệu Đặc Tả Use Case: Chức năng [Tên Chức Năng]

**UC-Spec-Version:** v{N}   <!-- MANDATORY — Mode CREATE: v1. Mode UPDATE: N+1 so với bản trước, xác định ở Gate 1 Bước 0 của create-spec-workflow.md -->
**Date:** [YYYY-MM-DD]
**Status:** ⏸️ Waiting for PM sign-off | ✅ PM Approved

> Header này là điểm neo cho toàn bộ chuỗi trace ngược (System Requirement, Test Case) — xem `docs/internal/Token Problems.md` §3.1. Trước đây template này không có version header, khiến mọi công cụ downstream (`create-system-requirement`, `create-testcase`) không có cách nào xác định UC Spec đang ở version nào một cách tường minh.

## 1. Thông tin chung (General Information)

| Thuộc tính | Mô tả chi tiết |
| :--- | :--- |
| **Tên chức năng (Function Name)** | [Tên chức năng chính xác] |
| **Mô tả (Description)** | [Tóm tắt mục đích và giá trị nghiệp vụ của chức năng] |
| **Tác nhân (Actors)** | [Danh sách các tác nhân sử dụng hoặc bị tác động] |
| **Tác nhân kích hoạt (Trigger)** | [Sự kiện kích hoạt luồng xử lý này] |
| **Điều kiện tiên quyết (Pre-Conditions)** | [Các điều kiện hệ thống hoặc trạng thái dữ liệu bắt buộc phải có trước khi thực hiện] |
| **Điều kiện sau xử lý (Post-Conditions)** | [Trạng thái của hệ thống và dữ liệu sau khi kết thúc thành công] |

### Luồng xử lý chính (Main Flow)

| Bước | Tác nhân (Actor Action) | Hệ thống (System Response) |
| :-: | :--- | :--- |
| 1 | Người dùng click menu item 「...」... | Hệ thống hiển thị giao diện... |
| 2 | Người dùng enter ... into field 「...」 | |
| 3 | Người dùng click button 「...」... | Hệ thống kiểm tra và thực hiện... |
| 4 | | Hệ thống thông báo thành công và chuyển hướng... |

### Các luồng thay thế / ngoại lệ (Alternative / Exception Flows)

- **Alternative Flow A: [Tên luồng thay thế]**
  - Thực hiện từ bước [X] của Luồng chính:
  - Các bước xử lý: ...
- **Exception Flow B: [Tên luồng lỗi]**
  - Thực hiện khi xảy ra lỗi: ...
  - Các bước xử lý: ...

---

## 2. Mô tả màn hình (Screen Description)
*Chèn ảnh chụp prototype (`ak proto shot`) và link click được tới file HTML gốc. Không dán mã HTML/CSS vào đây. Đường dẫn tính từ file UC Spec này.*

![Prototype [functionId] v1](../../03.UI-Prototypes/[functionId]/UI-Prototype_v1.png)

Mở prototype gốc (HTML, có thể tương tác): [UI-Prototype_v1.html](../../03.UI-Prototypes/[functionId]/UI-Prototype_v1.html)

---

## 3. Mô tả thành phần giao diện (UI Components Description)

| # | Tên Component | Loại Component | Cho phép sửa | Bắt buộc | Giá trị mặc định | Quy tắc định dạng & Giới hạn dữ liệu | Mô tả hành vi & tương tác |
| :-: | :--- | :--- | :-: | :-: | :--- | :--- | :--- |
| 1 | `ログインID` | Text input | Yes | Yes | None | Độ dài: 3-20 ký tự. Chỉ chữ và số. Không chứa khoảng trắng. | Ô nhập tên tài khoản của người dùng. |
| 2 | `ログイン` | Button | N/A | N/A | N/A | N/A | Click để gửi thông tin đăng nhập lên server. |
| 3 | | | | | | | |

---

## 4. Sơ đồ luồng hoạt động (Activity Flow Diagram)
*Sử dụng biểu đồ Mermaid để trực quan hóa quy trình xử lý.*

```mermaid
graph TD
    %% Viết mã nguồn Mermaid tại đây
```

---

## 5. Quy tắc nghiệp vụ (Business Rules)

### BR1: Quy tắc kiểm tra dữ liệu đầu vào (Validation Rules)
*Định nghĩa các lỗi khi người dùng nhập dữ liệu sai hoặc để trống.*
- **[BR1.1] Trống dữ liệu bắt buộc:** Nếu bất kỳ trường bắt buộc nào bị trống khi click button thực thi:
  - Hệ thống dừng xử lý.
  - Hiển thị inline error message `[Tên thông báo lỗi]` dưới field bị trống.
- **[BR1.2] Định dạng dữ liệu không hợp lệ:** ...

### BR2: Quy tắc lưu trữ dữ liệu (Saving Rules)
*Định nghĩa cách dữ liệu được ghi nhận vào cơ sở dữ liệu.*
- **[BR2.1]** Hệ thống ghi nhận thời gian đăng nhập vào bảng `user_logs` với các trường: `user_id`, `login_time`, `status`.

### BR3: Quy tắc phân quyền & Bảo mật (Authorization & Security Rules)
- **[BR3.1]** Sau 5 lần nhập sai mật khẩu liên tiếp, tài khoản tự động bị khóa trong 30 phút.

---

## 6. Change Log

*Chỉ điền khi Mode UPDATE (version ≥ v2) — Mode CREATE (v1) để trống hoặc ghi 1 dòng "Khởi tạo ban đầu".* Mỗi thay đổi giữa 2 version phải có 1 dòng — không âm thầm sửa nội dung mà không ghi lại (xem `custom/templates/shared/create-spec-workflow.md` Gate 4 Bước 1).

| Version | Ngày | Flow/BR/UI Component thay đổi | Tóm tắt thay đổi | Nguồn (ticket/CR) |
|---|---|---|---|---|
| v1 | [YYYY-MM-DD] | — | Khởi tạo ban đầu | [ticket gốc] |

---

## 7. Phụ lục cho Dev Team (KIT-25)

*Phần bàn giao cho Dev Team đọc nhanh, lấy từ Analysis đã duyệt. Mã giữ nguyên như Analysis (KIT-23); System Requirement, story, test case trỏ về các mã này.*

### Yêu cầu
- **REQ-001**: ...

### Acceptance Criteria
- **AC-001** (REQ-001): Given ... When ... Then ...

### Màn hình
- [Tên màn hình] — mới, đã xác nhận (mã xác nhận) / đã có: `../../03.UI-Prototypes/[functionId]/[Man-hinh]_vN.html`

### Ngoài phạm vi
- ...

### Thay đổi so với v(N-1) (chỉ khi type: change)
- **REQ-002** sửa: ...

### Câu hỏi kỹ thuật cho Dev Team (L1)
- ...

