# Skill: Template Q&A - Phiên bản v1

Mẫu tài liệu dùng để trình bày danh sách câu hỏi Q&A và theo dõi phản hồi từ khách hàng.

---

# Tài liệu Q&A: [Tên Chức Năng]

> ⚠️ **Độ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".

*Tài liệu này dùng để theo dõi các vấn đề nghiệp vụ cần làm rõ giữa đội ngũ dự án và khách hàng. Trạng thái bao gồm: **Open** (Đang chờ phản hồi), **Confirmed** (Đã thống nhất), **Blocked-by QA-xx** (chưa hỏi vì phụ thuộc câu QA-xx còn Open). Mức độ ảnh hưởng: 🔴 **Blocking** (chưa trả lời thì không thể tiến gate tiếp theo), 🟡 **Non-blocking** (có thể defer, output sẽ giữ marker `[PENDING - QA-ID]` tại vị trí liên quan).*

*Phụ thuộc ghi ở dòng thông tin thứ 2: câu độc lập → `không phụ thuộc câu hỏi nào khác`; có câu cha → `Chỉ trả lời được sau khi QA-xx được chốt.` Câu cha còn Open → câu con để trạng thái `Blocked-by QA-xx`, KHÔNG gửi cho khách hàng ở vòng này, và dùng chung marker `[PENDING - QA-xx]` của câu cha.*

*Cấu trúc một câu hỏi — viết cho người **không** đọc code:*

| Mục | Bắt buộc | Cách viết |
| :--- | :-: | :--- |
| Tiêu đề | Có | `Q{n}. [Màn hình/Chức năng] Về {chủ đề}` — một dòng, chủ đề viết thành **cụm danh từ**, không viết thành câu hỏi |
| Hai dòng thông tin | Có | Dòng 1: `QA-01 ・ 🔴 Blocking ・ Đã chốt (Confirmed)` — trạng thái tiếng Việt, từ khoá gốc trong ngoặc. Dòng 2: một câu gộp người cần trả lời, hạn, phụ thuộc — `Cần PM / Khách hàng trả lời trước 15/10. Không phụ thuộc câu hỏi nào khác.` Trường trống viết thành chữ (`Chưa đặt hạn`), không dùng `—` |
| Hiện trạng | Có | Hệ thống hiện đang làm gì. Tính năng mới thì ghi `Chưa có (tính năng mới)` |
| Bối cảnh | Có | Yêu cầu nào dẫn tới câu hỏi, và **chưa chốt thì ảnh hưởng gì** — đã gộp "Vì sao cần hỏi" vào đây, **không** viết thành mục riêng |
| Vấn đề | Không | Điểm chưa rõ, mâu thuẫn hoặc rủi ro phát hiện được. Không có thì bỏ hẳn mục |
| Câu hỏi | Có | Một câu, một chủ đề, ưu tiên câu hỏi đóng |
| Lựa chọn và đề xuất | Nên có | Mỗi option một dòng `A: …`; chữ cái kế tiếp luôn là `Khác (khách tự mô tả) / Chưa quyết định, cần thời gian.`; sau cùng là `Đề xuất của Relipa: <chữ cái>. Lý do: …`. **Không ghi công số** |
| Ví dụ minh họa | Khi cần | Bám dữ liệu/màn hình thật; kết quả theo option viết `Nếu chọn A: … Nếu chọn B: …`. Không có thì bỏ hẳn mục |
| Câu trả lời | Có | Chỉ chứa nội dung trả lời. Câu còn Open ghi `Chưa trả lời.` (kèm lý do nếu có) |
| Người trả lời / Ngày trả lời / Nguồn | Có | Ba dòng ngang cấp với `Câu trả lời:`, tên in đậm, giá trị cùng dòng, không thụt. Câu còn Open ghi `—` |

*Trình bày trong file — đọc như người viết tay: tên mục in đậm, kết bằng `:`, **không đánh số**; mỗi mục cách mục sau đúng 1 dòng trống, không có dòng trống giữa tên mục và nội dung; nội dung thụt **4 dấu cách**, mỗi ý một dòng, **không** dùng bullet `・` hay `-`. Mọi dòng trong cùng một khối (hai dòng thông tin; tên mục + nội dung; ba dòng Người trả lời / Ngày / Nguồn), trừ dòng cuối của khối, kết thúc bằng **2 dấu cách** — thiếu thì khi render markdown các dòng bị gộp thành một đoạn.*

*Các mục bên dưới có tên in đậm như `**Hiện trạng:**`. **Hiện trạng và Bối cảnh tách riêng**: Hiện trạng là sự thật hệ thống đang có, Bối cảnh là lý do bây giờ phải hỏi — viết lẫn thì khách nhầm giữa cái đang có với cái sắp làm. **Bối cảnh phải nêu mốc sự kiện cụ thể** — "sau khi phát hành chức năng quản lý `group`", "khi `admin` tạo `group` đầu tiên" — cấm nói tắt kiểu "khi bật `group`" vì không tương ứng với thao tác nào có thật. Mọi từ viết tắt giải nghĩa ngay lần đầu xuất hiện.*

***Bám sát hệ thống thực tế:** mọi option và mọi ví dụ chỉ dùng màn hình, nút, trường, vai trò, trạng thái **có thật** trong yêu cầu / `AK-Docs/` / mã nguồn. Không chỉ ra được nguồn → bỏ option đó, hoặc gộp vào `Khác — mô tả ngắn`. Option mô tả hành vi hệ thống chưa có → ghi `(chưa có, cần làm mới)` ngay trong option. Số liệu, ngày giờ trong ví dụ được phép là dữ liệu minh hoạ; màn hình và trường chứa chúng thì không.*

***Thuật ngữ:** dùng nguyên từ nghiệp vụ dự án theo `AK-Docs/00.Project-Overview/Glossary.md` — `group` không viết thành "nhóm", `buyer` không viết thành "cửa hàng", `import` không viết thành "nhập". Gặp từ chưa có trong Glossary → hỏi user, rồi ghi ngược vào file đó. Xem `custom/rules/domain-terminology.md`.*

## Dạng gọn khi hỏi trong chat

*Khối đầy đủ bên dưới chỉ dùng trong file `QnA-Log`. Khi hỏi BA trực tiếp trong hội thoại (Gate 1 Bước 2 của `create-spec`), dùng dạng **gọn** sau — khoảng 12 dòng, không bớt nội dung cần để ra quyết định. Quy tắc chi tiết: mục 1b "Quy tắc chất lượng câu hỏi" trong `create-spec-workflow.md`. BA gõ `chi tiết` → in khối đầy đủ của câu đang hỏi, đúng format ghi file.*

```text
**Q1/12 · 🔴 Blocking · QA-01** — [Cửa hàng – màn hình Danh sách `product` (商品一覧)] Phạm vi `product` cho `buyer` chưa thuộc `group`

**Hiện tại:** mọi `buyer` đăng nhập đều thấy toàn bộ `product` đang công khai (公開).
**Thay đổi:** sau khi phát hành chức năng quản lý `group`, `buyer` chỉ thấy `product` thuộc `group` của mình. `buyer` mới đăng ký chưa thuộc `group` nào cho tới khi `admin` xếp vào.

❓ `buyer` chưa thuộc `group` nào thì thấy gì?

- **A.** Không thấy `product` nào cho tới khi được xếp vào `group`. Công số thấp. ⭐ Relipa đề xuất: không lộ `product` premium.
- **B.** Thấy toàn bộ `product` đang công khai như hiện tại, chỉ thu hẹp khi đã có `group` (chưa có, cần làm mới). Công số thấp.
- **Khác / chưa quyết** → ghi Open vào QnA-Log.

VD: 「山田商店」 đăng ký 07/10, chưa thuộc `group` → A: trang trống · B: thấy cả 250 `product`.

↳ Trả lời: `A` / `B` / `Khác: …` / `Open` · gõ `chi tiết` để xem bản đầy đủ
```

*Khi ghi file, mỗi câu hỏi dạng gọn được mở rộng về khối đầy đủ bên dưới — cùng câu hỏi, cùng options, cùng đề xuất, điền đủ hai dòng thông tin (người cần trả lời, hạn, trạng thái). Ghi chú công số và dấu `⭐` của dạng gọn không chép sang file.*

## Danh sách câu hỏi Q&A

*Mỗi câu hỏi là **một khối**, không dùng bảng. Bảng nhiều cột buộc người đọc quét ngang mới ghép được nghĩa một câu hỏi, và cột nào cũng hẹp nên chữ xuống dòng vụn.*

*Chia theo **role** của hệ thống — mỗi role một nhóm `# Role: <tên>`, nhóm cuối là `# Chung / Cross-role` cho câu không gắn role nào. Tên role lấy đúng tên dự án đang dùng (Admin, Buyer, Guest, Operator...). Nhóm không có câu hỏi nào thì **không in heading** — ghi một dòng ở phần Tóm tắt. Hệ thống chỉ có một role → bỏ cấp nhóm role, chia theo màn hình/module.*

*Số thứ tự `Q1`, `Q2`… chạy theo thứ tự đọc của tài liệu. **Mã** `QA-01`, `QA-02`… là ID cố định của câu hỏi, đánh số liên tục toàn file và **không đổi giữa các version** — `Phụ thuộc` và marker `[PENDING - QA-xx]` trỏ theo Mã, không theo số Q.*

*Mục **Vấn đề** và **Ví dụ minh họa** bỏ hẳn khi không có nội dung; không để lại tên mục rỗng.*

---

# Role: Buyer

## Q1. [Màn hình Đăng nhập] Về cách lấy lại mật khẩu
QA-01 ・ 🔴 Blocking ・ Đã chốt (Confirmed)  
Cần PM / Khách hàng trả lời trước [dd/mm]. Không phụ thuộc câu hỏi nào khác.

**Hiện trạng:**  
    Màn hình Đăng nhập có link "Quên mật khẩu" click được, nhưng chưa nối sang màn hình nào.

**Bối cảnh:**  
    Tài liệu chưa nói click link "Quên mật khẩu" thì đi tiếp ra sao. Quyết định này đổi số bước người dùng phải làm và đổi phạm vi công việc.

**Câu hỏi:**  
    Buyer lấy lại mật khẩu qua email hay qua số điện thoại?

**Lựa chọn và đề xuất:**  
    A: Sang trang nhập email, buyer nhận link đặt lại mật khẩu trong hộp thư (màn hình nhập email đã có trong hệ thống).  
    B: Hiện popup nhập số điện thoại, buyer nhận OTP (mã xác thực dùng một lần) qua SMS (chưa có, cần làm mới). Phát sinh chi phí tin nhắn.  
    C: Khác (khách tự mô tả) / Chưa quyết định, cần thời gian.  
    Đề xuất của Relipa: A. Lý do: dùng lại màn hình đã có, không phát sinh chi phí tin nhắn.

**Câu trả lời:**  
    Chọn A, link URL là `/forgot-password`.

**Người trả lời:** Nguyễn Văn A (PO)  
**Ngày trả lời:** 12/07/2026  
**Nguồn:** Khách hàng

---

## Q2. [Màn hình Đăng nhập] Về câu chữ thông báo lỗi khi sai mật khẩu
QA-02 ・ 🟡 Non-blocking ・ Đang chờ trả lời (Open)  
Cần PM / Khách hàng trả lời trước [dd/mm]. Không phụ thuộc câu hỏi nào khác.

**Hiện trạng:**  
    Màn hình Đăng nhập hiển thị một thông báo lỗi chung khi buyer nhập sai.

**Bối cảnh:**  
    Tài liệu chưa chốt câu chữ cụ thể của thông báo này. Chưa chốt thì tài liệu giữ marker `[PENDING - QA-02]` tại mục thông báo lỗi, Test Case cũng chưa kiểm được câu chữ.

**Câu hỏi:**  
    Câu chữ thông báo lỗi khi sai mật khẩu là gì?

**Lựa chọn và đề xuất:**  
    A: "Email hoặc mật khẩu không đúng." (câu đang dùng trên màn hình hiện tại). Câu này không tiết lộ email có tồn tại hay không.  
    B: Khác (khách tự mô tả) / Chưa quyết định, cần thời gian.  
    Đề xuất của Relipa: A. Lý do: giữ nguyên câu đang chạy, không phát sinh việc.

**Câu trả lời:**  
    Chưa trả lời. Khách hàng cần hỏi lại team Marketing.

**Người trả lời:** —  
**Ngày trả lời:** —  
**Nguồn:** —

---

# Role: Admin

## Q3. [Màn hình quản lý group] Về cách xử lý dòng trùng khi import danh sách buyer
QA-03 ・ 🔴 Blocking ・ Đang chờ trả lời (Open)  
Cần PM / Khách hàng trả lời. Chưa đặt hạn, không phụ thuộc câu hỏi nào khác.

**Hiện trạng:**  
    Màn hình quản lý group đã có nút import danh sách buyer.

**Bối cảnh:**  
    Tài liệu chưa nói xử lý thế nào khi file có dòng trùng buyer đã nằm trong group. Chưa chốt thì không viết được thông báo kết quả import và không thiết kế được Test Case cho trường hợp này.

**Câu hỏi:**  
    File import có dòng trùng buyer đã nằm trong group thì hệ thống xử lý ra sao?

**Lựa chọn và đề xuất:**  
    A: Bỏ qua dòng trùng, import các dòng còn lại, cuối cùng hiện số dòng đã bỏ qua.  
    B: Dừng toàn bộ lần import đó, không ghi dòng nào.  
    C: Khác (khách tự mô tả) / Chưa quyết định, cần thời gian.  
    Đề xuất của Relipa: A. Lý do: admin không phải sửa file rồi import lại từ đầu chỉ vì vài dòng trùng.

**Ví dụ minh họa:**  
    File 100 dòng, trong đó 3 buyer đã có sẵn trong group.  
    Nếu chọn A: 97 dòng vào group, báo "bỏ qua 3 dòng trùng". Nếu chọn B: 0 dòng vào group, báo lỗi dòng 12, 48, 77.

**Câu trả lời:**  
    Chưa trả lời.

**Người trả lời:** —  
**Ngày trả lời:** —  
**Nguồn:** —

---

# Chung / Cross-role

## Q4. [Màn hình Đăng nhập] Về câu chữ thông báo khi tài khoản bị khoá tạm thời
QA-04 ・ 🟡 Non-blocking ・ Chờ QA-02 chốt trước (Blocked-by QA-02)  
Cần PM / Khách hàng trả lời trước [dd/mm]. Chỉ trả lời được sau khi QA-02 được chốt.

**Hiện trạng:**  
    Hệ thống khoá tạm thời tài khoản sau nhiều lần đăng nhập sai.

**Bối cảnh:**  
    Câu chữ thông báo cho trường hợp này chưa chốt, và phụ thuộc câu chữ sẽ chốt ở QA-02. Câu này chưa gửi vòng này vì QA-02 còn Open, nên dùng chung marker `[PENDING - QA-02]`.

**Câu hỏi:**  
    Thông báo khi tài khoản bị khoá tạm thời dùng lại câu chữ đã chốt ở QA-02 hay một câu riêng?

**Lựa chọn và đề xuất:**  
    A: Dùng lại câu của QA-02.  
    B: Câu riêng, khách hàng cung cấp.  
    C: Khác (khách tự mô tả) / Chưa quyết định, cần thời gian.

**Câu trả lời:**  
    Chưa trả lời.

**Người trả lời:** —  
**Ngày trả lời:** —  
**Nguồn:** —

---

## Quyết định đã chốt + hệ quả suy ra

*Cập nhật ngay sau mỗi câu trả lời. Hệ quả suy ra là **một phần của câu trả lời** — cấm mở câu hỏi mới cho những nội dung đã nằm ở cột phải, kể cả khi diễn đạt bằng từ đồng nghĩa (`retry` = `gửi lại` = `thử lại`). Không chắc đáp án cũ có bao phủ hay không → hỏi đúng **một** câu xác nhận yes/no, một lần.*

| Quyết định (nguồn) | Hệ quả suy ra trực tiếp — KHÔNG hỏi lại |
| :--- | :--- |
| *QA-01: Lấy lại mật khẩu qua email* | *Không cần cấu hình SMS/OTP cho luồng này; không có màn hình nhập số điện thoại; không có chi phí tin nhắn để ước tính* |
| *QA-06: Không gửi lại khi gửi email thất bại* | *Không có số lần gửi lại; không có khoảng cách giữa các lần gửi lại; không gửi lại cho các kênh khác trong cùng luồng (push, SMS); không có màn hình theo dõi gửi lại; lỗi gửi chỉ ghi nhận một lần* |

---
## Lịch sử cập nhật tài liệu
*Sau mỗi lần nhận phản hồi, BA cập nhật bảng trên và ghi nhận lịch sử tại đây:*
- **Ngày [dd/mm/yyyy]:** Nhận phản hồi lần 1 từ khách hàng cho câu hỏi QA-01. Cập nhật trạng thái sang **Confirmed** và chỉnh sửa tài liệu Phân tích bản đầu tương ứng.
- **Ngày [dd/mm/yyyy]:** QA-04 phụ thuộc QA-02 nên **không** được gửi cho khách hàng vòng này — giữ `Blocked-by QA-02`, dùng chung marker `[PENDING - QA-02]`. Khi QA-02 Confirmed, soát lại QA-04: đáp án đã bao phủ → đóng Confirmed; chưa bao phủ → chuyển Open và đưa vào vòng Q&A kế tiếp.
- **Ngày [dd/mm/yyyy]:** QA-02 (🟡 Non-blocking) vẫn **Open** — BA đã xác nhận tiếp tục sang gate kế tiếp, đánh dấu `[PENDING - QA-02]` trong Analysis tại mục thông báo lỗi đăng nhập.
