@shanyucoder/flowgrid 0.1.8 → 0.1.10

package/templates/shared/qa-authoring.md

@@ -0,0 +1,78 @@
+# flowgrid-qa-item/v1 — authoring rules (QA inbox)
+
+Hub template: `.flowgrid/templates/qa-item.yaml` (sau `flowgrid init`) · Workflow: `docs/workflows/qa-team.md`
+
+## File naming
+
+| Part | Rule | Example |
+|------|------|---------|
+| **SHORT** | Slug màn/module, ổn định, `A-Z0-9` + `-` | `HOTEL-LIST`, `ADM-AUTH` |
+| **NNNN** | Tăng dần theo SHORT (0001…) | `0001`, `0002` |
+| **Path** | `qa/<SHORT>_<NNNN>.yaml` | `qa/HOTEL-LIST_0001.yaml` |
+| **id** | **Bắt buộc** = basename không `.yaml` | `HOTEL-LIST_0001` |
+
+Legacy id `QA-<page-id>-NNNN` vẫn đọc được — file mới dùng `<SHORT>_NNNN`.
+
+Gợi ý SHORT từ `W-HOTEL-LIST` → `HOTEL-LIST` (bỏ prefix `W-`). Team có thể chọn slug module cố định (vd. `ADM-AUTH` cho nhiều màn auth).
+
+## Top-level fields
+
+| Key | Required | Purpose |
+|-----|----------|---------|
+| `schema` | yes | Luôn `flowgrid-qa-item/v1` |
+| `id` | yes | Khớp tên file |
+| `status` | yes | `open` \| `closed` |
+| `target.path` | yes | Bundle hoặc `01-backend-spec.yaml` (repo-relative) |
+| `target.at` | yes | Pointer field — gắn `#missing_info <id>` / `#tech-debt:<id>` |
+| `updates` | yes | Timeline append-only (≥1 dòng) |
+| `screen` | khuyến nghị | `W-*` hoặc `page-id` — catalog + split |
+| `bundleId` | khi legacy | `page-id` bundle để `Q&A` trên `ir/spec.yaml` |
+| `kind` | khuyến nghị | `customer` \| `choice` \| `tech-debt` \| `integration` \| `coverage` |
+| `skill` | khuyến nghị | Skill mở gap: `spec`, `grill-dev`, `api-spec`, … |
+| `options` | optional | Copy options AskQuestion khi mở (audit) |
+| `tags` | optional | Mirror tag đã gắn trên spec |
+
+## `updates[]` (append-only)
+
+**Không** sửa/xóa dòng cũ. Chỉ **thêm** cuối mảng.
+
+| `kind` | Ai / khi |
+|--------|----------|
+| `question` | Mở QA (Log Tech Debt) — **dòng đầu** |
+| `answer` | `/qa-resolve` — sau khi patch `target.at` |
+| `review` | `/qa-review` — `approved:` hoặc `needs-change:` |
+| `note` | Ghi chú, không đổi spec |
+
+| `at` | Format **bắt buộc** | `20260930 08:00` (YYYYMMDD HH:mm) |
+| `by` | Member / role | `ba-lead`, `middle-dev` |
+| `text` | Nội dung | Block `\|` multiline |
+
+### Vòng đời status
+
+- Mở file: `status: open`, `updates[0].kind: question`
+- `/qa-resolve`: append `answer`, `status: closed`, gỡ tag trên spec
+- `/qa-review` + `needs-change`: append `review`, **`status: open`** lại (cùng file)
+
+## Agent workflow (mở QA)
+
+1. Đọc **whole** `.flowgrid/templates/qa-item.yaml` + file này.
+2. Chọn SHORT (team convention hoặc từ `screen`).
+3. `nextQaId(hub, SHORT)` hoặc glob `qa/<SHORT>_*.yaml` → max NNNN + 1.
+4. Copy template → `qa/<SHORT>_<NNNN>.yaml`; set `id`, `target`, `at` now, `updates[0]`.
+5. Patch spec: `#missing_info <id>` trên field `target.at`.
+6. `flowgrid split` + `flowgrid render`.
+
+## Agent output
+
+- **YAML only** khi tạo/sửa QA file — không markdown giải thích trong repo.
+- Quote string có `:`; multiline dùng `|`.
+
+## Không dùng QA file cho
+
+- ADR → `architecture/09-decisions`
+- Risk dài hạn → `architecture/11-risks`
+- `openQuestions` trên bundle — **cấm**
+
+## Schema
+
+Validate (optional CI): `templates/schemas/qa-item.schema.json` · `flowgrid` test `validateQaItem`.

package/templates/shared/qa-item.yaml

@@ -1,15 +1,36 @@
-# Copy to qa/open/QA-<bundle.id>-NNNN.yaml — do not leave this file in qa/open/.
-id: QA-cmp-adm-002-02-01-02-0001
-kind: customer # customer | choice | tech-debt
-skill: spec # spec | grill-bqa | grill-dev | grill-docs | api-spec | api-update
+# flowgrid-qa-item/v1 — Authoring: qa-authoring.md · Hub: docs/workflows/qa-team.md
+# Copy to qa/<SHORT>_NNNN.yaml (id = basename without .yaml). Append-only updates[].
+
+schema: flowgrid-qa-item/v1
+id: HOTEL-LIST_0001
+screen: W-HOTEL-LIST
+bundleId: cmp-adm-000-01-01
+status: open
+kind: tech-debt
+skill: spec
+tags:
+  - "#missing_info HOTEL-LIST_0001"
 target:
-  path: surfaces/<surface>/CMP-*/<NN…>/<slug>.bundle.yaml
-  at: design.zones.main.items.title.purpose
-question: |
-  What is still unknown?
-options: []
-# - id: a
-#   text: Option A
-#   recommended: true
-# - id: other
-#   text: Member supplies copy
+  path: surfaces/<surface>/CMP-*/<slug>.bundle.yaml
+  at: design.sections.main.items.filter_timezone.purpose
+options:
+  - label: "(Recommended) Theo timezone property"
+    recommended: true
+  - label: Theo locale user
+updates:
+  - at: "20260930 08:00"
+    by: <member-id>
+    kind: question
+    text: |
+      Filter timezone lấy theo property hay user locale?
+# Append only — never delete or rewrite prior lines:
+#  - at: "20260930 10:00"
+#    by: ba-lead
+#    kind: answer
+#    text: |
+#      Theo property TZ; label UTC+7 trên UI.
+#  - at: "20261001 08:00"
+#    by: senior
+#    kind: review
+#    text: |
+#      needs-change: thêm AC khi property chưa set TZ.

package/templates/shared/tpl-api-contract.md

@@ -6,7 +6,7 @@
 
 ---
 
-## Đọc trước khi viết (global)
+## Read before writing (global)
 
 | Ai | Đọc gì trên VitePress / docs hub | Khi nào mở YAML `01` |
 |----|-----------------------------------|----------------------|
@@ -19,7 +19,7 @@ Sau `flowgrid split` + `flowgrid render`: sidebar leaf **Spec · W-*** · **Data
 
 ---
 
-## Bộ trio trên function leaf
+## Function leaf trio
 
 ```text
 surfaces/<surface>/CMP-*/<NN…>/<slug>/
@@ -42,7 +42,7 @@ surfaces/<surface>/CMP-*/<NN…>/<slug>/
 
 ---
 
-## Cấu trúc `01` (tóm tắt field)
+## `01` structure (field summary)
 
 Mẫu đầy đủ: [`backend-api.yaml`](./backend-api.yaml) (sau `flowgrid init` → `.flowgrid/templates/backend-api.yaml`).
 
@@ -108,15 +108,15 @@ Skill: `/openapi` · Redoc/Swagger UI: `openapi_build_ui` (tùy hub).
 
 ---
 
-## YAML an toàn
+## Safe YAML
 
 - Chuỗi có `:` → bọc `"..."`.
 - Chạy `flowgrid api:check` trước handoff.
-- Thiếu fact → AskQuestion hoặc `qa/open/` — **không** `openQuestions` trong YAML.
+- Thiếu fact → AskQuestion hoặc `qa/` — **không** `openQuestions` trong YAML.
 
 ---
 
-## Liên kết bundle FE
+## FE bundle link
 
 Trên bundle chỉ khai báo **hành vi UI** và `apiRefs`; chi tiết endpoint nằm trên `01`:
 

package/templates/tests-skeleton/catalog/locale.yaml

@@ -1,16 +1,17 @@
-memberLocale: vi
+# Overwritten on scaffold — English headings; prose in TC YAML uses contentLocale.
+structureLocale: en
+contentLocale: vi
 headings:
-  vi:
-    home: Trang chủ
-    cases: Testcase
-    scenarios: Scenario
-    plans: Kế hoạch kiểm thử
-    preconditions: Điều kiện tiên quyết
-    steps: Các bước thực hiện
-    expected: Kết quả mong đợi
-    traceability: Liên kết docs (traceability)
-    testMatrix: Ma trận kiểm thử
-    crossRefDocs: Đối chiếu docs hub
-    technical: Chi tiết kỹ thuật
-    testData: Dữ liệu kiểm thử
-    coverage: Phạm vi coverage
+  home: Home
+  cases: Test cases
+  scenarios: Scenarios
+  plans: Test plans
+  preconditions: Preconditions
+  steps: Steps
+  expected: Expected results
+  traceability: Traceability (docs SSOT)
+  testMatrix: Test matrix (equivalence)
+  crossRefDocs: Docs hub cross-reference
+  technical: Technical details
+  testData: Test data
+  coverage: Coverage

package/templates/tests-skeleton/tpl-testcase-plan.md

@@ -1,9 +1,9 @@
-# Testcase plan — hướng dẫn hub
+# Testcase plan — hub guide
 
-Bản đầy đủ (toolkit): sau `flowgrid init` copy từ package `harness/tests/templates/tpl-testcase-plan.md` hoặc xem repo FlowGrid `templates/tests-skeleton/tpl-testcase-plan.md` (sync với harness).
+Full toolkit copy: `harness/tests/templates/tpl-testcase-plan.md` (synced with this skeleton).
 
-- SSOT ghi: `cases/**/TC-*.yaml`
-- SSOT đọc team: `cases:render` → `TC-*.md` trên VitePress (`flowgrid dev` port 5174)
-- Đối chiếu nghiệp vụ: docs hub `FLOWGRID_DOCS_ROOT` — bundle + `ir/generated/spec.md`
+- **SSOT write:** `cases/**/TC-*.yaml` — field names **English**; narrative in `contentLocale` (`catalog/locale.yaml`).
+- **SSOT read:** `cases:render` → `TC-*.md` on VitePress (`flowgrid dev`, port 5174).
+- **Business alignment:** docs hub — bundle + `ir/generated/spec.md`. Product copy values live in bundle `i18n:`, not in TC prose.
 
-Mẫu vàng: `TC.example.yaml` (init / harness templates).
+Golden example: `TC.example.yaml` (init / harness templates).