improve BA skill

.claude/skills/ba-3-specification/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ba-3-specification
-description: Giai đoạn 3 của quy trình BA — viết đặc tả chi tiết tới mức dev code được và QA test được. Viết SRS/FRD cho một hoặc nhiều User Story, với PART 2 thay đổi theo loại sản phẩm - màn hình và bảng field (screen), endpoint và hợp đồng dữ liệu (api-service), luồng dữ liệu và data contract (data-pipeline), metric và ngưỡng chấp nhận (ml-model), lịch và idempotency (batch-job) - cộng acceptance criteria Given/When/Then đủ cả luồng lỗi, bảng mã lỗi, yêu cầu phi chức năng, API contract. Kích hoạt khi người dùng nói "viết SRS", "đặc tả US này", "viết acceptance criteria", "field spec", "bảng mã lỗi", "NFR", "API contract", "data contract", "spec cho dev", "ngưỡng chấp nhận cho mô hình". Input là BACKLOG đã qua G2; output vào ba-output/<PROJECT>/03-specification/ và phải qua Gate G3 (Ready for Dev) trước khi dev bắt đầu.
+description: Giai đoạn 3 của quy trình BA — viết đặc tả chi tiết tới mức dev code được và QA test được. Viết SRS/FRD cho một hoặc nhiều User Story, với PART 2 thay đổi theo loại sản phẩm - màn hình và bảng field (screen), endpoint và hợp đồng dữ liệu (api-service), luồng dữ liệu và data contract (data-pipeline), metric và ngưỡng chấp nhận (ml-model), lịch và idempotency (batch-job) - cộng acceptance criteria Given/When/Then đủ cả luồng lỗi, bảng mã lỗi, yêu cầu phi chức năng, API contract; với sản phẩm có giao diện còn sinh quy ước giao diện cấp project (UICONV) và wireframe low-fi (WF markdown + HTML) đối chiếu với prototype nếu có. Kích hoạt khi người dùng nói "viết SRS", "đặc tả US này", "viết acceptance criteria", "field spec", "bảng mã lỗi", "NFR", "API contract", "data contract", "spec cho dev", "ngưỡng chấp nhận cho mô hình", "wireframe", "bố cục màn hình", "đối chiếu prototype", "quy ước UI". Input là BACKLOG đã qua G2 (+ prototype/design system nếu có); output vào ba-output/<PROJECT>/03-specification/ và phải qua Gate G3 (Ready for Dev) trước khi dev bắt đầu.
 ---
 
 # GĐ3 · SPECIFICATION — Đặc tả chi tiết
@@ -10,7 +10,10 @@ Mục tiêu: **viết tới mức dev code được mà không phải đoán, QA
 Đây là sản phẩm chính của nghề BA và là gate nghiêm nhất. Một chỗ mơ hồ lọt qua G3 sẽ
 thành một bug hoặc một CR — với chi phí gấp nhiều lần chi phí làm rõ ở đây.
 
-Output: `SRS` · `AC` · `NFR` · `API` (+ `WF` nếu có) trong `ba-output/<PROJECT>/03-specification/`
+Output: `SRS` · `AC` · `NFR` · `API` trong `ba-output/<PROJECT>/03-specification/`.
+Khi `PRODUCT = screen` thêm: `UICONV` (một lần cho cả project, ở `00-index/`) và `WF` (mỗi US,
+gồm `.md` + `.html` low-fi) — hai artifact này là phần **thay vai trò design ở mức bố cục và
+trạng thái** khi dự án có prototype tham chiếu, và là **đề xuất chờ Designer duyệt** khi không có.
 
 ## Bốn nguyên tắc bất di bất dịch
 
@@ -44,21 +47,34 @@ Ví dụ minh hoạ cho từng bước, ở nhiều domain khác nhau: `examples
 4. **Phạm vi lần chạy** — liệt kê đích danh `US` sẽ đặc tả. **Quá 3 US một lần chạy thì
    chất lượng giảm rõ rệt** — đề xuất chia.
 5. **Biến thể PART 2 sẽ nạp** — theo `PRODUCT` (Bước 2). US có nhiều loại ⇒ nêu đủ.
-6. **Guideline dự án cần tuân thủ** — tìm và nêu: quy ước UI, bộ NFR chuẩn, glossary, danh
-   sách mã lỗi đã dùng. Không có ⇒ nói rõ sẽ tự định nghĩa và cần ai duyệt.
+6. **Guideline dự án cần tuân thủ** — tìm và nêu: `00-index/UICONV_<PROJECT>.md`, quy ước UI
+   sẵn có của dự án (vd `GLOBAL_UI_CONVENTION.md`), bộ NFR chuẩn, glossary, danh sách mã lỗi
+   đã dùng. **Chưa có `UICONV` mà `PRODUCT = screen` ⇒ lần chạy này phải sinh nó trước (Bước 8)**
+   và nêu ai duyệt (Designer + PO).
 7. **Ngôn ngữ hiển thị** — chỉ hỏi khi `PRODUCT` có giao diện cho người. Không có ⇒ ghi N/A.
+8. **Prototype / design system tham chiếu** — chỉ khi `PRODUCT = screen`. Tìm theo thứ tự:
+   tham số `--proto`, thư mục `design/` hoặc `prototype/` trong repo, mục *Thiết kế giao diện*
+   của SAD (`docs/sections/07-*.md`, `docs/SAD.md` §7), file Figma/HTML/ảnh người dùng đưa.
+   Trình bảng `Nguồn | Định dạng | Phiên bản | Phủ màn hình nào`. Không có ⇒ nói rõ **WF sẽ là
+   đề xuất của BA và cần Designer duyệt trước G3**; có ⇒ prototype là nguồn sự thật về bố cục.
 
-Rồi **hỏi xác nhận** bảy điểm trên.
+Rồi **hỏi xác nhận** tám điểm trên.
 
 Bỏ qua khi lệnh có `go`.
 
-## Thực hiện — 7 bước
+## Thực hiện — 9 bước
+
+Bước 1–7 cho mọi `PRODUCT`. Bước 8–9 chỉ khi `PRODUCT = screen`; loại khác ghi "N/A" trong
+báo cáo cuối, không bỏ im lặng.
 
 ### Bước 1 — Khung SRS và tóm tắt nghiệp vụ
 
 Dùng `templates/srs.md`. **Không bỏ mục nào** — mục không áp dụng thì ghi "N/A" kèm lý do,
 đừng xoá; xoá mục làm người đọc không biết là đã cân nhắc hay đã quên.
 
+Với `PRODUCT = screen`: §2.3.6 (trạng thái), §4.3 (định dạng) và mọi quy ước phân trang, toast,
+vị trí nút **tham chiếu `UICONV`** thay vì định nghĩa lại. Muốn khác ⇒ ghi vào `UICONV` §12.
+
 Viết mục **Tóm tắt nghiệp vụ** cho PO đọc: US này giải quyết `RQ` nào, người dùng được gì,
 khác hiện tại chỗ nào. Ngôn ngữ nghiệp vụ, không có tên bảng dữ liệu, không có tên component.
 Đây là hiện thực hoá quy tắc W10 — một tài liệu, ba người đọc.
@@ -215,9 +231,60 @@ Ba điểm phải chốt, hay bị bỏ:
 - **Thời gian** dạng gì, múi giờ nào — UTC hay giờ địa phương?
 - **Phân trang** offset hay cursor, có `hasNext`/`total` không?
 
+### Bước 8 — Quy ước giao diện cấp project (`UICONV`) — chỉ `screen`
+
+Dùng `templates/ui-convention.md`, ghi vào `00-index/UICONV_<PROJECT>.md`. **Sinh một lần** ở
+lần chạy ba-3 đầu tiên của project; các lần sau chỉ đọc và bổ sung §10 (dãy mã lỗi), §11 (từ
+vựng thành phần), §12 (ngoại lệ).
+
+Nguồn điền, theo thứ tự ưu tiên: design system của dự án > prototype tham chiếu > guideline
+sẵn có > **hỏi** (ghi `OQ`, không tự chọn). Mọi ô "chọn một" phải chọn xong — còn dấu `/`
+giữa các phương án là chưa làm.
+
+🔴 `UICONV` là **hợp đồng giữa BA và Design**: BA sở hữu text và trạng thái, Design sở hữu
+layout và từ vựng thành phần. Cả hai ký. Dự án không có Designer ⇒ PO ký thay và ghi `DEC-nn`.
+
+### Bước 9 — Wireframe & bố cục (`WF`) — chỉ `screen`
+
+Dùng `templates/wireframe.md` (bảng) + `templates/wireframe.html` (render low-fi). Ghi
+`WF_<US>_v1.0.md` và `WF_<US>_v1.0.html` vào `03-specification/`. Làm **sau** Bước 3 và 5, vì
+WF chỉ sắp xếp những thành phần và text đã có trong SRS.
+
+**Hai chế độ, phải khai rõ ở dòng `Nguồn bố cục` của header:**
+
+| Chế độ | Khi nào | WF là gì | Ai duyệt |
+|---|---|---|---|
+| 🎨 **Prototype tham chiếu** | Có Figma / HTML / ảnh / mô tả UI đã duyệt | **Bản ghi lại** bố cục của prototype bằng bảng + đối chiếu với SRS | PO (Designer đã duyệt prototype) |
+| ✏️ **BA tự dựng** | Không có prototype | **Đề xuất** bố cục theo `UICONV` | **Designer bắt buộc** ở `standard`+ |
+
+Bốn việc, theo thứ tự:
+
+1. **Bản đồ prototype ↔ SCR** (§1): mỗi màn hình trong `SRS` §2.1 có trong prototype không,
+   ở frame/trang nào. Màn hình prototype không có ⇒ BA tự dựng phần đó và đánh dấu.
+2. **Bảng vùng + vị trí thành phần** (§3.x.1–2) cho **mọi** `SCR`, kể cả modal và trang lỗi.
+   🔴 Tập `C-id` phải **khớp hai chiều** với bảng thành phần `SRS` §2.3.1 — chạy
+   `grep -o "C[0-9][0-9]"` trên cả hai file và so tập. Thành phần có trong prototype mà SRS
+   không có ⇒ **không tự thêm vào SRS**, ghi lệch ở §5 cho PO quyết.
+3. **Trạng thái, responsive, tương tác trình bày** (§3.x.3–6): hai trạng thái rỗng phải **trông**
+   khác nhau; mọi con số (ms, s, px) có nguồn `UICONV`/prototype, không có ⇒ `OQ`.
+4. **Sinh HTML** từ bảng: mỗi `SCR` một `<section id>`, mỗi vùng `data-zone`, mỗi thành phần
+   `data-c` đúng C-id, mỗi trạng thái một khối `data-state`. Thành phần **chỉ có ở prototype**
+   (lệch loại Tồn tại ở §5) vẽ đúng chỗ prototype đặt nó bằng `<span class="proto-only"
+   data-ref="WF §5 #n">`, **không gán `data-c`** — khung đỏ đứt để PO nhìn thấy ngay quyết định
+   còn thiếu. Giữ nguyên `<style>`/`<script>` của template để mọi WF trong project trông giống
+   nhau. Không màu thương hiệu, không font.
+
+**§5 Lệch prototype ↔ SRS là mục quan trọng nhất của WF.** Phân loại: Tồn tại · Hành vi · Bố
+cục · Text · Trạng thái thiếu. Bên thắng theo W11: SRS thắng Tồn tại/Hành vi/Text; prototype
+thắng Bố cục. Lệch Tồn tại/Hành vi chưa có người quyết ⇒ 🔴 chặn G3. Bảng rỗng vẫn phải ghi
+"đã đối chiếu n màn hình, không lệch".
+
+Điều **không** làm ở bước này: chọn màu, font, icon, khoảng cách chính xác, motion — ghi vào
+§6 "Designer còn phải làm". Có prototype phủ hết ⇒ ghi "Không".
+
 ## Trước khi kết thúc
 
-In năm thứ:
+In năm thứ (sáu khi `PRODUCT = screen`):
 
 **① Bảng truy vết** `US` → `AC` → `BR` → `field` → `mã lỗi`. Ô trống là chỗ chưa đặc tả xong.
 
@@ -234,10 +301,17 @@ bảng ràng buộc của PART 2 hoặc trong bảng mã lỗi ⇒ G3 không th
 
 **⑤ `OQ` mở** — cái nào ảnh hưởng tới hành vi hệ thống thì đánh dấu 🔴 chặn G3.
 
+**⑥ Đối chiếu WF ↔ SRS ↔ UICONV** *(chỉ `screen`)* — in: tập `C-id` lệch hai chiều (phải rỗng) ·
+số dòng §5 của WF theo loại và số dòng chưa có người quyết · mục nào của SRS định nghĩa lại
+thứ đã có trong `UICONV` mà không có dòng ở `UICONV` §12 · WF đang ở chế độ 🎨 hay ✏️ và
+Designer đã ký chưa.
+
 Nhắc chữ ký theo `RIGOR` (`../ba-lifecycle/references/workflow.md` §2 — G3):
 `light` không cần chữ ký QA · `standard` cần **PO + Tech Lead + QA** · `strict` thêm
 **Bảo mật/Pháp chế**, và API **phải do BE xác nhận**, không chấp nhận contract BA tự đề xuất.
 Ở mức `standard` trở lên, QA phải xác nhận *mọi AC đều test được*.
+`PRODUCT = screen` ở `standard`+ thêm **Designer** ký `UICONV` và `WF` (WF ở chế độ 🎨 thì
+Designer đã duyệt prototype, chỉ cần PO xác nhận bản đồ §1 và §5 không còn lệch mở).
 
 ## Bẫy thường gặp
 
@@ -250,6 +324,15 @@ sai. Mỗi field phải truy về một `BR` hoặc một câu trả lời của
 **Mô tả hành vi bằng ảnh.** Wireframe minh hoạ bố cục; hành vi nằm ở bảng thành phần và AC
 (quy tắc W11). Viết "xem hình" ở cột hành vi là chưa đặc tả.
 
+**Chép prototype vào SRS.** Prototype có nút mà backlog không có ⇒ đó là scope creep bằng hình
+ảnh. Ghi vào WF §5, để PO quyết, không tự thêm thành phần vào bảng SRS.
+
+**Mỗi SRS tự đặt quy ước.** Phân trang, vị trí toast, định dạng ngày phải tham chiếu `UICONV`.
+Ba SRS với ba kiểu phân trang là ba màn hình người dùng phải học lại.
+
+**WF không có bảng lệch.** WF chỉ có hình mà không có §5 là chưa đối chiếu — và đúng chỗ
+prototype khác SRS là chỗ dev sẽ tự chọn một bên.
+
 **Trộn "ẩn" với "disable".** Ba trạng thái khác nhau (W7), và người dùng phản ứng rất khác:
 nút biến mất làm họ tưởng mất quyền, nút mờ có tooltip làm họ hiểu vì sao chưa bấm được.