@educa-corp/sdd-framework 0.5.0 → 0.7.0

package/commands/map-testids.tmpl

@@ -1,81 +0,0 @@
-# /map-testids — Định nghĩa/backfill test-id ổn định lên component FE tái dùng & có sẵn
-
-> Đồng hành với contract *Test Selectors* §4.5.6 của tech-doc gộp. `/generate-tech-docs` và
-> `/generate-code` gán test-id cho code **mới**; lệnh này lo phần còn lại: component catalog
-> **tái dùng** (id sống ở usage site; component phải *forward* được test-id) và màn
-> **đã có / brownfield** đã code mà chưa có test-id. Nó reverse-document những gì đang có,
-> gán id ổn định ở chỗ còn thiếu, đảm bảo component tái dùng forward được id, ghi việc
-> forwarding vào figma-components catalog, patch các usage site, và ghi map §4.5.6 — để QC
-> định vị element bằng id thay vì scan lúc runtime.
-
-Usage: `/map-testids {UC-ID}`
-
-## Gate
-{{include:steps/gate.md}}
-
-*Lưu ý: Với lệnh này, target ở Bước 1 là một UC-ID. Đọc `.feature` FE của UC (web/app), các màn Design Spec của nó, tech-doc gộp `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{TICKET-ID}-tech-design.md` (§4.5.6 của platform, nếu có — bảng này gộp mọi UC của platform, **lọc theo cột "Serves SC" khớp SC của UC này** qua §10), và figma-components catalog cho `active_module`.*
-
-## Context
-{{include:steps/context-loader.md}}
-
----
-
-## Step 0 — Platform guard
-
-Phân giải `platform` từ `@trace.platform` / `platform_type`. Test-id là chuyện của **FE/App** — nếu `system` / backend → HALT:
-```
-❌ /map-testids chỉ áp dụng cho FE/App (web/app). BE không có UI test-id.
-```
-Phân giải attribute test-id từ `@trace.testid_attr` (hoặc theo module): web `data-testid` · React Native `testID` · Flutter `Key`/`Semantics(identifier:)` · native iOS `accessibilityIdentifier`.
-
-## Step 1 — Thu thập element có action
-
-Từ các step `When` trong `.feature` FE của UC + các màn Design Spec, liệt kê mọi element **có action** mà scenario chạm tới (button, input, link, select, toggle, form-submit). Bỏ qua text/label tĩnh. Với mỗi cái, phân giải component render và phân loại:
-- **reused** — khớp một row trong figma-components catalog (component design-system dùng chung);
-- **existing** — component riêng của feature đã có trong codebase (brownfield);
-- **new** — chưa code (để `/generate-code` lo; chỉ ghi lại id dự kiến).
-
-## Step 2 — Phân giải test-id ổn định cho mỗi element
-
-- **Existing/brownfield:** đọc file component. Nếu element **đã** có test-id (trong attribute của platform) → **reverse-document** nó (dùng lại as-is). Nếu không, gán theo quy ước `{uc-lower}-{screen}-{element}-{type}` (vd `ft001-login-submit-btn`). Không bao giờ nhúng số scenario.
-- **Reused:** id được áp ở **usage site** (không bake vào component dùng chung) → gán theo cùng quy ước.
-- **Cross-platform:** nếu §4.5.6 của platform **kia** (block `web`/`app` trong cùng tech-doc gộp) đã có id cho cùng element logic, **dùng lại id value đó** (chỉ attribute khác theo platform) để web và app nhất quán và logic QC tái dùng được.
-
-## Step 3 — Đảm bảo component tái dùng forward được test-id (catalog)
-
-Với mỗi component **reused** có action, tra section **`## Test-ID Forwarding`** của catalog (`{paths.domain_knowledge_dir}/figma-components/{active_module}.md`):
-- **Đã ghi prop forwarding** → dùng nó ở usage site (Step 4).
-- **Chưa ghi** → kiểm tra source component:
-  - Đã forward (spread `...props` / có prop `testId`/`testID` / truyền attribute qua) → **ghi** prop vào bảng Test-ID Forwarding của catalog.
-  - **Không** forward → **patch component MỘT LẦN** để nhận + forward test-id (web: thêm prop `testId` → render `data-testid={testId}`; RN: `testID`; Flutter: truyền `Key`/`Semantics(identifier:)`; iOS: `accessibilityIdentifier`), rồi ghi vào catalog.
-
-In mọi row catalog được thêm và mọi component dùng chung được patch (chúng đụng code dùng chung — nêu ra để review).
-
-## Step 4 — Patch usage site (chỉ EXTEND)
-
-Với mỗi element có action trong các màn **existing/reused** của UC này, thêm test-id ở usage site — attribute thô cho element thường, hoặc prop forwarding cho component tái dùng — với id từ Step 2. **EXTEND mode:** chỉ đụng attribute/prop; không refactor gì khác. Bỏ qua element đã mang đúng id (idempotent).
-
-## Step 5 — Ghi/làm mới map §4.5.6 Test Selectors
-
-Tạo hoặc cập nhật §4.5.6 (block platform tương ứng) trong tech-doc gộp `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{TICKET-ID}-tech-design.md`:
-- Nếu tech-doc tồn tại → cập nhật bảng §4.5.6 của platform này (thêm block §4.5 cho platform nếu chưa có).
-- Nếu **chưa** tồn tại (pure brownfield) → ghi một file tối thiểu: header `@trace` (gồm `@trace.testid_attr`) + §4.5.6. `/generate-tech-docs` điền các section còn lại sau; nó không được ghi đè các id §4.5.6 mà lệnh này đã ghi.
-
-Mỗi row: `Test-ID | Element | Component (reused/existing/new) | Action | Serves SC`.
-
-## Step 6 — Handoff
-
-Nếu tech-design sống trong spec repo dùng chung (`spec_source` được set), commit + push (2 tầng) như `/generate-tech-docs`. Patch component dùng chung đi vào FE service submodule (push 2 tầng, xem Sync & Update §4.4).
-
-## Output
-
-{{include:steps/report-footer.md}}
-
-```
-/map-testids Hoàn tất — {UC-ID} ({platform})
-Elements: {N} mapped — {reused} reused · {existing} existing (backfilled) · {new} để dành cho /generate-code
-Forwarding: {M} component dùng chung được patch để forward test-id · {K} row catalog được ghi
-§4.5.6: {paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{TICKET-ID}-tech-design.md updated ({N} selectors, {platform})
-Next: /review-tech-docs {tech-design}   ← review map §4.5.6 + patch component dùng chung
-      /qc-design-test {UC-ID}            ← QC giờ định vị bằng test-id (không scan)
-```