@edupia-tutor/spec-driven-docs 0.14.0 → 0.14.2

package/commands/map-testids.tmpl

@@ -1,19 +1,19 @@
-# /map-testids — Define/backfill stable test-ids onto reused & existing FE components
+# /map-testids — Định nghĩa/backfill test-id ổn định lên component FE tái dùng & có sẵn
 
-> Companion to the FE tech-design §2b *Test Selectors* contract. `/generate-tech-docs` (FE) and
-> `/generate-code` assign test-ids to **new** code; this command handles the rest: **reused**
-> catalog components (id lives at the usage site; the component must *forward* a test-id) and
-> **existing / brownfield** screens already coded without test-ids. It reverse-documents what
-> exists, assigns stable ids where missing, ensures reusable components forward an id, records the
-> forwarding in the figma-components catalog, patches usage sites, and writes the §2b map — so QC
-> locates elements by id instead of scanning at runtime.
+> Đồng hành với contract *Test Selectors* §2b của FE tech-design. `/generate-tech-docs` (FE) 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 §2b — để QC
+> định vị element bằng id thay vì scan lúc runtime.
 
 Usage: `/map-testids {UC-ID}`
 
 ## Gate
 {{include:steps/gate.md}}
 
-*Note: For this command, the target in Step 1 is a UC-ID. Read the UC's FE `.feature` (web/app), its Design Spec screens, the FE tech-design `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design-{platform}.md` (if any), and the figma-components catalog for `active_module`.*
+*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ó, FE tech-design `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design-{platform}.md` (nếu có), và figma-components catalog cho `active_module`.*
 
 ## Context
 {{include:steps/context-loader.md}}
@@ -22,60 +22,60 @@ Usage: `/map-testids {UC-ID}`
 
 ## Step 0 — Platform guard
 
-Resolve `platform` from `@trace.platform` / `platform_type`. Test-ids are a **FE/App** concern — if `system` / backend → HALT:
+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 applies to FE/App (web/app) only. BE has no UI test-ids.
+❌ /map-testids chỉ áp dụng cho FE/App (web/app). BE không có UI test-id.
 ```
-Resolve the test-id attribute from `@trace.testid_attr` (or by module): web `data-testid` · React Native `testID` · Flutter `Key`/`Semantics(identifier:)` · native iOS `accessibilityIdentifier`.
+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 — Collect actionable elements
+## Step 1 — Thu thập element có action
 
-From the UC's FE `.feature` `When` steps + the Design Spec screens, list every **actionable** element the scenarios touch (button, input, link, select, toggle, form-submit). Skip static text/labels. For each, resolve the rendering component and classify:
-- **reused** — matches a row in the figma-components catalog (shared design-system component);
-- **existing** — feature-specific component already in the codebase (brownfield);
-- **new** — not yet coded (leave to `/generate-code`; just record the intended id).
+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 — Resolve a stable test-id per element
+## Step 2 — Phân giải test-id ổn định cho mỗi element
 
-- **Existing/brownfield:** read the component file. If the element **already** has a test-id (in the platform attribute) → **reverse-document** it (reuse as-is). Else assign by convention `{uc-lower}-{screen}-{element}-{type}` (e.g. `ft001-login-submit-btn`). Never embed the scenario number.
-- **Reused:** the id is applied at the **usage site** (not baked into the shared component) → assign by the same convention.
-- **Cross-platform:** if the **other** platform's tech-design (`{UC-ID}-tech-design-{web|app}.md`) already has a §2b id for the same logical element, **reuse that id value** (only the attribute differs per platform) so web and app stay consistent and QC logic is portable.
+- **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 tech-design của platform **kia** (`{UC-ID}-tech-design-{web|app}.md`) đã có id §2b 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 — Ensure reusable components forward a test-id (catalog)
+## Step 3 — Đảm bảo component tái dùng forward được test-id (catalog)
 
-For each **reused** actionable component, consult the catalog's **`## Test-ID Forwarding`** section (`{paths.domain_knowledge_dir}/figma-components/{active_module}.md`):
-- **Forwarding prop recorded** → use it at the usage site (Step 4).
-- **Not recorded** → inspect the component source:
-  - Already forwards (spreads `...props` / has a `testId`/`testID` prop / passes the attribute through) → **record** the prop in the catalog's Test-ID Forwarding table.
-  - Does **not** forward → **patch the component ONCE** to accept + forward a test-id (web: add prop `testId` → render `data-testid={testId}`; RN: `testID`; Flutter: pass `Key`/`Semantics(identifier:)`; iOS: `accessibilityIdentifier`), then record it in the 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.
 
-Print every catalog row added and every shared component patched (these touch shared code — call them out for review).
+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 sites (EXTEND only)
+## Step 4 — Patch usage site (chỉ EXTEND)
 
-For each actionable element in this UC's **existing/reused** screens, add the test-id at the usage site — the raw attribute for plain elements, or the forwarding prop for a reused component — with the id from Step 2. **EXTEND mode:** touch only the attribute/prop; do not refactor anything else. Skip elements already carrying the correct id (idempotent).
+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 — Write/refresh the §2b Test Selectors map
+## Step 5 — Ghi/làm mới map §2b Test Selectors
 
-Create or update §2b of `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design-{platform}.md`:
-- If the FE tech-design exists → update its §2b table.
-- If it does **not** exist yet (pure brownfield) → write a minimal file: the `@trace` header (incl `@trace.testid_attr`) + only §2b. `/generate-tech-docs` (FE) fills the remaining sections later; it must not overwrite the §2b ids this command recorded.
+Tạo hoặc cập nhật §2b của `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design-{platform}.md`:
+- Nếu FE tech-design tồn tại → cập nhật bảng §2b của nó.
+- 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`) + chỉ §2b. `/generate-tech-docs` (FE) điền các section còn lại sau; nó không được ghi đè các id §2b mà lệnh này đã ghi.
 
-Each row: `Test-ID | Element | Component (reused/existing/new) | Action | Serves SC`.
+Mỗi row: `Test-ID | Element | Component (reused/existing/new) | Action | Serves SC`.
 
 ## Step 6 — Handoff
 
-If the tech-design lives in the shared spec repo (`spec_source` set), commit + push (2-layer) like `/generate-tech-docs`. Shared-component patches go in the FE service submodule (2-tang push, see Sync & Update §4.4).
+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 Complete — {UC-ID} ({platform})
-Elements: {N} mapped — {reused} reused · {existing} existing (backfilled) · {new} deferred to /generate-code
-Forwarding: {M} shared components patched to forward a test-id · {K} catalog rows recorded
+/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
 §2b: {paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design-{platform}.md updated ({N} selectors)
-Next: /review-tech-docs {tech-design}   ← review the §2b map + shared-component patches
-      /qc-design-test {UC-ID}            ← QC now locates by test-id (no scan)
+Next: /review-tech-docs {tech-design}   ← review map §2b + patch component dùng chung
+      /qc-design-test {UC-ID}            ← QC giờ định vị bằng test-id (không scan)
 ```