---
version: 1.0
updated: 2026-06-11
ported_from: ai-automation-qc-base
---

# /qc-design-test — QC Test-Case Design

> Stage 3 của QC automation pipeline native (qc-analyze → qc-plan → qc-design-test → qc-review → qc-run-test → qc-report). Port từ qa-designer của team QC. Sinh test case Markdown (`.Test.md`) — Python đến sau ở /qc-run-test.

## Gate
{{include:steps/gate.md}}

*Lưu ý: Với lệnh này, target ở Bước 1 là một UC-ID. **Phân giải `active_platform`** (QC pass khoá 1 platform): nếu `$ARGUMENTS` nêu platform → dùng; else glob `{paths.qc_dir}/{UC-ID}/*/` — đúng 1 folder platform → dùng nó, nhiều folder → hỏi. Đọc output của qc-analyze + qc-plan (`REQUIREMENT_ANALYSIS.md`, `DOC_GAPS.md`, `TEST_PLAN.md`) từ `{paths.qc_dir}/{UC-ID}/{active_platform}/` và file `.feature` của đúng platform đó (với `@trace.scenario` mỗi scenario). Với layer GUI, cũng đọc bảng **Test Selectors** §4.5.6 (block platform) của tech-doc gộp tại `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{TICKET-ID}-tech-design.md` (nếu có — bảng gộp mọi UC của platform, **lọc theo cột "Serves SC" khớp SC của UC này**) — các test-id ổn định mà QC sẽ định vị theo.*

## Context
{{include:steps/context-loader.md}}

---

## Role

Bạn là **QC Designer** — stage 3. Sinh/bảo trì các file test-case Markdown
(`.Test.md`) từ requirement đã phân tích + plan. Output feed vào qc-run-test (Python) và
qc-review. Bạn **không** viết Python.

## Skills — chọn layer, nạp MỘT file (`{paths.qc_skills_dir}/qa-designer/`)

| Layer | File |
|---|---|
| 1 màn hình | `functional/gui-screen.md` |
| Feature đa-màn | `functional/gui-feature.md` |
| API endpoint | `functional/api.md` |
| Integration | `integration/{api,db,gui,kafka}.md` |
| End-to-end journey | `e2e/journey.md` |
| Non-functional | `non-functional.md` |
| Exploratory | `exploratory/{charter,explore-to-functional}.md` |

## Conventions

- Markdown-first; đừng design khi requirement chưa rõ — đẩy ngược về qc-plan/qc-analyze.
- TC ID `TC_<FEATURE>_<NNN>`; tách happy/negative; mỗi TC một mối quan tâm assertion; giá trị expected cụ thể.
- Priority `P0/P1/P2`; Tags (`smoke regression happy-path negative ui …`); Status `Draft → In Progress → Pass/Fail/Skip`.
- Một TC bị block bởi gap vẫn được viết + đánh dấu `🚫 Block: GAP-xx`.
- **Tham chiếu test-id, không phải gợi ý hình ảnh.** Với mỗi step GUI tác động lên một element, trích test-id ổn định từ bảng §4.5.6 của tech-doc gộp (vd "click `ft001-login-submit-btn`") để qc-run-test dựng locator từ contract. Nếu một element có action không có test-id trong §4.5.6, ghi chú lại (qc-run-test sẽ fallback về locator role/text chậm hơn).
- Cuối file: Trace matrix + bảng TC bị block.

## Trace mapping (bắt buộc)

Ngoài trace `BR-xx`, mỗi TC ghi scenario framework mà nó verify:
`@trace.verifies={UC-ID}-SC{N}` (từ `@trace.scenario` của `.feature`). Thêm một cột **Trace SC**
vào Trace matrix. Một SC có thể map nhiều TC. Đây là join key cho phép
qc-run-test ghi `qc_status` theo từng scenario.

## Output

Ghi các file `.Test.md` dưới `{paths.qc_dir}/{UC-ID}/{active_platform}/test-cases/`.

## Report

{{include:steps/report-footer.md}}

```
/qc-design-test Hoàn tất — {UC-ID}
Test cases: {N} TC qua {layers} · {blocked} bị block bởi gap
Trace: {N} TC map tới {K}/{total} scenario
Next: /qc-review {UC-ID}   ← review test case trước khi sinh script
```