@shanyucoder/flowgrid 0.1.4 → 0.1.8

package/harness/tests/extracts/wire-test-handoff.md

@@ -0,0 +1,37 @@
+# Wire phase — tests-hub handoff
+
+When **FE `/wire` or `/grill-wire`** finds plan gaps (real API behaviour, status codes, matrix facets), fix on **tests-docs** — not on FE repo.
+
+Hub: `docs/workflows/wire.md#gap-loop` · FE extract: `harness/fe/extracts/wire-audit-loop.md`.
+
+## Triggers from wire audits
+
+| Signal | Tests action |
+|--------|----------------|
+| `audit e2e` `matrixRowsUncovered` for post-wire facet | Extend `TC-*.yaml` `testMatrix` + `steps[]` (real API, no mock) |
+| New error path seen on wire (409, 422 field) | Add negative TC row; mirror bundle `#err:*` |
+| `SC_SCREEN_NO_TC` after wire | `/testcase` under `cases/...` or update `SC-*.yaml` |
+| Plan still describes mock-only setup | Set lifecycle / steps for **wire** runtime; remove mock-only `setup` notes |
+
+## Grill sequence
+
+1. Read full `*.bundle.yaml` on docs (post `/update-spec` if spec changed).
+2. Patch `cases/**/TC-*.yaml` — `traceability`, `testMatrix`, `refs`.
+3. `flowgrid cases:check`
+4. `flowgrid audit testcase <TC.yaml> --bundle <bundle>`
+5. `flowgrid cases:gate --strict --docs-root $FLOWGRID_DOCS_ROOT`
+6. `flowgrid cases:render` (hub 5174)
+7. `/grill-testcase` sign-off for scope
+
+## Back to FE
+
+```text
+testcase:gen --id TC-*   # e2e-root
+/test → scoped test:e2e (post-wire)
+/grill-test → audit e2e
+/grill-wire → full convergence chain
+```
+
+## Spec hole (not test-only)
+
+If AC/UX wrong → paste `/docs-hub /update-spec …` — do not invent business rules on tests hub.

package/harness/tests/skills/grill-testcase/SKILL.md

@@ -6,6 +6,7 @@ disable-model-invocation: true
 
 > [!CRITICAL] MANDATORY PRE-FLIGHT
 > **[MANDATORY]** Re-read this entire `SKILL.md` via file-read tool. STRICTLY FORBIDDEN to rely on memory.
+> **[MANDATORY]** Read `.cursor/extracts/tests-verify-gate.md`, `testcase-plan.md`, and the mode extract matching scope: `grill-screen-tc.md` (one `W-*`), `grill-scenario-flow.md` (`SC-*`), `grill-api-hook.md` (`genType: api-e2e`). After FE wire gaps: also `wire-test-handoff.md`.
 
 # /grill-testcase
 

package/harness/tests/skills/test-api/SKILL.md

@@ -6,7 +6,7 @@ disable-model-invocation: true
 
 > [!CRITICAL] MANDATORY PRE-FLIGHT
 > **[MANDATORY]** Re-read this `SKILL.md` via file-read tool.
-> **[MANDATORY]** Integration contract SSOT on docs-hub: `surfaces/integrations/`, `01-backend-spec` — skills `/api-integration`, `/grill-integration-spec`.
+> **[MANDATORY]** Contract SSOT on docs-hub: `…/api/<seq>/01-backend-spec.yaml` — `/api-spec` then `/grill-api-spec`.
 
 # /test-api — API hook E2E (tests-docs + codegen)
 
@@ -27,11 +27,11 @@ disable-model-invocation: true
 - **[MANDATORY]** `api.baseUrlEnv` (CI env) + `api.baseURL` fallback; optional `api.defaultHeaders`.
 - **[MANDATORY]** `apiSteps[]`: `method`, `path`, `expectStatus`, optional `body`, `headers`, `expectJson`, `expectBodyContains`.
 - **[MANDATORY]** Human `steps[]` + `testMatrix` (same gate as UI TC).
-- Mirror path: `cases/.../integrations/.../TC-*.yaml` aligned with docs integration leaf.
+- Mirror path: `cases/.../<module>/.../TC-*.yaml` aligned with docs API leaf on the same surface.
 
-Template: `harness/tests/templates/TC.example-api.yaml`.
+Template: hub `_templates/TC.example-api.yaml` or `harness/tests/templates/TC.example-api.yaml`.
 
-Audit: `flowgrid audit testcase <TC.yaml> --bundle <integration.bundle.yaml>` when bundle exists on docs hub.
+Audit: `flowgrid audit testcase <TC.yaml> --bundle <*.bundle.yaml>` when bundle exists on docs hub.
 
 ---
 
@@ -53,7 +53,15 @@ Output (e2e-root): `tests/api-e2e/<module>/<TC-id>.api.spec.ts` — run with Pla
 
 - Fix auth (HMAC, rotating tokens) in generated spec or TC `headers` — do not commit secrets; use env in CI.
 - Hybrid UI → API: run UI spec first (or fixture API) then API spec; share `orderId` via `process.env` / `test.info().attach` / storageState as team convention.
-- Postman/Newman collections remain optional; link via TC tag `contract-postman` (no FlowGrid gen yet).
+## Newman / Postman (optional)
+
+- **[MANDATORY]** FlowGrid SSOT remains `TC-*.yaml` (`api-e2e`) — Newman does **not** replace plan or `cases:gate`.
+- Store partner collections under e.g. `integrations/postman/`; CI: `newman run … -e …`.
+- Tag TC: `contract-postman`; document collection path in `description`.
+- Use Newman when: partner-owned collection, heavy pre-request scripts, or contractual replay — **in addition to** Playwright gen for traceability.
+- Grill cross-flow: same `SC-*` may list UI `TC` (e2e) + API `TC` (api-e2e) — `audit scenario` must cover both screens/API refs.
+
+Extract: `.cursor/extracts/grill-api-hook.md`.
 
 ---
 
@@ -61,5 +69,5 @@ Output (e2e-root): `tests/api-e2e/<module>/<TC-id>.api.spec.ts` — run with Pla
 
 - Author plan: `/testcase` (UI), `/scenario` (SC-*)
 - Grill hub: `/grill-testcase`
-- Docs SSOT: `/api-integration`, `/grill-integration-spec`
+- Docs SSOT: `/api-spec`, `/grill-api-spec`
 - UI E2E after skeleton: `/test` + `testcase:gen`

package/harness/tests/skills/testcase/SKILL.md

@@ -7,6 +7,7 @@ disable-model-invocation: true
 > [!CRITICAL] MANDATORY PRE-FLIGHT
 > **[MANDATORY]** Re-read this entire `SKILL.md` via file-read tool. STRICTLY FORBIDDEN to rely on memory.
 > **[MANDATORY]** Read the entire function **`*.bundle.yaml`** (sibling of `ir/` on docs hub) BEFORE authoring any test case. Do not split-read `ir/spec.yaml` + `ir/design.yaml` for coverage traceability.
+> **[MANDATORY]** Read `.cursor/extracts/testcase-plan.md` and golden `TC.example.yaml` from hub `_templates/` (after init) or package `harness/tests/templates/`.
 
 # /testcase — E2E Test Case Authoring (Tests Hub)
 
@@ -91,8 +92,9 @@ disable-model-invocation: true
 - [ ] Function `*.bundle.yaml` read in full (not partial slices).
 - [ ] All `userStories.scenarios` covered by corresponding test cases.
 - [ ] Equivalence Partitioning & Boundary Value Analysis `testMatrix` declared (min/max boundary, regex failure, duplicate 409, double-submit lock, offline preservation).
-- [ ] Scenario markdown (`SC-*.md`) formatted with IEEE 29119 Boundary Analysis Table & Gherkin BDD.
+- [ ] Cross-flow: `refs.scenario` points to existing `SC-*`; per-screen TC still authored via `/testcase` (optional review prose: `SC.example.md` pattern).
 - [ ] `meaning` + `purpose` used for step descriptions.
 - [ ] `id` short; `title` ≤20 chars; `description` is rich and business-meaningful.
 - [ ] YAML syntax valid — no JS expressions in test data values.
 - [ ] Directory structure mirrors docs SSOT path exactly.
+- [ ] `flowgrid cases:render` run so `TC-*.md` exposes steps, testMatrix table, and traceability for QA.

package/harness/tests/templates/TC.example-api.yaml

@@ -1,6 +1,6 @@
 schemaVersion: 2
 id: TC-EXAMPLE-PARTNER-EXPORT
-title: Partner export hook
+title: Partner export
 summary: Ví dụ — đối tác đọc export API sau khi đơn đã sẵn sàng.
 story: |
   Given đơn ORD-EXAMPLE-001 đã được portal xử lý
@@ -38,7 +38,13 @@ steps:
   - Partner gọi GET export với token hợp lệ
   - Hệ thống trả JSON orderId và status
 tags: [integration, partner-api, webhook]
+# contract-postman: integrations/postman/partner-export.json  # optional Newman — see grill-api-hook extract
 automation: automated
+traceability:
+  bundleScreen: API-EXAMPLE-EXPORT-001
+  bundleScenarios: []
+  acceptanceRefs: []
+  actionRefs: []
 dimensions:
   business: [workflow]
   technical: [api]

package/harness/tests/templates/TC.example.yaml

@@ -1,7 +1,10 @@
 schemaVersion: 2
 id: TC-EXAMPLE-VALID
-title: Example flow with valid input should succeed
+title: Valid create flow
 summary: Ví dụ — luồng hợp lệ đi đến trạng thái thành công.
+description: |
+  Member tạo hồ sơ mới với dữ liệu hợp lệ theo ma trận positive_boundary.
+  Kỳ vọng: lưu thành công, thông báo rõ, không mất dữ liệu khi lỗi mạng tạm thời.
 story: |
   Given điều kiện đầu vào hợp lệ và người dùng có quyền
   When thực hiện thao tác nhập liệu và nhấn lưu

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

@@ -0,0 +1,75 @@
+# Template — Testcase plan (`TC-*.yaml`)
+
+**Mục đích:** SSOT **kế hoạch** kiểm thử (hub tests-docs) → `cases:render` → **user case** trên VitePress (port **5174**) → `testcase:gen` → Playwright (e2e-root).
+
+**Workflow:** [docs/workflows/test.md](../../../docs/workflows/test.md) · Artifact: [docs/artifacts/tests-docs.md](../../../docs/artifacts/tests-docs.md).
+
+---
+
+## Ai đọc gì
+
+| Ai | Đọc | Ghi |
+|----|-----|-----|
+| BA / PO | Docs hub `ir/generated/spec.md` (AC, scenarios) | Không sửa `TC-*.yaml` |
+| QA | Tests hub `TC-*.md` (sau render) + YAML SSOT | `/testcase`, `/scenario` |
+| Dev FE | `TC-*.md` + `ir/design.yaml` (`testIds`) | `/test`, `/grill-test` |
+| Dev BE | `TC` `genType: api-e2e` + docs `01` | `/test-api` |
+
+**Không** sửa tay `TC-*.md` — chỉnh YAML → `flowgrid cases:render`.
+
+---
+
+## Path mirror
+
+```text
+docs: surfaces/<surface>/CMP-*/<NN…>/<slug>/*.bundle.yaml
+tests: cases/<surface>/CMP-*/<NN…>/<slug>/TC-*.yaml
+```
+
+Cross-flow: `scenarios/.../FLOW-<name>/SC-*.yaml` mirror `FLOW-*.md` trên docs.
+
+---
+
+## Golden file
+
+Copy shape từ `harness/tests/templates/TC.example.yaml` (sau init tests hub: `.flowgrid/` hoặc package harness path).
+
+Bắt buộc:
+
+- `schemaVersion: 2`
+- `story` / `description` (ngữ cảnh nghiệp vụ)
+- `testMatrix[]` — facet: `positive_boundary`, `negative_length`, `negative_format`, `negative_duplicate`, `concurrency_double_submit`, `network_interruption`
+- `steps[]` — chuỗi bước QA (string hoặc machine step)
+- `traceability` — `bundleScreen`, `bundleScenarios[]`, `acceptanceRefs[]`, `actionRefs[]` (cho `cases:gate --strict`)
+- `testIds.required` — khớp bundle/design sau split
+- `genType: e2e` | `api-e2e`
+
+---
+
+## Trước khi author
+
+1. Đọc **cả** `*.bundle.yaml` trên docs leaf — không chỉ IR.
+2. Bundle thiếu story/AC → STOP → `/update-spec` trên docs hub.
+3. `flowgrid audit testcase <TC> --bundle <bundle>` sau draft.
+
+## Gate release
+
+```text
+flowgrid cases:check
+flowgrid cases:render
+flowgrid cases:gate --strict --docs-root $FLOWGRID_DOCS_ROOT
+```
+
+---
+
+## Grill — chọn mode
+
+| Mode | Extract / workflow |
+|------|-------------------|
+| Một màn `W-*` | `extracts/grill-screen-tc.md` · [test.md#grill-single-screen](../../../docs/workflows/test.md#grill-single-screen) |
+| Flow dài `SC-*` | `extracts/grill-scenario-flow.md` · [test.md#grill-scenario-flow](../../../docs/workflows/test.md#grill-scenario-flow) |
+| API hook | `/test-api` · `extracts/grill-api-hook.md` · Playwright `testcase:gen:api` (+ Newman tùy chọn) |
+
+## Excel UAT
+
+Excel deliverable **xuất sau** YAML/MD chốt — không SSOT ngược. Xem tests-docs § Excel.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shanyucoder/flowgrid",
-  "version": "0.1.4",
+  "version": "0.1.8",
   "description": "Unified Local MCP Toolkit (Graph, DNA, Docs, Test, Codegen)",
   "type": "module",
   "main": "./dist/index.js",

package/stacks/fastapi.json

@@ -45,6 +45,7 @@
     ]
   },
   "registries": [
+    "registries/be-capabilities.registry.json",
     "registries/codegen.registry.json",
     "registries/unit-test.registry.json",
     "registries/common.registry.json"

package/stacks/laravel.json

@@ -42,6 +42,7 @@
   },
   "registries": [
     "registries/codegen.registry.json",
+    "registries/be-capabilities.registry.json",
     "registries/unit-test.registry.json"
   ],
   "gapSources": [

package/stacks/nestjs.json

@@ -0,0 +1,72 @@
+{
+  "stack": "nestjs",
+  "mode": "brownfield",
+  "commands": {
+    "genDry": [
+      "flowgrid",
+      "api-gen:dry",
+      "--",
+      "--spec",
+      "{spec}"
+    ],
+    "gen": [
+      "flowgrid",
+      "api-gen",
+      "--",
+      "--spec",
+      "{spec}"
+    ],
+    "unitGenDry": [
+      "flowgrid",
+      "api-unit-gen:dry",
+      "--",
+      "--spec",
+      "{spec}"
+    ],
+    "unitGen": [
+      "flowgrid",
+      "api-unit-gen",
+      "--",
+      "--spec",
+      "{spec}"
+    ],
+    "registryValidate": [
+      "flowgrid",
+      "api-registry"
+    ]
+  },
+  "registries": [
+    "registries/be-capabilities.registry.json",
+    "registries/nest-codegen.registry.json",
+    "registries/nest-unit-test.registry.json"
+  ],
+  "gapSources": [
+    "**/generated/HANDOFF.md",
+    "**/generated/UNIT-HANDOFF.md",
+    "**/generated/codegen.manifest.json"
+  ],
+  "specRoots": [],
+  "templates": {
+    "root": "adapters/nestjs/nestgen/templates",
+    "engine": "handlebars",
+    "note": "SSOT in FlowGrid package; product registries at repo root"
+  },
+  "dsl": {
+    "ssot": "product-repo",
+    "lanes": {
+      "be": {
+        "registries": ["registries/nest-codegen.registry.json"],
+        "genKeys": ["genDry", "gen"],
+        "needsTags": ["#needs-endpoint", "#needs-dto"]
+      },
+      "unit": {
+        "registries": ["registries/nest-unit-test.registry.json"],
+        "genKeys": ["unitGenDry", "unitGen"],
+        "needsTags": ["#needs-unit-test"]
+      }
+    }
+  },
+  "vocabularies": {
+    "registryTags": "artifactgraph/lexicon/registry-tags.en.txt"
+  }
+}

package/stacks/nextjs-nest.json

@@ -38,6 +38,7 @@
   },
   "registries": [
     "registries/design.registry.json",
+    "registries/be-capabilities.registry.json",
     "registries/nest-codegen.registry.json",
     "registries/contract-field.registry.json"
   ],

package/stacks/nuxt4-nest.json

@@ -48,6 +48,7 @@
     "registries/design.registry.json",
     "registries/unit-test.registry.json",
     "registries/e2e-test.registry.json",
+    "registries/be-capabilities.registry.json",
     "registries/nest-codegen.registry.json",
     "registries/contract-field.registry.json"
   ],

package/templates/project-skeleton/architecture/03-business-process/FLOW-template.md

@@ -15,6 +15,8 @@ status: "draft"
 
 * **Bối cảnh kích hoạt (Trigger Context):** [Mô tả hoàn cảnh hoặc sự kiện nào khiến quy trình này diễn ra. Ví dụ: Khách hàng yêu cầu đặt hàng, hoặc quản trị viên khởi tạo chiến dịch khuyến mãi...]
 * **Mục tiêu kinh doanh (Business Goal):** [Giá trị kinh doanh hoặc bài toán mà quy trình này giải quyết...]
+* **Chỉ số thành công (Success metrics):** [Đo được nếu có — VD: thời gian xử lý, tỷ lệ lỗi, SLA phản hồi]
+* **Phạm vi không làm (Non-goals):** [Quy trình/phase này cố ý không bao gồm — tránh trùng FLOW khác]
 * **Ma trận Vai trò & Quyền hạn (Role & Permission Matrix):**
   | Tác nhân (Actor) | Vai trò trong Quy trình | Quyền hạn trên Màn hình |
   | :--- | :--- | :--- |

package/templates/project-skeleton/overview/index.md

@@ -1,2 +1,68 @@
-# Product Overview
-Welcome to the product overview.
+---
+status: draft
+owner: product-team
+---
+
+# Product overview (arc42 §1 — Introduction & Goals)
+
+Tài liệu **sản phẩm** cho toàn docs hub: *vì sao* hệ thống tồn tại, *ai* dùng, *phạm vi* operational area. Chi tiết màn/API → `surfaces/`; kiến trúc kỹ thuật → `architecture/`.
+
+## Mục tiêu (Goals)
+
+1. **Giá trị nghiệp vụ** — [Một đoạn: bài toán chính product giải quyết.]
+2. **Đối tượng phục vụ** — [Vai trò / operational area chính.]
+3. **Nguyên tắc sản phẩm** — [VD: một SSOT docs, trace `W-*` / `API-*`, grill trước codegen.]
+
+## Stakeholders
+
+| Vai trò | Mục đích đọc overview |
+| --- | --- |
+| PO / BA | Phạm vi, persona, operational area |
+| Dev / QA | Boundary module, link `CMP-*` |
+| Leadership | Goals + success metrics cấp product |
+
+## Top quality goals (arc42)
+
+| # | Thuộc tính | Mục tiêu (đo được nếu có) |
+| --- | --- | --- |
+| 1 | Khả dụng | [VD: uptime SLA nội bộ] |
+| 2 | Bảo mật | [VD: RBAC trên admin portal] |
+| 3 | Khả năng mở rộng | [VD: multi-tenant / module mới không phá SSOT] |
+| 4 | Khả năng bảo trì | [VD: spec bundle + split + audit] |
+| 5 | Trải nghiệm | [VD: affordance UX portal chuẩn] |
+
+## Personas (tóm tắt)
+
+- **[Persona A]** — [Một câu: nhu cầu chính trên surface nào.]
+- **[Persona B]** — […]
+
+Leaf `userStories.primary.asA` **tham chiếu** persona ở đây (không copy persona dài trên từng màn).
+
+## Phạm vi & không làm (product-level)
+
+**In scope (overview):**
+
+- [Operational area / surface được document trong hub này]
+
+**Non-goals (product-level):**
+
+- [VD: không mô tả hạ tầng chi tiết — xem `architecture/`]
+- [VD: không thay quy trình UAT Excel deliverable — xem tests-docs]
+
+## Success metrics (product-level)
+
+- [Chỉ số đo được cấp product — VD: thời gian onboard member đọc SSOT, % leaf có audit sạch trước test lane]
+
+## Operational areas
+
+Mỗi area một file dưới `overview/operational-areas/` — dùng [`_template.md`](./operational-areas/_template.md).
+
+| Area | File |
+| --- | --- |
+| [Tên area] | `operational-areas/<slug>.md` |
+
+## See also
+
+- Surfaces SSOT: `surfaces/`
+- Architecture: `architecture/01-introduction/`
+- Workflow Design: `platform` hoặc `docs/workflows/design.md` (khi publish site)

package/templates/project-skeleton/overview/operational-areas/_template.md

@@ -0,0 +1,37 @@
+---
+id: OA-TEMPLATE
+title: "Tên operational area"
+status: draft
+surfaces: ["admin-web"]
+---
+
+# Operational area: [Tên]
+
+**Mục đích:** [Một đoạn — bối cảnh vận hành: ai làm việc gì, trên kênh nào.]
+
+## Personas trong area
+
+| Persona | Mô tả ngắn | Surface chính |
+| --- | --- | --- |
+| [VD: Nhân viên vận hành] | [Nhu cầu] | `admin-web` |
+
+## Phạm vi nghiệp vụ
+
+- **In scope:** [Quy trình / module thuộc area]
+- **Out of scope:** [Chuyển sang area khác hoặc phase sau]
+
+## Success metrics (area)
+
+- [Metric 1 — đo được]
+- [Metric 2]
+
+## Liên kết module
+
+| CMP | Mô tả |
+| --- | --- |
+| `CMP-XX-…` | [Boundary một dòng] |
+
+## Non-goals
+
+- [Không document chi tiết deployment — `architecture/07-deployment/`]
+- [Không duplicate FLOW kỹ thuật — `architecture/03-business-process/`]

package/templates/project-skeleton/surfaces/common/data-model/index.md

@@ -1,6 +1,14 @@
 # Data model
 
-Shared domain notes (MD). Entity detail for a feature still belongs in that feature’s Code bundle `spec.entities`.
+Shared domain notes (MD) — **bổ trợ** ERD; không thay `common/db-erd.md`.
+
+| Artifact | Vai trò |
+|----------|---------|
+| [`../db-erd.md`](../db-erd.md) | **ERD tổng** (Phase 0, skill `/db-erd`) — Mermaid, entity, ownership |
+| File này + topics | Policy prose (`#derived-data`, journey links) |
+| Leaf `*.bundle.yaml` | **Chi tiết màn:** `spec.entities` + `design.sections[].db` → `ir/design.yaml` |
+
+Workflow: [architecture-data.md](/docs/workflows/architecture-data.md) (path hub khi publish).
 
 ## Topics
 
@@ -9,7 +17,7 @@ Shared domain notes (MD). Entity detail for a feature still belongs in that feat
 ## Journeys vs ER
 
 Runtime sequences live under [`architecture/06-runtime/journeys/`](/architecture/06-runtime/) (`FLOW-*`).  
-When a journey persists data, **link** the relevant entity here or in the owning `CMP-*/code` bundle — **do not** paste ER diagrams into every sequence.
+When a journey persists data, **link** the entity in **`db-erd.md`** — **do not** paste ER diagrams into every sequence or every bundle.
 
 | Journey | Data notes |
 |---------|------------|

package/templates/shared/api-03-mock.stub.yaml

@@ -0,0 +1,14 @@
+# Copy to api/<seq>/03-mock.yaml when prototype/wire needs samples (optional).
+version: 1
+feature: feature-slug
+endpoints:
+  feature.search:
+    samples:
+      - status: 200
+        description: "List success — replace with realistic payload"
+        body:
+          data: []
+          meta:
+            page: 1
+            perPage: 20
+            total: 0

package/templates/shared/backend-api.bundle.yaml

@@ -1,3 +1,6 @@
+# LEGACY: portal-feature-bundle with nested spec.api — do NOT use for new 01 files.
+# New API contract SSOT: api/<seq>/01-backend-spec.yaml from backend-api.yaml + tpl-api-contract.md
+
 schema: portal-feature-bundle/v1
 id: role-domain-function
 title: Feature API

package/templates/shared/backend-api.yaml

@@ -1,3 +1,7 @@
+# SSOT shape for api/<seq>/01-backend-spec.yaml (NOT the screen bundle).
+# Authoring guide: tpl-api-contract.md · Sample only — copy/adapt per leaf.
+# Portal screen bundle: feature.bundle.yaml — do NOT embed spec.api here.
+
 feature:
   id: feature-slug
   title: Feature Title

package/templates/shared/be-capabilities.registry.base.json

@@ -0,0 +1,8 @@
+{
+  "version": 1,
+  "description": "BE base capabilities (auth, exceptions, shared helpers) indexed for DSL / ArtifactGraph. flowgrid registry:sync",
+  "capabilities": {},
+  "middleware": [],
+  "exceptionHandlers": [],
+  "helpers": []
+}

package/templates/shared/bundle-authoring.md

@@ -8,8 +8,10 @@ Hub: `docs/templates/feature.bundle.yaml` · split: `pnpm spec:split`
 |-----|---------|
 | `page-id` | Screen identity (`cmp-adm-000-01`). Split copies this onto `ir/spec.yaml` as `page-id` (not `id`, so it does not collide with requirement/section ids). Legacy bundles may still use `id`. |
 | `summary` | Phải trình bày dạng bullet. Bắt buộc có các tiêu đề (chuẩn Arc42 business): **mục tiêu nghiệp vụ** (business_goals), **các bên liên quan** (stakeholders), **kịch bản người dùng** (user_journey), **bối cảnh** (description, input liên kết cross-page/module, output) và **cách giải quyết** (tùy chọn). Mục đích để 100% Non-tech Stakeholder hiểu và duyệt. |
+| `successMetrics` | **Tùy chọn** khi có thông tin — bullet (string multiline hoặc list). Chỉ số đo được / qualitative metric cấp **màn/feature**. Product-level → `overview/`. Split → `ir/spec.yaml`; render → section riêng trong `ir/generated/spec.md`. |
+| `nonGoals` | **Tùy chọn** — phạm vi **không làm** trên màn/phase (PRD non-goals). Tránh nhét vào `requirements` prose. |
 | `userStories` | **Khối User Stories chuyên sâu cho màn hình:** `primary`, `contextAndHandoff` (+ `screenAccess`), `scenarios` (5 kịch bản chuẩn + **scenario thứ 6 “Affordances UX”** khi màn có delete/filter/breadcrumb/disabled/import — xem `feature.bundle.yaml`), `acceptanceCriteria` (kèm checkbox UX khi áp dụng). **Split:** `pnpm spec:split` copy nguyên khối sang `ir/spec.yaml` (business prose); **không** tự sinh từ `design` — Agent phải cập nhật `userStories` khi bổ sung DSL/`#needs-component`/audit `UX_*`. Render → `## User Stories & Screen Journey` trong Markdown. |
-| `spec` | Design v1 — actors, requirements, `ui.routes`, **`ui.list` / `ui.form` / `ui.detail`**, `acceptance`. **Không** author `spec.api` — API SSOT là `api/<seq>/01-backend-spec.yaml`. |
+| `spec` | Design v1 — **`entities`**, **`relationships`**, actors, requirements, `ui.routes`, **`ui.list` / `ui.form` / `ui.detail`**, `acceptance`. **Không** author `spec.api` — API SSOT là `api/<seq>/01-backend-spec.yaml`. |
 | `gen` | **Bắt buộc trước flowgrid gen:** `codegen.profile` (`auth` login/forgot/reset; `change-password`; `public`; `not-found`/`error`; `list`/`create`/`admin-crud`) + entity/module, `tags`, derived `ui.*`. `/grill-dev` ghi. Endpoint `action` ghi trên **01**, không trên bundle. |
 | `legacy` | Legacy facts + evidence pointers |
 | `design` | Nested **`sections[]`** (card/container/form + `meaning` + `purpose` + `visual` + `interaction` + `validation` + `messages` + `states` + `bind`/`db`) · **`nav`** (`screenAccess` & `sidebar.hierarchy`) · `zones[]` fallback · `behavior` · **`actions[]`** (onSuccess, onSpecificError, backgroundTrigger) |
@@ -36,6 +38,39 @@ Hub: `docs/templates/feature.bundle.yaml` · split: `pnpm spec:split`
 - Missing hard facts → `#missing_info` on that field. Do not wait for grill to invent inventory.
 - `/grill-bqa`, `/grill-dev`, `/grill-docs` only re-check, fill gaps, or fix conflicts.
 
+## Data model — Phase 0 ERD vs screen detail {#data-model--phase-0-erd-vs-screen-detail}
+
+**Phase 0 (không viết trong `/spec` session đầu nếu chưa có):** `/db-erd` → `<LCA>/common/db-erd.md` (Mermaid ER, ownership). Workflow: [architecture-data.md](../../docs/workflows/architecture-data.md).
+
+**Phase 1 — trên leaf bundle (bắt buộc khi field persisted):**
+
+| Chỗ ghi | Nội dung |
+|---------|----------|
+| `spec.entities[]` | Entity **của màn** (name, mô tả ngắn, link entity ER) — mirror subset ERD, không copy full diagram |
+| `spec.relationships[]` | Quan hệ màn này đọc/ghi (optional) |
+| `design.sections[].items[].db` | `schema` (table hoặc tên khớp ERD), `field` (column), `enumMapping` cho select/chip |
+| `design.sections[].items[].bind` | `field` — tên payload form/API (có thể camelCase khác column DB) |
+| `spec.ui.list.columns[]` | `key` khớp `bind.field` hoặc cột DB; cột chỉ tính toán → `#derived-data`, không `db` |
+| `spec.ui.form` / `detail` fields | Cùng quy tắc `bind` + `db` trên từng control |
+
+**Quy tắc:**
+
+- Có `validation` trên control persisted → **phải** có `db.field` (hoặc QA defer) trừ khi field pure UI (`#derived-data`).
+- `meaning` = nghiệp vụ; `db` = vật lý — không gộp một dòng chung trong `requirements`.
+- Split: `entities` + `db` → **`ir/design.yaml`**; BA MD generated **không** render `db` (dev đọc IR / `01`).
+- Grill-dev: `01.modules[].entities[].fields` phải **khớp** tập `db.field` màn (review tay; `#update:*` khi đổi).
+
+**Không:** dump SQL migration; thay `db-erd.md` bằng `entities: []` rỗng khi form có >3 field persisted.
+
+**Review (multi-table):**
+
+| Artifact | Ai đọc |
+|----------|--------|
+| `design.dataModel` | BA/lead — vai trò từng bảng (`tables[].roleOnScreen`, `summary`) — mẫu [tpl-screen-data-model.md](./tpl-screen-data-model.md) |
+| `ir/generated/data-model.md` | Sau `flowgrid split` — bảng/cột gom theo `schema`; link từ `spec.md` |
+| `api/.../01-backend-spec.yaml` | BE codegen — `modules[].entities[]` + `fields[]` khớp `db` trên design |
+| `flowgrid audit spec` | `confirms[]` `CONFIRM_DB_*` → AskQuestion (extract `db-audit-wizard.md`); không chặn split |
+
 ## spec (design v1) — có
 
 - `actors`, `entities`, `relationships`
@@ -76,8 +111,9 @@ Authoring (`/spec`, grill-*) still **writes** `*.bundle.yaml`, then split.
 | `*.bundle.yaml` | **Ghi** `/spec`, grill-*; **đọc cả file** `/testcase`, `/grill-testcase` | Đầy đủ spec+gen+design+`userStories`; tests hub read-only |
 | `ir/design.yaml` | **Đọc cả file** — grill-*, FE `/prototype`, codegen | Tech sau split; `api` chiếu từ 01. |
 | `ir/spec.yaml` | VitePress + stakeholder | Business page + requirements/acceptance. Không id/tag/bind. `"Q&A"`. Không stub `legacy` rỗng. |
-| `…/api/<seq>/01-backend-spec.yaml` | BE `/api`, `openapi:gen`, **author API** | Tech BE — SSOT duy nhất cho endpoint |
-| `<slug>.md` | Người (BA/QA) | Render từ **`ir/spec.yaml`** (chưa split thì không có trang) |
+| `…/api/<seq>/01-backend-spec.yaml` | BE `/api`, `openapi_gen`, **author API** | Tech BE — SSOT duy nhất cho endpoint |
+| `ir/generated/data-model.md` | BA/lead/BE review | Bảng/cột theo `schema` (multi-table); sinh từ `ir/design.yaml` |
+| `ir/generated/spec.md` · `ir/generated/api.md` | BA/QA/Dev review (VitePress) | Render từ `ir/spec.yaml` + `01`; hướng dẫn API: [tpl-api-contract.md](./tpl-api-contract.md) |
 
 Không còn `ir/legacy.yaml`. `legacy:` trên `ir/spec.yaml` chỉ khi có evidence thật.